tracktolib 0.62.1__py3-none-any.whl → 0.63.0__py3-none-any.whl

tracktolib/notion/fetch.py

@@ -0,0 +1,352 @@
+import os
+from typing import Any
+
+try:
+    import niquests
+except ImportError:
+    raise ImportError('Please install niquests or tracktolib with "notion" to use this module')
+
+from .models import (
+    Block,
+    BlockListResponse,
+    Database,
+    IntrospectTokenResponse,
+    Page,
+    PageListResponse,
+    RevokeTokenResponse,
+    SearchResponse,
+    TokenResponse,
+    User,
+    UserListResponse,
+)
+
+__all__ = (
+    # Auth helpers
+    "get_notion_headers",
+    # OAuth
+    "create_token",
+    "introspect_token",
+    "revoke_token",
+    "refresh_token",
+    # Users
+    "fetch_users",
+    "fetch_user",
+    "fetch_me",
+    # Pages
+    "fetch_page",
+    "create_page",
+    "update_page",
+    # Databases
+    "fetch_database",
+    "query_database",
+    # Blocks
+    "fetch_block",
+    "fetch_block_children",
+    "fetch_append_block_children",
+    # Search
+    "fetch_search",
+)
+
+NOTION_API_URL = "https://api.notion.com"
+
+
+def _get_notion_token() -> str:
+    """Get Notion token from config or environment."""
+    token = os.environ.get("NOTION_TOKEN")
+    if not token:
+        raise ValueError("Notion token not found. Set NOTION_TOKEN env var.")
+    return token
+
+
+def get_notion_headers(api_version: str = "2025-09-03", token: str | None = None):
+    """Get headers for Notion API requests."""
+    _token = token or _get_notion_token()
+    return {
+        "Authorization": f"Bearer {_token}",
+        "Notion-Version": api_version,
+    }
+
+
+# OAuth endpoints
+
+
+async def create_token(
+    session: niquests.AsyncSession,
+    client_id: str,
+    client_secret: str,
+    code: str,
+    redirect_uri: str | None = None,
+) -> TokenResponse:
+    """Create an access token from an OAuth authorization code."""
+    payload: dict[str, str] = {
+        "grant_type": "authorization_code",
+        "code": code,
+    }
+    if redirect_uri:
+        payload["redirect_uri"] = redirect_uri
+
+    response = await session.post(f"{NOTION_API_URL}/v1/oauth/token", json=payload, auth=(client_id, client_secret))
+    response.raise_for_status()
+    return response.json()  # type: ignore[return-value]
+
+
+async def introspect_token(
+    session: niquests.AsyncSession,
+    client_id: str,
+    client_secret: str,
+    token: str,
+) -> IntrospectTokenResponse:
+    """Get a token's active status, scope, and issued time."""
+    payload = {"token": token}
+    response = await session.post(
+        f"{NOTION_API_URL}/v1/oauth/introspect", json=payload, auth=(client_id, client_secret)
+    )
+    response.raise_for_status()
+    return response.json()  # type: ignore[return-value]
+
+
+async def revoke_token(
+    session: niquests.AsyncSession,
+    client_id: str,
+    client_secret: str,
+    token: str,
+) -> RevokeTokenResponse:
+    """Revoke an access token."""
+    payload = {"token": token}
+
+    response = await session.post(f"{NOTION_API_URL}/v1/oauth/revoke", json=payload, auth=(client_id, client_secret))
+    response.raise_for_status()
+    return response.json()  # type: ignore[return-value]
+
+
+async def refresh_token(
+    session: niquests.AsyncSession,
+    client_id: str,
+    client_secret: str,
+    refresh_token_value: str,
+) -> TokenResponse:
+    """Refresh an access token, generating new access and refresh tokens."""
+    payload = {
+        "grant_type": "refresh_token",
+        "refresh_token": refresh_token_value,
+    }
+
+    response = await session.post(f"{NOTION_API_URL}/v1/oauth/token", json=payload, auth=(client_id, client_secret))
+    response.raise_for_status()
+    return response.json()  # type: ignore[return-value]
+
+
+# Users endpoints
+
+
+async def fetch_users(
+    session: niquests.AsyncSession,
+    *,
+    start_cursor: str | None = None,
+    page_size: int | None = None,
+) -> UserListResponse:
+    """List all users in the workspace."""
+    params: dict[str, str] = {}
+    if start_cursor:
+        params["start_cursor"] = start_cursor
+    if page_size:
+        params["page_size"] = str(page_size)
+
+    response = await session.get(f"{NOTION_API_URL}/v1/users", params=params or None)
+    response.raise_for_status()
+    return response.json()  # type: ignore[return-value]
+
+
+async def fetch_user(session: niquests.AsyncSession, user_id: str) -> User:
+    """Retrieve a user by ID."""
+    response = await session.get(f"{NOTION_API_URL}/v1/users/{user_id}")
+    response.raise_for_status()
+    return response.json()  # type: ignore[return-value]
+
+
+async def fetch_me(session: niquests.AsyncSession) -> User:
+    """Retrieve the bot user associated with the token."""
+    response = await session.get(f"{NOTION_API_URL}/v1/users/me")
+    response.raise_for_status()
+    return response.json()  # type: ignore[return-value]
+
+
+# Pages endpoints
+
+
+async def fetch_page(session: niquests.AsyncSession, page_id: str) -> Page:
+    """Retrieve a page by ID."""
+    response = await session.get(f"{NOTION_API_URL}/v1/pages/{page_id}")
+    response.raise_for_status()
+    return response.json()  # type: ignore[return-value]
+
+
+async def create_page(
+    session: niquests.AsyncSession,
+    *,
+    parent: dict[str, Any],
+    properties: dict[str, Any],
+    children: list[dict[str, Any]] | None = None,
+    icon: dict[str, Any] | None = None,
+    cover: dict[str, Any] | None = None,
+) -> Page:
+    """Create a new page."""
+    payload: dict[str, Any] = {
+        "parent": parent,
+        "properties": properties,
+    }
+    if children:
+        payload["children"] = children
+    if icon:
+        payload["icon"] = icon
+    if cover:
+        payload["cover"] = cover
+
+    response = await session.post(f"{NOTION_API_URL}/v1/pages", json=payload)
+    response.raise_for_status()
+    return response.json()  # type: ignore[return-value]
+
+
+async def update_page(
+    session: niquests.AsyncSession,
+    page_id: str,
+    *,
+    properties: dict[str, Any] | None = None,
+    archived: bool | None = None,
+    icon: dict[str, Any] | None = None,
+    cover: dict[str, Any] | None = None,
+) -> Page:
+    """Update a page's properties."""
+    payload: dict[str, Any] = {}
+    if properties is not None:
+        payload["properties"] = properties
+    if archived is not None:
+        payload["archived"] = archived
+    if icon is not None:
+        payload["icon"] = icon
+    if cover is not None:
+        payload["cover"] = cover
+
+    response = await session.patch(f"{NOTION_API_URL}/v1/pages/{page_id}", json=payload)
+    response.raise_for_status()
+    return response.json()  # type: ignore[return-value]
+
+
+# Databases endpoints
+
+
+async def fetch_database(session: niquests.AsyncSession, database_id: str) -> Database:
+    """Retrieve a database by ID."""
+    response = await session.get(f"{NOTION_API_URL}/v1/databases/{database_id}")
+    response.raise_for_status()
+    return response.json()  # type: ignore[return-value]
+
+
+async def query_database(
+    session: niquests.AsyncSession,
+    database_id: str,
+    *,
+    filter: dict[str, Any] | None = None,
+    sorts: list[dict[str, Any]] | None = None,
+    start_cursor: str | None = None,
+    page_size: int | None = None,
+) -> PageListResponse:
+    """Query a database."""
+    payload: dict[str, Any] = {}
+    if filter:
+        payload["filter"] = filter
+    if sorts:
+        payload["sorts"] = sorts
+    if start_cursor:
+        payload["start_cursor"] = start_cursor
+    if page_size:
+        payload["page_size"] = page_size
+
+    response = await session.post(f"{NOTION_API_URL}/v1/databases/{database_id}/query", json=payload or None)
+    response.raise_for_status()
+    return response.json()  # type: ignore[return-value]
+
+
+# Blocks endpoints
+
+
+async def fetch_block(session: niquests.AsyncSession, block_id: str) -> Block:
+    """Retrieve a block by ID."""
+    response = await session.get(f"{NOTION_API_URL}/v1/blocks/{block_id}")
+    response.raise_for_status()
+    return response.json()  # type: ignore[return-value]
+
+
+async def fetch_block_children(
+    session: niquests.AsyncSession,
+    block_id: str,
+    *,
+    start_cursor: str | None = None,
+    page_size: int | None = None,
+) -> BlockListResponse:
+    """Retrieve a block's children."""
+    params: dict[str, str] = {}
+    if start_cursor:
+        params["start_cursor"] = start_cursor
+    if page_size:
+        params["page_size"] = str(page_size)
+
+    response = await session.get(f"{NOTION_API_URL}/v1/blocks/{block_id}/children", params=params or None)
+    response.raise_for_status()
+    return response.json()  # type: ignore[return-value]
+
+
+async def fetch_append_block_children(
+    session: niquests.AsyncSession,
+    block_id: str,
+    children: list[dict[str, Any]],
+) -> BlockListResponse:
+    """Append children blocks to a parent block."""
+    payload = {"children": children}
+
+    response = await session.patch(f"{NOTION_API_URL}/v1/blocks/{block_id}/children", json=payload)
+    response.raise_for_status()
+    return response.json()  # type: ignore[return-value]
+
+
+# Search endpoint
+
+
+async def fetch_search(
+    session: niquests.AsyncSession,
+    *,
+    query: str | None = None,
+    filter: dict[str, Any] | None = None,
+    sort: dict[str, Any] | None = None,
+    start_cursor: str | None = None,
+    page_size: int | None = None,
+) -> SearchResponse:
+    """Search pages and databases."""
+    payload: dict[str, Any] = {}
+    if query:
+        payload["query"] = query
+    if filter:
+        payload["filter"] = filter
+    if sort:
+        payload["sort"] = sort
+    if start_cursor:
+        payload["start_cursor"] = start_cursor
+    if page_size:
+        payload["page_size"] = page_size
+
+    response = await session.post(f"{NOTION_API_URL}/v1/search", json=payload or None)
+    response.raise_for_status()
+    return response.json()  # type: ignore[return-value]
+
+
+if __name__ == "__main__":
+    import asyncio
+
+    async def main():
+        async with niquests.AsyncSession() as session:
+            session.headers.update(get_notion_headers())
+            me = await fetch_me(session)
+            print("Me:", me)
+            # print(await fetch_search(session, filter="aaa"))
+
+    asyncio.run(main())

