A Python Client for the Official Notion API, With Sync and Async Support

If you've ever tried to work with Notion's API from Python, you know the drill: you either write your own HTTP wrapper or wrestle with a library that doesn't quite match the official documentation. The Notion API is well-documented, but having a proper Python client makes a real difference. That's exactly what notion-sdk-py provides.

What It Does

notion-sdk-py is a client library for the official Notion API, designed to be the Python equivalent of the reference JavaScript SDK. If you've used the JS version, the usage patterns here should feel immediately familiar—same structure, same approach, just Python.

The library supports both synchronous and asynchronous clients. You import Client for regular use or AsyncClient if you're working in an asyncio environment. Every API endpoint is available in both versions, so you're not locked into one paradigm. You initialize a client with an integration token or OAuth access token, and from there you can make requests to any Notion API endpoint through a clean, consistent interface.

One design decision worth noting: endpoint parameters are grouped into a single object rather than being split across path, query, and body arguments. This means you don't have to remember where each parameter belongs—you just pass them all together.

Why It's Cool

There are a few things that make this library worth a look:

• It mirrors the official JavaScript SDK. The project explicitly states it's meant to be a Python version of the reference JS SDK, so usage should be very similar between both. If you're already familiar with the JS version (or working in a codebase that uses it), the mental overhead of switching to Python is minimal. The maintainers even invite you to open an issue or PR if you find discrepancies.

• Sync and async, no compromises. Some libraries treat async as an afterthought. Here, all API endpoints are available in both the synchronous and asynchronous clients. If you're building something with asyncio, you won't hit a wall where certain endpoints just aren't available.

• Parameter handling that respects your time. The single-object parameter grouping is a small thing, but it adds up. You don't need to consult the docs every time to figure out whether a parameter goes in the path, query string, or request body. You just pass what you need.

• It's actively maintained and tested. The README shows badges for code quality, test coverage, and documentation builds. There's a Codecov badge, CI workflows for testing and quality checks, and the project uses Black for code formatting. These aren't guarantees, but they're good signals that the project takes maintenance seriously.

• Straightforward installation and setup. It's on PyPI as notion-client, so installation is a single pip command. No build steps, no dependency wrangling.

How to Try It

Getting started is about as simple as it gets:

1. Install the package:

pip install notion-client

1. If you haven't already, follow Notion's Getting Started Guide to set up your integration and get a token.

2. Import and initialize the client:

import os
from notion_client import Client

notion = Client(auth=os.environ["NOTION_TOKEN"])

Or, if you're in an asyncio environment:

from notion_client import AsyncClient

notion = AsyncClient(auth=os.environ["NOTION_TOKEN"])

1. Make a request to any Notion API endpoint. Here's a synchronous example:

from pprint import pprint

list_users_response = notion.users.list()
pprint(list_users_response)

And the async version:

list_users_response = await notion.users.list()
pprint(list_users_response)

You'll get back a dictionary with the response data—something like a list of users with their IDs, names, and types.

For endpoints with parameters, you pass them as a single object:

my_page = notion.data_sources.query(
    **{
        "data_source_id": "897e5a76-ae52-4b48-9fdf-e71f5945d1af",
        "filter": {
            "property": "Landmark",
            "rich_text": {
                "contains": "Bridge",
            },
        },
    }
)

The README also notes that error handling is covered, though the truncated content doesn't show the full details—you'll want to check the repo for that.

You can find the project at github.com/ramnes/notion-sdk-py.

Final Thoughts

If you're building anything in Python that talks to Notion, this library is a sensible default. It's not trying to be clever or reinvent the API—it's giving you a clean, predictable interface that matches the official SDK's patterns. The sync and async support means it fits into whatever architecture you're working with, and the parameter grouping removes a common source of friction. It's best suited for developers who want to spend their time building features, not writing HTTP boilerplate. If that's you, give it a look.