tracktolib 0.62.1__tar.gz → 0.64.0__tar.gz

{tracktolib-0.62.1 → tracktolib-0.64.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tracktolib
-Version: 0.62.1
+Version: 0.64.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 → tracktolib-0.64.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "tracktolib"
-version = "0.62.1"
+version = "0.64.0"
 authors = [
     { email = "julien.brayere@tracktor.fr" }
 ]
@@ -18,8 +18,6 @@ include = [
 ]
 requires-python = ">=3.12,<4.0"
 
-dependencies = []
-
 [project.optional-dependencies]
 logs = ["python-json-logger>=3.2.1"]
 pg-sync = ["psycopg>=3.1.12"]
@@ -39,6 +37,9 @@ pg = [
     "asyncpg>=0.27.0",
     "rich>=13.6.0",
 ]
+notion = [
+    "niquests>=3.15.2"
+]
 
 [dependency-groups]
 dev = [
@@ -91,7 +92,7 @@ pythonPlatform = "Linux"
 
 [tool.commitizen]
 name = "cz_conventional_commits"
-version = "0.62.1"
+version = "0.64.0"
 tag_format = "$version"
 version_files = [
     "pyproject.toml:version"

tracktolib-0.64.0/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-0.64.0/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 → tracktolib-0.64.0}/tracktolib/pg/query.py

@@ -160,12 +160,34 @@ class PGInsertQuery(PGQuery):
     def is_returning(self):
         return self.returning is not None
 
+    def _get_values_query(self) -> str:
+        """Generate the VALUES clause for the query."""
+        _columns = self.columns
+        num_cols = len(_columns)
+
+        if len(self.items) == 1 or not self.is_returning:
+            # Single row or no returning: simple placeholders
+            return ", ".join(f"${i + 1}" for i in range(num_cols))
+        else:
+            # Multiple rows with returning: generate all value groups
+            value_groups = []
+            for row_idx in range(len(self.items)):
+                offset = row_idx * num_cols
+                group = ", ".join(f"${offset + i + 1}" for i in range(num_cols))
+                value_groups.append(f"({group})")
+            return ", ".join(value_groups)
+
     @property
     def query(self) -> str:
         _columns = self.columns
-        _values = ", ".join(f"${i + 1}" for i, _ in enumerate(_columns))
+        _values = self._get_values_query()
 
-        query = _get_insert_query(self.table, _columns, _values)
+        if len(self.items) > 1 and self.is_returning:
+            # For multi-row insert with returning, build full VALUES clause
+            _columns_str = ", ".join(_columns)
+            query = f"INSERT INTO {self.table} AS t ({_columns_str}) VALUES {_values}"
+        else:
+            query = _get_insert_query(self.table, _columns, _values)
 
         # Conflict
         if self.on_conflict:
@@ -184,13 +206,14 @@ class PGInsertQuery(PGQuery):
         if self.returning is not None:
             if self.returning.returning_ids is None:
                 raise ValueError("No returning ids found")
-            if len(self.items) == 1:
-                query = _get_returning_query(query, self.returning.returning_ids)
-            else:
-                raise NotImplementedError("Cannot return value when inserting many.")
+            query = _get_returning_query(query, self.returning.returning_ids)
 
         return query
 
+    def _get_flat_values(self) -> list:
+        """Get all values as a flat list for multi-row insert with returning."""
+        return [val for item_values in self.iter_values() for val in item_values]
+
 
 def get_update_fields(
     item: dict,
@@ -341,6 +364,7 @@ async def insert_one(
     await query.run(conn)
 
 
+@overload
 async def insert_many(
     conn: _Connection,
     table: str,
@@ -349,12 +373,53 @@ async def insert_many(
     on_conflict: OnConflict | None = None,
     fill: bool = False,
     quote_columns: bool = False,
+    returning: None = None,
     query_callback: QueryCallback[PGInsertQuery] | None = None,
-):
-    query = insert_pg(table=table, items=items, on_conflict=on_conflict, fill=fill, quote_columns=quote_columns)
+) -> None: ...
+
+
+@overload
+async def insert_many(
+    conn: _Connection,
+    table: str,
+    items: list[dict],
+    *,
+    on_conflict: OnConflict | None = None,
+    fill: bool = False,
+    quote_columns: bool = False,
+    returning: str | list[str],
+    query_callback: QueryCallback[PGInsertQuery] | None = None,
+) -> list[asyncpg.Record]: ...
+
+
+async def insert_many(
+    conn: _Connection,
+    table: str,
+    items: list[dict],
+    *,
+    on_conflict: OnConflict | None = None,
+    fill: bool = False,
+    quote_columns: bool = False,
+    returning: str | list[str] | None = None,
+    query_callback: QueryCallback[PGInsertQuery] | None = None,
+) -> list[asyncpg.Record] | None:
+    returning_values = [returning] if isinstance(returning, str) else returning
+    query = insert_pg(
+        table=table,
+        items=items,
+        on_conflict=on_conflict,
+        fill=fill,
+        quote_columns=quote_columns,
+        returning=returning_values,
+    )
     if query_callback is not None:
         query_callback(query)
-    await query.run(conn)
+
+    if returning is not None:
+        return await conn.fetch(query.query, *query._get_flat_values())
+    else:
+        await query.run(conn)
+        return None
 
 
 @overload
@@ -381,22 +446,41 @@ async def insert_returning(
 ) -> asyncpg.Record | None: ...
 
 
+@overload
 async def insert_returning(
     conn: _Connection,
     table: str,
-    item: dict,
+    item: list[dict],
+    returning: str | list[str],
+    on_conflict: OnConflict | None = None,
+    fill: bool = False,
+    query_callback: QueryCallback[PGInsertQuery] | None = None,
+) -> list[asyncpg.Record]: ...
+
+
+async def insert_returning(
+    conn: _Connection,
+    table: str,
+    item: dict | list[dict],
     returning: list[str] | str,
     on_conflict: OnConflict | None = None,
     fill: bool = False,
     query_callback: QueryCallback[PGInsertQuery] | None = None,
-) -> asyncpg.Record | Any | None:
+) -> asyncpg.Record | Any | list[asyncpg.Record] | None:
     returning_values = [returning] if isinstance(returning, str) else returning
-    query = insert_pg(table=table, items=[item], on_conflict=on_conflict, fill=fill, returning=returning_values)
+    items = item if isinstance(item, list) else [item]
+
+    query = insert_pg(table=table, items=items, on_conflict=on_conflict, fill=fill, returning=returning_values)
     if query_callback is not None:
         query_callback(query)
-    fn = conn.fetchval if len(returning_values) == 1 and returning != "*" else conn.fetchrow
 
-    return await fn(query.query, *query.values)
+    if len(items) > 1:
+        # Multi-row insert: use fetch() with flat values
+        return await conn.fetch(query.query, *query._get_flat_values())
+    else:
+        # Single row insert: use fetchval or fetchrow
+        fn = conn.fetchval if len(returning_values) == 1 and returning != "*" else conn.fetchrow
+        return await fn(query.query, *query.values)
 
 
 async def fetch_count(conn: _Connection, query: str, *args) -> int: