notion-sdk-py - Python 客户端库简化 Notion API 集成

notion-sdk-py 是一个简单易用的官方 Notion API 客户端库。

它旨在成为参考 JavaScript SDK 的Python版本，因此两者的使用方式应该非常相似。😊（如果不是，请提出问题或PR！）

📢 公告 (2023-12-28) — 2.2.1版本已发布，修复了迭代辅助函数。

2.2.0版本（2023-12-26）的新特性：

现在可以从页面中删除图标和封面。

在 notion.pages.retrieve 中添加了 filter_properties。

现在可以在迭代辅助函数中传递自定义的 start_cursor。

安装

pip install notion-client

使用方法

使用Notion的入门指南来设置使用Notion API。

使用集成令牌或OAuth 访问令牌导入并初始化客户端。

import os
from notion_client import Client

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

在异步环境中，使用异步客户端：

from notion_client import AsyncClient

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

向任何Notion API端点发送请求。

完整的端点列表请参见API参考。

from pprint import pprint

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

或者使用异步客户端：

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

这将输出类似以下内容：

{'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'},
             ...]}

所有API端点在同步和异步客户端中都可用。

端点参数被分组到一个单一对象中。你不需要记住哪些参数属于路径、查询或正文。

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

错误处理

如果API返回unsuccessful响应，将会抛出 APIResponseError。

错误包含来自响应的属性，其中最有用的是 code。你可以将 code 与 APIErrorCode 对象中的值进行比较，以避免拼写错误代码。

import logging
from notion_client import APIErrorCode, APIResponseError

try:
    my_page = notion.databases.query(
        **{
            "database_id": "897e5a76-ae52-4b48-9fdf-e71f5945d1af",
            "filter": {
                "property": "Landmark",
                "rich_text": {
                    "contains": "Bridge",
                },
            },
        }
    )
except APIResponseError as error:
    if error.code == APIErrorCode.ObjectNotFound:
        ...  # 例如：通过要求用户选择不同的数据库来处理
    else:
        # 其他错误处理代码
        logging.error(error)

日志记录

客户端向日志记录器发送有用的信息。默认情况下，它只发送警告和错误。如果你正在调试应用程序，并希望客户端记录请求和响应主体，请将 log_level 选项设置为 logging.DEBUG。

notion = Client(
    auth=os.environ["NOTION_TOKEN"],
    log_level=logging.DEBUG,
)

你还可以设置自定义的 logger 将日志发送到 stdout 以外的目标。如果你想创建自己的日志记录器，请查看 Python 的日志记录操作指南。

客户端选项

Client 和 AsyncClient 在初始化时都支持以下选项。这些选项都是构造函数单一参数中的键。

选项	默认值	类型	描述
`auth`	`None`	`string`	用于身份验证的Bearer令牌。如果未定义，应在每个请求中设置 `auth` 参数。
`log_level`	`logging.WARNING`	`int`	实例将产生的日志详细程度。默认情况下，日志写入 `stdout`。
`timeout_ms`	`60_000`	`int`	在发出 `RequestTimeoutError` 之前等待的毫秒数
`base_url`	`"https://api.notion.com"`	`string`	发送API请求的根URL。可以更改此项以使用模拟服务器进行测试。
`logger`	输出到控制台	`logging.Logger`	自定义日志记录器。

完整的API响应

以下函数可以区分完整和部分API响应。

函数	用途
`is_full_page`	判断对象是否为完整的页面对象
`is_full_block`	判断对象是否为完整的块对象
`is_full_database`	判断对象是否为完整的数据库对象
`is_full_page_or_database`	判断对象是否为完整的页面对象或数据库对象
`is_full_user`	判断对象是否为完整的用户对象
`is_full_comment`	判断对象是否为完整的评论对象

from notion_client.helpers import is_full_page

full_or_partial_pages = await notion.databases.query(
    database_id="897e5a76-ae52-4b48-9fdf-e71f5945d1af"
)

for page in full_or_partial_pages["results"]:
    if not is_full_page_or_database(page):
        continue
    print(f"创建时间：{page['created_time']}")

实用函数

这些函数可以帮助处理任何分页API。

iterate_paginated_api(function, **kwargs) 及其异步版本 async_iterate_paginated_api(function, **kwargs) 将任何分页API转换为生成器。

function 参数必须接受 start_cursor 参数。例如：notion.blocks.children.list。

from notion_client.helpers import iterate_paginated_api

for block in iterate_paginated_api(
    notion.databases.query, database_id="897e5a76-ae52-4b48-9fdf-e71f5945d1af"
):
    # 对块进行操作
    ...

如果你不需要生成器，collect_paginated_api(function, **kwargs) 及其异步版本 async_collect_paginated_api(function, **kwargs) 具有与之前函数相同的行为，但返回分页API的所有结果列表。

from notion_client.helpers import collect_paginated_api

all_results = collect_paginated_api(
    notion.databases.query, database_id="897e5a76-ae52-4b48-9fdf-e71f5945d1af"
)