tracktolib/notion/models.py

@@ -0,0 +1,281 @@
+"""Notion API models based on official notion-sdk-js types."""
+
+from typing import Any, Literal, NotRequired, TypedDict
+
+# Base types
+
+
+class PartialUser(TypedDict):
+    """Partial user object."""
+
+    id: str
+    object: Literal["user"]
+
+
+class PersonDetails(TypedDict):
+    """Person details."""
+
+    email: NotRequired[str]
+
+
+class PersonUserObjectResponse(TypedDict):
+    """Person user type details."""
+
+    type: Literal["person"]
+    person: PersonDetails
+
+
+class BotUserObjectResponse(TypedDict):
+    """Bot user type details."""
+
+    type: Literal["bot"]
+    bot: dict[str, Any]
+
+
+class UserObjectResponseCommon(TypedDict):
+    """Common user object fields."""
+
+    id: str
+    object: Literal["user"]
+    name: str | None
+    avatar_url: str | None
+
+
+# User object is common fields + either person or bot
+class User(UserObjectResponseCommon):
+    """Full user object."""
+
+    type: Literal["person", "bot"]
+    person: NotRequired[PersonDetails]
+    bot: NotRequired[dict[str, Any]]
+
+
+# OAuth types
+
+
+class UserOwner(TypedDict):
+    """User owner for OAuth."""
+
+    type: Literal["user"]
+    user: User | PartialUser
+
+
+class WorkspaceOwner(TypedDict):
+    """Workspace owner for OAuth."""
+
+    type: Literal["workspace"]
+    workspace: Literal[True]
+
+
+Owner = UserOwner | WorkspaceOwner
+
+
+class TokenResponse(TypedDict):
+    """Response from creating or refreshing an access token."""
+
+    access_token: str
+    token_type: Literal["bearer"]
+    refresh_token: str | None
+    bot_id: str
+    workspace_icon: str | None
+    workspace_name: str | None
+    workspace_id: str
+    owner: Owner
+    duplicated_template_id: str | None
+    request_id: NotRequired[str]
+
+
+class IntrospectTokenResponse(TypedDict):
+    """Response from introspecting a token."""
+
+    active: bool
+    scope: NotRequired[str]
+    iat: NotRequired[int]
+    request_id: NotRequired[str]
+
+
+class RevokeTokenResponse(TypedDict):
+    """Response from revoking a token."""
+
+    request_id: NotRequired[str]
+
+
+# Rich text types
+
+
+class RichTextItemResponse(TypedDict):
+    """Rich text item."""
+
+    type: str
+    plain_text: str
+    href: str | None
+    annotations: dict[str, Any]
+    text: NotRequired[dict[str, Any]]
+    mention: NotRequired[dict[str, Any]]
+    equation: NotRequired[dict[str, Any]]
+
+
+# Parent types
+
+
+class PageParent(TypedDict):
+    """Page parent."""
+
+    type: Literal["page_id"]
+    page_id: str
+
+
+class DatabaseParent(TypedDict):
+    """Database parent."""
+
+    type: Literal["database_id"]
+    database_id: str
+
+
+class WorkspaceParent(TypedDict):
+    """Workspace parent."""
+
+    type: Literal["workspace"]
+    workspace: Literal[True]
+
+
+class BlockParent(TypedDict):
+    """Block parent."""
+
+    type: Literal["block_id"]
+    block_id: str
+
+
+Parent = PageParent | DatabaseParent | WorkspaceParent | BlockParent
+
+
+# Page types
+
+
+class Page(TypedDict):
+    """Page object response."""
+
+    object: Literal["page"]
+    id: str
+    created_time: str
+    last_edited_time: str
+    created_by: PartialUser
+    last_edited_by: PartialUser
+    archived: bool
+    in_trash: bool
+    is_locked: bool
+    url: str
+    public_url: str | None
+    parent: Parent
+    properties: dict[str, Any]
+    icon: dict[str, Any] | None
+    cover: dict[str, Any] | None
+
+
+class PartialPage(TypedDict):
+    """Partial page object."""
+
+    object: Literal["page"]
+    id: str
+
+
+# Database types
+
+
+class Database(TypedDict):
+    """Database object response."""
+
+    object: Literal["database"]
+    id: str
+    title: list[RichTextItemResponse]
+    description: list[RichTextItemResponse]
+    parent: Parent
+    is_inline: bool
+    in_trash: bool
+    is_locked: bool
+    created_time: str
+    last_edited_time: str
+    icon: dict[str, Any] | None
+    cover: dict[str, Any] | None
+    properties: dict[str, Any]
+    url: str
+    public_url: str | None
+    archived: bool
+    created_by: PartialUser
+    last_edited_by: PartialUser
+
+
+class PartialDatabase(TypedDict):
+    """Partial database object."""
+
+    object: Literal["database"]
+    id: str
+
+
+# Block types
+
+
+class Block(TypedDict):
+    """Block object response."""
+
+    object: Literal["block"]
+    id: str
+    parent: Parent
+    type: str
+    created_time: str
+    last_edited_time: str
+    created_by: PartialUser
+    last_edited_by: PartialUser
+    has_children: bool
+    archived: bool
+    in_trash: bool
+
+
+class PartialBlock(TypedDict):
+    """Partial block object."""
+
+    object: Literal["block"]
+    id: str
+
+
+# List response types
+
+
+class UserListResponse(TypedDict):
+    """Response from listing users."""
+
+    object: Literal["list"]
+    type: Literal["user"]
+    results: list[User]
+    next_cursor: str | None
+    has_more: bool
+
+
+class PageListResponse(TypedDict):
+    """Response from querying a database."""
+
+    object: Literal["list"]
+    type: Literal["page_or_data_source"]
+    results: list[Page | PartialPage]
+    next_cursor: str | None
+    has_more: bool
+
+
+class BlockListResponse(TypedDict):
+    """Response from listing block children."""
+
+    object: Literal["list"]
+    type: Literal["block"]
+    results: list[Block | PartialBlock]
+    next_cursor: str | None
+    has_more: bool
+
+
+class SearchResponse(TypedDict):
+    """Response from search."""
+
+    object: Literal["list"]
+    type: Literal["page_or_data_source"]
+    results: list[Page | PartialPage | Database | PartialDatabase]
+    next_cursor: str | None
+    has_more: bool

