notion-py-client 0.1.20

A Python client for Notion API

notion-py-client

A type-safe Python client library for the Notion API, built with Pydantic v2.

Features

• Type-Safe: Complete type definitions using Pydantic v2
• Async-First: Built on httpx for async/await support
• API 2026-03-11: Latest Notion API with position, in_trash, and meeting_notes
• Comprehensive: All blocks, properties, filters, and request types
• Domain Mapping: Built-in mapper for converting to domain models

Installation

pip install notion-py-client

Quick Start

import asyncio
from notion_py_client import NotionAsyncClient

async def main():
    client = NotionAsyncClient(auth="your_NOTION_API_TOKEN")

    # Query a data source (API 2026-03-11)
    response = await client.dataSources.query(
        data_source_id="your_data_source_id"
    )

    for page in response.results:
        print(page.id, page.properties)

asyncio.run(main())

Notion API 2026-03-11

This library supports the latest Notion API version 2026-03-11, including:

• Current breaking changes: position, in_trash, and meeting_notes
• Markdown APIs: create, read, and update page content as markdown
• Custom emojis: customEmojis.list() support
• DataSources: Continued support for the 2025-09-03 data model split

DataSources vs Databases

# New DataSources API (recommended)
await client.dataSources.query(data_source_id="...")

# Legacy Databases API (only for older Notion-Version headers)
await client.databases.query(database_id="...")

Both endpoints work identically, but dataSources is the future-proof choice.

Documentation

Full documentation is available at: https://higashi-masafumi.github.io/notion-py/

• Quick Start Guide
• API Reference
• Type Reference
• Advanced Usage

Core Capabilities

Pages

# Create a page
from notion_py_client.requests import CreatePageParameters, TitlePropertyRequest

await client.pages.create(
    params=CreatePageParameters(
        parent={"type": "data_source_id", "data_source_id": "your_data_source_id"},
        properties={
            "Name": TitlePropertyRequest(
                title=[{"type": "text", "text": {"content": "New Page"}}]
            )
        }
    )
)

Filters

from notion_py_client import NotionAsyncClient
from notion_py_client.filters import create_and_filter, create_or_filter

client = NotionAsyncClient(auth="your_NOTION_API_TOKEN")

# Simple filter (直接辞書 - IDE補完が効く)
response = await client.dataSources.query(
    data_source_id="your_data_source_id",
    filter={"property": "Status", "status": {"equals": "Active"}}
)

# AND filter with helper function (型安全 - IDE補完が効く)
filter = create_and_filter(
    {"property": "Name", "rich_text": {"contains": "urgent"}},
    {"property": "Status", "status": {"equals": "In Progress"}}
)

# OR filter with helper function
filter = create_or_filter(
    {"property": "Priority", "select": {"equals": "High"}},
    {"property": "Priority", "select": {"equals": "Medium"}}
)

# Nested filters (AND + OR)
filter = create_and_filter(
    {"property": "Team", "select": {"equals": "Engineering"}},
    create_or_filter(
        {"property": "Status", "status": {"equals": "Active"}},
        {"property": "Status", "status": {"equals": "Pending"}}
    )
)

await client.dataSources.query(
    data_source_id="your_data_source_id",
    filter=filter
)

Key Benefits:

• IDE Completion: Type hints work correctly with dictionary literals
• Type Safety: TypedDict definitions match official TypeScript SDK
• No .model_dump(): Use filters directly without conversion
• Public API Compatible: Follows official Notion API specification

Domain Mapping

from notion_py_client.helper import NotionMapper, NotionPropertyDescriptor, Field
from notion_py_client.requests.property_requests import (
    TitlePropertyRequest,
    StatusPropertyRequest,
)
from notion_py_client.responses.property_types import TitleProperty, StatusProperty
from pydantic import BaseModel

class Task(BaseModel):
    id: str
    name: str
    status: str

class TaskMapper(NotionMapper[Task]):
    # Define field descriptors with type annotations
    name_field: NotionPropertyDescriptor[TitleProperty, TitlePropertyRequest, str] = Field(
        notion_name="Name",
        parser=lambda p: p.title[0].plain_text if p.title else "",
        request_builder=lambda v: TitlePropertyRequest(
            title=[{"type": "text", "text": {"content": v}}]
        )
    )

    status_field: NotionPropertyDescriptor[StatusProperty, StatusPropertyRequest, str] = Field(
        notion_name="Status",
        parser=lambda p: p.status.name if p.status else "",
        request_builder=lambda v: StatusPropertyRequest(
            status={"name": v}
        )
    )

    def to_domain(self, notion_page):
        """Convert Notion page to domain model."""
        props = notion_page.properties
        return Task(
            id=notion_page.id,
            name=self.name_field.parse(props["Name"]),
            status=self.status_field.parse(props["Status"]),
        )

# Use the mapper
mapper = TaskMapper()
tasks = [mapper.to_domain(page) for page in response.results]

Requirements

• Python >= 3.10
• Pydantic >= 2.11.10

License

MIT License - see LICENSE for details.