Description

<!-- markdownlint-disable -->  <div align="center"> <p> <a href="https://pypi.org/project/notion-client"><img src="https://img.shields.io/pypi/v/notion-client.svg" alt="PyPI"></a> <a href="tox.ini"><img src="https://img.shields.io/pypi/pyversions/notion-client" alt="Supported Python Versions"></a> <br/> <a href="LICENSE"><img src="https://img.shields.io/github/license/ramnes/notion-sdk-py" alt="License"></a> <a href="https://github.com/ambv/black"><img src="https://img.shields.io/badge/code%20style-black-black" alt="Code style"></a> <a href="https://codecov.io/github/ramnes/notion-sdk-py"><img src="https://codecov.io/gh/ramnes/notion-sdk-py/branch/main/graphs/badge.svg" alt="Coverage"></a> <a href="https://pypistats.org/packages/notion-client"><img src="https://img.shields.io/pypi/dm/notion-client" alt="Package downloads"></a> <br/> <a href="https://github.com/ramnes/notion-sdk-py/actions/workflows/quality.yml"><img src="https://github.com/ramnes/notion-sdk-py/actions/workflows/quality.yml/badge.svg" alt="Code Quality"></a> <a href="https://github.com/ramnes/notion-sdk-py/actions/workflows/test.yml"><img src="https://github.com/ramnes/notion-sdk-py/actions/workflows/test.yml/badge.svg" alt="Tests"></a> <a href="https://github.com/ramnes/notion-sdk-py/actions/workflows/docs.yml"><img src="https://github.com/ramnes/notion-sdk-py/actions/workflows/docs.yml/badge.svg" alt="Docs"></a> </p> </div> <!-- markdownlint-enable --> **_notion-sdk-py_ is a simple and easy to use client library for the official [Notion API](https://developers.notion.com/).** It is meant to be a Python version of the reference [JavaScript SDK](https://github.com/makenotion/notion-sdk-js), so usage should be very similar between both. 😊 (If not, please open an issue or PR!) <!-- markdownlint-disable --> ## Installation <!-- markdownlint-enable --> ```shell pip install notion-client ``` ## Usage > Use Notion's [Getting Started Guide](https://developers.notion.com/docs/getting-started) > to get set up to use Notion's API. Import and initialize a client using an **integration token** or an OAuth **access token**. ```python import os from notion_client import Client notion = Client(auth=os.environ["NOTION_TOKEN"]) ``` In an asyncio environment, use the asynchronous client instead: ```python from notion_client import AsyncClient notion = AsyncClient(auth=os.environ["NOTION_TOKEN"]) ``` Make a request to any Notion API endpoint. ```python from pprint import pprint list_users_response = notion.users.list() pprint(list_users_response) ``` > [!NOTE] > See the complete list of endpoints in the [API reference](https://developers.notion.com/reference). or with the asynchronous client: ```python list_users_response = await notion.users.list() pprint(list_users_response) ``` This would output something like: ```text {'results': [{'avatar_url': 'https://secure.notion-static.com/e6a352a8-8381-44d0-a1dc-9ed80e62b53d.jpg', 'id': 'd40e767c-d7af-4b18-a86d-55c61f1e39a4', 'name': 'Avocado Lovelace', 'object': 'user', 'person': {'email': 'avo@example.org'}, 'type': 'person'}, ...]} ``` All API endpoints are available in both the synchronous and asynchronous clients. Endpoint parameters are grouped into a single object. You don't need to remember which parameters go in the path, query, or body. ```python my_page = notion.data_sources.query( **{ "data_source_id": "897e5a76-ae52-4b48-9fdf-e71f5945d1af", "filter": { "property": "Landmark", "rich_text": { "contains": "Bridge", }, }, } ) ``` ### Handling errors If the API returns an unsuccessful response, an `APIResponseError` will be raised. The error contains properties from the response, and the most helpful is `code`. You can compare `code` to the values in the `APIErrorCode` object to avoid misspelling error codes. ```python import logging from notion_client import APIErrorCode, APIResponseError, Client try: notion = Client(auth=os.environ["NOTION_TOKEN"]) my_page = notion.data_sources.query( **{ "data_source_id": "897e5a76-ae52-4b48-9fdf-e71f5945d1af", "filter": { "property": "Landmark", "rich_text": { "contains": "Bridge", }, }, } ) except APIResponseError as error: if error.code == APIErrorCode.ObjectNotFound: # # For example: handle by asking the user to select a different data source # ... else: # Other error handling code print(error) ``` ### Logging The cli