Introducing notion-sdk-py
notion-sdk-py is a straightforward client library designed to make interactions with the official Notion API easy and efficient for Python developers. Intended as a Python equivalent to the JavaScript SDK, it provides an intuitive interface for accessing Notion’s powerful API capabilities in a familiar way for Python users.
Recent Updates
The library is actively maintained, as shown by recent updates. For example, version 2.2.1 released on December 28, 2023, introduced improvements to iteration helpers, and version 2.2.0 added features such as the ability to remove icons and covers from pages, and introduced a new filter_properties option for retrieving pages.
Installation
To start using notion-sdk-py, simply install it using pip:
pip install notion-client
Getting Started
To integrate Notion's API into your Python project, follow Notion's Getting Started Guide. Begin by importing and initializing a client with an integration token or an OAuth access token, allowing for synchronous or asynchronous operations.
Synchronous Client Example:
import os
from notion_client import Client
notion = Client(auth=os.environ["NOTION_TOKEN"])
Asynchronous Client Example:
from notion_client import AsyncClient
notion = AsyncClient(auth=os.environ["NOTION_TOKEN"])
Making API Requests
Once set up, you can interact with Notion’s API by making requests to different endpoints. For instance, to list users:
Synchronous Request:
from pprint import pprint
list_users_response = notion.users.list()
pprint(list_users_response)
Asynchronous Request:
list_users_response = await notion.users.list()
pprint(list_users_response)
Error Handling
Errors are managed by raising an APIResponseError when API requests are unsuccessful. Developers can check the error's code against predefined codes in APIErrorCode for accurate error handling.
import logging
from notion_client import APIErrorCode, APIResponseError
try:
# Example API call
my_page = notion.databases.query(database_id="example_id")
except APIResponseError as error:
if error.code == APIErrorCode.ObjectNotFound:
# Handle object not found error
...
else:
# Log other errors
logging.error(error)
Logging
For debugging purposes, developers can adjust the logging level using the log_level option. This configuration allows for detailed log outputs, including request and response bodies, to assist with deeper analysis.
import logging
notion = Client(
auth=os.environ["NOTION_TOKEN"],
log_level=logging.DEBUG,
)
Advanced Features
The library supports full API responses, utility functions for dealing with paginated APIs, and provides various client options to customize the client to suit specific needs.
Client Configuration Options
| Option | Default value | Description |
|---|---|---|
auth | None | Authentication token required for making requests. |
log_level | logging.WARNING | Defines the verbosity of log outputs. |
timeout_ms | 60_000 | Timeout duration in milliseconds for requests. |
base_url | "https://api.notion.com" | Base URL for API requests. Useful for testing with mock servers. |
logger | Default console logger | Allows setting a custom logger for more control over log outputs. |
Testing the Library
The notion-sdk-py library supports testing through pytest. To conduct tests across all Python environments, the tox command can be used. Tests simulate real API requests, requiring environment variables NOTION_TOKEN and NOTION_TEST_PAGE_ID for setup.
System Requirements
To ensure compatibility, the library supports Python version 3.7 and above, and requires httpx version 0.15.0 or newer.
Getting Help
Should you encounter issues or wish to request features for the Notion API, you can email the developers at [email protected]. For problems specific to this library, you are encouraged to submit an issue on its GitHub repository.
In summary, notion-sdk-py bridges the gap between Notion's extensive API and Python developers, offering a user-friendly and feature-complete experience to enhance productivity and workflow automation within Notion environments.