notion-client api
notion-sdk-py is a simple and easy to use client library for the official Notion API.
It is meant to be a Python version of the reference JavaScript SDK, so usage should be pretty similar between both.
Announcement (18-04-2022) Notion API is officially out of beta, and we are too: 1.0.0 is now released! Beware, Notion-Version has been upgraded to 2022-02-22 and it brings breaking changes.
Installation
pip install notion-client
Usage
Import and initialize a client using an integration token or an OAuth access token.
import os from notion_client import Client notion = Client ( auth = os . environ [ "NOTION_TOKEN" ])
In an asyncio environment, use the asynchronous client instead:
from notion_client import AsyncClient notion = AsyncClient ( auth = os . environ [ "NOTION_TOKEN" ])
Make a request to any Notion API endpoint.
See the complete list of endpoints in the API reference.
from pprint import pprint list_users_response = notion . users . list () pprint ( list_users_response )
or with the asynchronous client:
list_users_response = await notion . users . list () pprint ( list_users_response )
This would output something like:
{'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.
my_page = notion . databases . query ( ** { "database_id" : "897e5a76-ae52-4b48-9fdf-e71f5945d1af" , "filter" : { "property" : "Landmark" , "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.
import logging from notion_client import APIErrorCode , APIResponseError try : my_page = notion . databases . query ( ** { "database_id" : "897e5a76-ae52-4b48-9fdf-e71f5945d1af" , "filter" : { "property" : "Landmark" , "text" : { "contains" : "Bridge" , }, }, } ) except APIResponseError as error : if error . code == APIErrorCode . ObjectNotFound : ... # For example: handle by asking the user to select a different database else : # Other error handling code logging . exception ()
Logging
The client emits useful information to a logger. By default, it only emits warnings and errors.
If you're debugging an application, and would like the client to log request & response bodies, set the log_level option to logging.DEBUG .
notion = Client ( auth = os . environ [ "NOTION_TOKEN" ], log_level = logging . DEBUG , )
You may also set a custom logger to emit logs to a destination other than stdout . Have a look at Python's logging cookbook if you want to create your own logger.
Client options
Client and AsyncClient both support the following options on initialization. These options are all keys in the single constructor parameter.
Option Default value Type Description auth None string Bearer token for authentication. If left undefined, the auth parameter should be set on each request. log_level logging.WARNING int Verbosity of logs the instance will produce. By default, logs are written to stdout . timeout_ms 60_000 int Number of milliseconds to wait before emitting a RequestTimeoutError base_url "https://api.notion.com" string The root URL for sending API requests. This can be changed to test with a mock server. logger Log to console logging.Logger A custom logger.
Requirements
This package supports the following minimum versions:
Python >= 3.7
httpx >= 0.15.0
Earlier versions may still work, but we encourage people building new applications to upgrade to the current stable.
Getting help
If you have a question about the library, or are having difficulty using it, chat with the community in GitHub Discussions.
If you're experiencing issues with the Notion API, such as a service interruption or a potential bug in the platform, reach out to Notion help.
It is meant to be a Python version of the reference JavaScript SDK, so usage should be pretty similar between both.
Announcement (18-04-2022) Notion API is officially out of beta, and we are too: 1.0.0 is now released! Beware, Notion-Version has been upgraded to 2022-02-22 and it brings breaking changes.
Installation
pip install notion-client
Usage
Import and initialize a client using an integration token or an OAuth access token.
import os from notion_client import Client notion = Client ( auth = os . environ [ "NOTION_TOKEN" ])
In an asyncio environment, use the asynchronous client instead:
from notion_client import AsyncClient notion = AsyncClient ( auth = os . environ [ "NOTION_TOKEN" ])
Make a request to any Notion API endpoint.
See the complete list of endpoints in the API reference.
from pprint import pprint list_users_response = notion . users . list () pprint ( list_users_response )
or with the asynchronous client:
list_users_response = await notion . users . list () pprint ( list_users_response )
This would output something like:
{'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.
my_page = notion . databases . query ( ** { "database_id" : "897e5a76-ae52-4b48-9fdf-e71f5945d1af" , "filter" : { "property" : "Landmark" , "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.
import logging from notion_client import APIErrorCode , APIResponseError try : my_page = notion . databases . query ( ** { "database_id" : "897e5a76-ae52-4b48-9fdf-e71f5945d1af" , "filter" : { "property" : "Landmark" , "text" : { "contains" : "Bridge" , }, }, } ) except APIResponseError as error : if error . code == APIErrorCode . ObjectNotFound : ... # For example: handle by asking the user to select a different database else : # Other error handling code logging . exception ()
Logging
The client emits useful information to a logger. By default, it only emits warnings and errors.
If you're debugging an application, and would like the client to log request & response bodies, set the log_level option to logging.DEBUG .
notion = Client ( auth = os . environ [ "NOTION_TOKEN" ], log_level = logging . DEBUG , )
You may also set a custom logger to emit logs to a destination other than stdout . Have a look at Python's logging cookbook if you want to create your own logger.
Client options
Client and AsyncClient both support the following options on initialization. These options are all keys in the single constructor parameter.
Option Default value Type Description auth None string Bearer token for authentication. If left undefined, the auth parameter should be set on each request. log_level logging.WARNING int Verbosity of logs the instance will produce. By default, logs are written to stdout . timeout_ms 60_000 int Number of milliseconds to wait before emitting a RequestTimeoutError base_url "https://api.notion.com" string The root URL for sending API requests. This can be changed to test with a mock server. logger Log to console logging.Logger A custom logger.
Requirements
This package supports the following minimum versions:
Python >= 3.7
httpx >= 0.15.0
Earlier versions may still work, but we encourage people building new applications to upgrade to the current stable.
Getting help
If you have a question about the library, or are having difficulty using it, chat with the community in GitHub Discussions.
If you're experiencing issues with the Notion API, such as a service interruption or a potential bug in the platform, reach out to Notion help.
Comentarios
Publicar un comentario