{tracktolib-0.62.1.dist-info → tracktolib-0.63.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tracktolib
-Version: 0.62.1
+Version: 0.63.0
 Summary: Utility library for python
 Keywords: utility
 Author-email: julien.brayere@tracktor.fr
@@ -10,6 +10,7 @@ Requires-Dist: fastapi>=0.103.2 ; extra == 'api'
 Requires-Dist: pydantic>=2 ; extra == 'api'
 Requires-Dist: httpx>=0.25.0 ; extra == 'http'
 Requires-Dist: python-json-logger>=3.2.1 ; extra == 'logs'
+Requires-Dist: niquests>=3.15.2 ; extra == 'notion'
 Requires-Dist: asyncpg>=0.27.0 ; extra == 'pg'
 Requires-Dist: rich>=13.6.0 ; extra == 'pg'
 Requires-Dist: psycopg>=3.1.12 ; extra == 'pg-sync'
@@ -21,6 +22,7 @@ Requires-Python: >=3.12, <4.0
 Provides-Extra: api
 Provides-Extra: http
 Provides-Extra: logs
+Provides-Extra: notion
 Provides-Extra: pg
 Provides-Extra: pg-sync
 Provides-Extra: s3

{tracktolib-0.62.1.dist-info → tracktolib-0.63.0.dist-info}/RECORD

@@ -2,6 +2,9 @@ tracktolib/__init__.py,sha256=Q9d6h2lNjcYzxvfJ3zlNcpiP_Ak0T3TBPWINzZNrhu0,173
 tracktolib/api.py,sha256=ZLMgjH3Y8r3MpXc8m3IuZbzTj3fgrZKZORtSVgbuP-M,10221
 tracktolib/http_utils.py,sha256=c10JGmHaBw3VSDMYhz2dvVw2lo4PUAq1xMub74I7xDc,2625
 tracktolib/logs.py,sha256=D2hx6urXl5l4PBGP8mCpcT4GX7tJeFfNY-7oBfHczBU,2191
+tracktolib/notion/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tracktolib/notion/fetch.py,sha256=zIhFo9T18eS75l0wZN_WaXD51OUxTsgvFuvqk3R87o4,9974
+tracktolib/notion/models.py,sha256=D-px7Ht2xoXKKZICuEkZhRwVBvVCaKCvhpzPtVVYawI,5390
 tracktolib/pg/__init__.py,sha256=Ul_hgwvTXZvQBt7sHKi4ZI-0DDpnXmoFtmVkGRy-1J0,366
 tracktolib/pg/query.py,sha256=_wL9MQU_z8Sk0ZOYGVE0TjUbwBZ1OJJuEq2jlmWoeeM,16693
 tracktolib/pg/utils.py,sha256=ygQn63EBDaEGB0p7P2ibellO2mv-StafanpXKcCUiZU,6324
@@ -12,6 +15,6 @@ tracktolib/s3/minio.py,sha256=wMEjkSes9Fp39fD17IctALpD6zB2xwDRQEmO7Vzan3g,1387
 tracktolib/s3/s3.py,sha256=0HbSAPoaup5-W4LK54zRCjrQ5mr8OWR-N9WjW99Q4aw,5937
 tracktolib/tests.py,sha256=gKE--epQjgMZGXc5ydbl4zjOdmwztJS42UMV0p4hXEA,399
 tracktolib/utils.py,sha256=ysTBF9V35fVXQVBPk0kfE_84SGRxzrayqmg9RbtoJq4,5761
-tracktolib-0.62.1.dist-info/WHEEL,sha256=3id4o64OvRm9dUknh3mMJNcfoTRK08ua5cU6DFyVy-4,79
-tracktolib-0.62.1.dist-info/METADATA,sha256=dKxWZjdrwg0x4Hak-Wux5mQcjfT2ZL0in7ZQp_dyaXo,3053
-tracktolib-0.62.1.dist-info/RECORD,,
+tracktolib-0.63.0.dist-info/WHEEL,sha256=z-mOpxbJHqy3cq6SvUThBZdaLGFZzdZPtgWLcP2NKjQ,79
+tracktolib-0.63.0.dist-info/METADATA,sha256=q3HcfLHVoybHIDc4Bgayt3kYd5v1spd62OCGyxjCfZw,3128
+tracktolib-0.63.0.dist-info/RECORD,,

{tracktolib-0.62.1.dist-info → tracktolib-0.63.0.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: uv 0.9.13
+Generator: uv 0.9.15
 Root-Is-Purelib: true
 Tag: py3-none-any