notion_kit

notion_kit is a lightweight Python SDK wrapper around notion-client. It keeps the official Client object and adds object-oriented helpers for common Notion API workflows.

中文文档是本仓库的维护源和事实基准；英文文档是展示和同步版本。中英文含义不一致时，以中文文档为准。

Documentation

• 中文文档
• English documentation
• 完整 API 使用文档
• Complete API usage reference
• 使用场景文档
• Scenario guides

Project Governance

• Security policy
• Contributing guide
• Local live-test configuration template: env.example

Install

pip install notion-kit

For local development:

pip install -e .

Quick Start

import os

from notion_kit import Kit as nkit

notion = nkit.Client(token=os.environ["NOTION_TOKEN"])
page_id = nkit.get_id("<NOTION_PAGE_URL>")
page = nkit.Page.get_data(page_id)

print(page.id)

Supported Integration Model

本 SDK 当前按 Notion internal integration 使用场景维护和验证。推荐使用 Notion integration token，通过 NOTION_TOKEN 传入 nkit.Client()，并把目标页面、database 或 data source 授权给对应 integration。

OAuth helpers are thin pass-through wrappers for public integration OAuth flows. They are documented for completeness, but they are outside the internal-integration live validation scope.

Current API Boundary

This package targets notion-client >=3.1.0,<4. In the current Notion API model, a database container and a data source are different concepts:

• Database: the Notion page-level database container.
• Data source: the schema and rows inside a database.

Use the data source id when querying rows, reading schema, updating schema, or creating rows under a database.

nkit.Client() defaults to Notion API version 2026-03-11 and attaches wrappers for the current SDK endpoint families:

• Object helpers: Page, Database, DataSource, Block, User, Gadget
• Pass-through endpoint wrappers: Search, Comment, FileUpload, View, CustomEmoji, OAuth

See 最新 SDK 操作 / Latest SDK Operations for the full mapping.

License

MIT License