Package: notionhq-client
Notion SDK for PythonA simple and easy to use client for theNotion APIThis client is meant to be a Python version of the referenceJavaScript SDK,
so usage should be pretty similar between both. 😊📢Announcement(14-08-2021) — 0.6.0 is now released and adds support for
therecent Notion API changes.
Upgrading should be seamless from 0.4.0 onwards.Installationpipinstallnotion-clientUsageBefore getting started,create an integrationand find the token.→ Learn more about authorization.Import and initialize a client using anintegration tokenor an
OAuthaccess token.importosfromnotion_clientimportClientnotion=Client(auth=os.environ["NOTION_TOKEN"])In an asyncio environment, use the asynchronous client instead:fromnotion_clientimportAsyncClientnotion=AsyncClient(auth=os.environ["NOTION_TOKEN"])Make a request to any Notion API endpoint.See the complete list of endpoints in theAPI reference.frompprintimportpprintlist_users_response=notion.users.list()pprint(list_users_response)or with the asynchronous client:list_users_response=awaitnotion.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 errorsIf the API returns an unsuccessful response, anAPIResponseErrorwill be raised.The error contains properties from the response, and the most helpful iscode.
You can comparecodeto the values in theAPIErrorCodeobject to avoid
misspelling error codes.importloggingfromnotion_clientimportAPIErrorCode,APIResponseErrortry:my_page=notion.databases.query(**{"database_id":"897e5a76-ae52-4b48-9fdf-e71f5945d1af","filter":{"property":"Landmark","text":{"contains":"Bridge",},},})exceptAPIResponseErroraserror:iferror.code==APIErrorCode.ObjectNotFound:...# For example: handle by asking the user to select a different databaseelse:# Other error handling codelogging.exception()LoggingThe 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 response bodies,
set thelog_leveloption tologging.DEBUG.notion=Client(auth=os.environ["NOTION_TOKEN"],log_level=logging.DEBUG,)You may also set a customloggerto emit logs to a destination other thanstdout.
Have a look atPython's logging cookbookif you want to create your own logger.Client optionsClientandAsyncClientboth support the following options on initialization.
These options are all keys in the single constructor parameter.OptionDefault valueTypeDescriptionauthNonestringBearer token for authentication. If left undefined, theauthparameter should be set on each request.log_levellogging.WARNINGintVerbosity of logs the instance will produce. By default, logs are written tostdout.timeout_ms60_000intNumber of milliseconds to wait before emitting aRequestTimeoutErrorbase_url"https://api.notion.com"stringThe root URL for sending API requests. This can be changed to test with a mock server.loggerLog to consolelogging.LoggerA custom logger.RequirementsThis package supports the following minimum versions:Python >= 3.7httpx >= 0.15.0Earlier versions may still work, but we encourage people building new applications
to upgrade to the current stable.Getting helpIf you have a question about the library, or are having difficulty using it,
chat with the community inGitHub Discussions.If you're experiencing issues with the Notion API, such as a service interruption
or a potential bug in the platform, reach out toNotion help.