// the find
ramnes/notion-sdk-py
Notion API client SDK, rewritten in Python! (sync + async)
A thin Python wrapper around the official Notion API, mirroring the structure of Notion's own JavaScript SDK. Both sync and async clients are supported via httpx, and the library stays deliberately close to the raw API rather than abstracting it into a higher-level ORM. Good fit for anyone building Notion integrations who wants something that won't drift from the upstream API spec.
The sync/async parity is clean — same method signatures, same ergonomics, just swap Client for AsyncClient. Pagination helpers (iterate_paginated_api, collect_paginated_api) are a genuine quality-of-life win over manual cursor loops. The retry logic handles 429 and idempotent-only 500/503 correctly — retrying POST on a 500 would be a footgun and it doesn't. VCR cassette tests mean the suite runs fast and offline without mocking the whole world by hand.
Returns raw dicts throughout, so callers get no type safety or autocomplete on response fields — you're always guessing whether a key exists or spelunking the Notion docs. The is_full_* helpers partially address this but add ceremony without solving the underlying problem. The library tracks the official API version, which means it inherits Notion's own instability: the API has renamed and restructured endpoints multiple times (databases → data_sources is visible right in the test cassettes), so upgrades can break callsites silently. No higher-level abstractions for common patterns like building rich_text arrays or block trees means a lot of boilerplate for anyone doing non-trivial page construction.