notion-client

notion-client (the PyPI name for the notion-sdk-py project) is a Python port of Notion’s official JavaScript SDK, giving Python developers a Client and AsyncClient that cover every documented Notion API endpoint — pages, blocks, databases, data sources, users, comments, search, and webhooks — without needing to hand-roll HTTP requests. Endpoint parameters are grouped into a single call so callers don’t need to remember which fields belong in the path, query string, or request body.

The library ships built-in error handling via a typed APIResponseError and APIErrorCode enum, configurable logging, and automatic retries with exponential backoff and jitter for rate limits (429) and transient server errors (500/503), retrying idempotent methods only where safe. Helper functions like is_full_page and is_full_block let callers distinguish full versus partial API responses, and named constants (DEFAULT_BASE_URL, DEFAULT_TIMEOUT_MS, MIN_VIEW_COLUMN_WIDTH) are exported for direct use in application code.

What You Get

• Both Client (sync) and AsyncClient (async) classes covering every documented Notion API endpoint, sharing an identical interface
• Automatic retries with exponential backoff and jitter for rate-limited (429) and transient server errors (500/503), scoped to idempotent methods
• A typed APIResponseError exception with an APIErrorCode enum for precise error handling instead of string matching
• Helper functions (is_full_page, is_full_block, is_full_data_source, is_full_user, is_full_comment) to distinguish full from partial API responses
• Exported constants (DEFAULT_BASE_URL, DEFAULT_TIMEOUT_MS, MIN_VIEW_COLUMN_WIDTH) and configurable logging via a log_level or custom logger

Common Use Cases

• Building internal tools or bots that read and write Notion pages, databases, and blocks programmatically
• Syncing external data sources into Notion databases via scheduled scripts using the synchronous Client
• High-throughput async integrations (e.g. web backends) that query Notion concurrently using AsyncClient
• Handling Notion webhook payloads in a typed way via the dedicated webhooks module

Under The Hood

Architecture - The library centers on notion_client/client.py, which defines the shared request-building logic used by both Client and AsyncClient, dispatching to endpoint-grouped methods declared in api_endpoints.py (e.g. notion.data_sources.query(...), notion.users.list()). Cross-cutting concerns are isolated into dedicated modules: errors.py for typed exceptions and error codes, constants.py for default configuration values, logging.py for request/response log formatting, helpers.py for full/partial response predicates, and webhooks.py for handling incoming Notion webhook events.

Tech Stack - Pure Python (100% of the repo), built on httpx for both sync and async HTTP transport (enabling a single codebase to serve both client variants), with full type hints throughout (py.typed marker) and dataclass-based response typing per the GitHub topics.

Code Quality - The tests/ directory uses recorded HTTP cassettes (tests/cassettes/) to replay real API interactions deterministically in test_endpoints.py, alongside focused unit tests for errors, webhooks, helpers, and the client itself (test_errors.py, test_webhooks.py, test_helpers.py, test_client.py), with Black formatting, a Codecov-tracked coverage badge, and separate CI workflows for quality, tests, and docs.

API Design - The client intentionally mirrors the official JavaScript SDK’s shape so behavior and method names transfer directly between languages, groups all endpoint parameters (path, query, body) into a single keyword-argument call so callers never need to remember Notion’s HTTP layout, and documents retry, logging, and error-handling configuration clearly in the README with runnable examples for both sync and async usage.