tracktolib 0.67.0__py3-none-any.whl → 0.68.0__py3-none-any.whl

tracktolib/notion/cache.py

@@ -0,0 +1,202 @@
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass, field
+from datetime import datetime
+from pathlib import Path
+from types import TracebackType
+from typing import TYPE_CHECKING, Any, Mapping, Self, Sequence, TypedDict, cast
+
+if TYPE_CHECKING:
+    from .utils import PageComment
+
+
+class CachedDatabase(TypedDict):
+    id: str
+    title: str
+    properties: dict[str, Any]
+    cached_at: str
+
+
+class CachedPageBlocks(TypedDict):
+    """Cached blocks for a page."""
+
+    page_id: str
+    blocks: list[dict[str, Any]]
+    cached_at: str
+
+
+class CachedPageComments(TypedDict):
+    """Cached comments for a page."""
+
+    page_id: str
+    comments: list[dict[str, Any]]
+    cached_at: str
+
+
+class CacheData(TypedDict, total=False):
+    databases: dict[str, CachedDatabase]
+    page_blocks: dict[str, CachedPageBlocks]
+    page_comments: dict[str, CachedPageComments]
+
+
+def _default_cache_dir() -> Path:
+    """Default cache directory: $XDG_CACHE_HOME/tracktolib/notion or ~/.cache/tracktolib/notion."""
+    xdg_cache = os.environ.get("XDG_CACHE_HOME", str(Path.home() / ".cache"))
+    return Path(xdg_cache) / "tracktolib" / "notion"
+
+
+@dataclass
+class NotionCache:
+    """Persistent cache for Notion data.
+
+    Use as a context manager to load on entry and save on exit:
+
+        with NotionCache() as cache:
+            db = cache.get_database("db-id")
+            cache.set_database({"id": "new-db", ...})
+        # Automatically saved on exit
+    """
+
+    # Directory for cache file.
+    cache_dir: Path = field(default_factory=_default_cache_dir)
+    _file_path: Path = field(init=False)
+    _data: CacheData = field(init=False)
+    _dirty: bool = field(init=False, default=False)
+
+    def __post_init__(self) -> None:
+        self._file_path = self.cache_dir / "cache.json"
+        self._data = {}
+
+    def load(self) -> None:
+        """Load cache from disk into memory."""
+        if self._file_path.exists():
+            self._data = json.loads(self._file_path.read_text())
+        else:
+            self._data = {}
+        self._dirty = False
+
+    def save(self) -> None:
+        """Save in-memory cache to disk (only if modified)."""
+        if not self._dirty:
+            return
+        self._file_path.parent.mkdir(parents=True, exist_ok=True)
+        tmp = self._file_path.with_suffix(".tmp")
+        tmp.write_text(json.dumps(self._data, indent=2, default=str))
+        tmp.rename(self._file_path)
+        self._dirty = False
+
+    def __enter__(self) -> Self:
+        self.load()
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        self.save()
+
+    def get_database(self, database_id: str) -> CachedDatabase | None:
+        """Get a cached database by ID."""
+        return self._data.get("databases", {}).get(database_id)
+
+    def get_databases(self) -> dict[str, CachedDatabase]:
+        """Get all cached databases."""
+        return self._data.get("databases", {})
+
+    def set_database(self, database: Mapping[str, Any]) -> CachedDatabase:
+        """Cache a database from Notion API response."""
+        title_prop = database.get("title", [])
+        title = next(
+            (el["plain_text"] for el in title_prop if isinstance(el, Mapping) and "plain_text" in el),
+            "",
+        )
+
+        entry: CachedDatabase = {
+            "id": database["id"],
+            "title": title,
+            "properties": database["properties"],
+            "cached_at": datetime.now().isoformat(),
+        }
+
+        if "databases" not in self._data:
+            self._data["databases"] = {}
+        self._data["databases"][database["id"]] = entry
+        self._dirty = True
+        return entry
+
+    def delete_database(self, database_id: str) -> None:
+        """Remove a database from cache."""
+        if "databases" in self._data:
+            self._data["databases"].pop(database_id, None)
+            self._dirty = True
+
+    def clear(self) -> None:
+        """Clear all cached data."""
+        self._data = {}
+        self._dirty = True
+
+    def get_page_blocks(self, page_id: str) -> list[dict[str, Any]] | None:
+        """Get cached blocks for the given page_id, or None if not cached."""
+        cached = self._data.get("page_blocks", {}).get(page_id)
+        if cached:
+            return cached["blocks"]
+        return None
+
+    def set_page_blocks(
+        self,
+        page_id: str,
+        blocks: Sequence[dict[str, Any]],
+    ) -> CachedPageBlocks:
+        """Cache the given blocks for page_id and return the cached entry."""
+        entry: CachedPageBlocks = {
+            "page_id": page_id,
+            "blocks": list(blocks),
+            "cached_at": datetime.now().isoformat(),
+        }
+
+        if "page_blocks" not in self._data:
+            self._data["page_blocks"] = {}
+        self._data["page_blocks"][page_id] = entry
+        self._dirty = True
+        return entry
+
+    def delete_page_blocks(self, page_id: str) -> None:
+        """Remove cached blocks for the given page_id."""
+        if "page_blocks" in self._data:
+            self._data["page_blocks"].pop(page_id, None)
+            self._dirty = True
+
+    def get_page_comments(self, page_id: str) -> list[PageComment] | None:
+        """Get cached comments for the given page_id, or None if not cached."""
+        cached = self._data.get("page_comments", {}).get(page_id)
+        if cached:
+            return cached["comments"]  # type: ignore[return-value]
+        return None
+
+    def set_page_comments(
+        self,
+        page_id: str,
+        comments: Sequence[PageComment],
+    ) -> CachedPageComments:
+        """Cache the given comments for page_id and return the cached entry."""
+        entry: CachedPageComments = {
+            "page_id": page_id,
+            "comments": cast(list[dict[str, Any]], list(comments)),
+            "cached_at": datetime.now().isoformat(),
+        }
+
+        if "page_comments" not in self._data:
+            self._data["page_comments"] = {}
+        self._data["page_comments"][page_id] = entry
+        self._dirty = True
+        return entry
+
+    def delete_page_comments(self, page_id: str) -> None:
+        """Remove cached comments for the given page_id."""
+        if "page_comments" in self._data:
+            self._data["page_comments"].pop(page_id, None)
+            self._dirty = True

tracktolib/notion/fetch.py

@@ -1,14 +1,22 @@
+from __future__ import annotations
+
 import os
-from typing import Any, Literal
+from typing import TYPE_CHECKING, Any, Literal, Sequence, overload
 
 try:
     import niquests
 except ImportError:
     raise ImportError('Please install niquests or tracktolib with "notion" to use this module')
 
+if TYPE_CHECKING:
+    from .blocks import NotionBlock
+    from .cache import CachedDatabase, NotionCache
+
 from .models import (
     Block,
     BlockListResponse,
+    Comment,
+    CommentListResponse,
     Database,
     IntrospectTokenResponse,
     Page,
@@ -61,6 +69,10 @@ __all__ = (
     "fetch_block",
     "fetch_block_children",
     "fetch_append_block_children",
+    "delete_block",
+    # Comments
+    "fetch_comments",
+    "create_comment",
     # Search
     "fetch_search",
 )
@@ -217,7 +229,7 @@ async def create_page(
     *,
     parent: dict[str, Any],
     properties: dict[str, Any],
-    children: list[dict[str, Any]] | None = None,
+    children: Sequence[NotionBlock | dict[str, Any]] | None = None,
     icon: dict[str, Any] | None = None,
     cover: dict[str, Any] | None = None,
     api_version: ApiVersion | None = None,
@@ -274,17 +286,46 @@ async def update_page(
 # Databases endpoints
 
 
+@overload
+async def fetch_database(
+    session: niquests.AsyncSession,
+    database_id: str,
+    *,
+    api_version: ApiVersion | None = None,
+    cache: None = None,
+) -> Database: ...
+
+
+@overload
 async def fetch_database(
     session: niquests.AsyncSession,
     database_id: str,
     *,
     api_version: ApiVersion | None = None,
-) -> Database:
+    cache: NotionCache,
+) -> Database | CachedDatabase: ...
+
+
+async def fetch_database(
+    session: niquests.AsyncSession,
+    database_id: str,
+    *,
+    api_version: ApiVersion | None = None,
+    cache: NotionCache | None = None,
+) -> Database | CachedDatabase:
     """Retrieve a database/data source by ID.
 
     For API version 2025-09-03+, uses /v1/data_sources/{id} endpoint.
     For older API versions, uses /v1/databases/{id} endpoint.
+
+    If cache is provided, the database will be looked up in the cache first.
+    On cache miss, the database is fetched from the API and stored in the cache.
+    When returning from cache, returns a CachedDatabase (partial) instead of full Database.
     """
+    if cache:
+        if cached := cache.get_database(database_id):
+            return cached
+
     _api_version = _get_api_version(session, api_version)
     if _use_data_source_api(_api_version):
         endpoint = f"{NOTION_API_URL}/v1/data_sources/{database_id}"
@@ -293,7 +334,12 @@ async def fetch_database(
 
     response = await session.get(endpoint)
     response.raise_for_status()
-    return response.json()  # type: ignore[return-value]
+    result: Database = response.json()
+
+    if cache:
+        cache.set_database(result)
+
+    return result
 
 
 async def query_database(
@@ -364,7 +410,7 @@ async def fetch_block_children(
 async def fetch_append_block_children(
     session: niquests.AsyncSession,
     block_id: str,
-    children: list[dict[str, Any]],
+    children: Sequence[NotionBlock | dict[str, Any]],
 ) -> BlockListResponse:
     """Append children blocks to a parent block."""
     payload = {"children": children}
@@ -374,6 +420,76 @@ async def fetch_append_block_children(
     return response.json()  # type: ignore[return-value]
 
 
+async def delete_block(session: niquests.AsyncSession, block_id: str) -> Block:
+    """Delete (archive) a block.
+
+    Args:
+        session: Authenticated niquests session
+        block_id: The ID of the block to delete
+
+    Returns:
+        The deleted block object with archived=True
+    """
+    response = await session.delete(f"{NOTION_API_URL}/v1/blocks/{block_id}")
+    response.raise_for_status()
+    return response.json()  # type: ignore[return-value]
+
+
+# Comments endpoints
+
+
+async def fetch_comments(
+    session: niquests.AsyncSession,
+    block_id: str,
+    *,
+    start_cursor: str | None = None,
+    page_size: int | None = None,
+) -> CommentListResponse:
+    """Retrieve comments for a block or page.
+
+    Args:
+        session: Authenticated niquests session
+        block_id: The ID of the block or page to get comments for
+        start_cursor: Pagination cursor
+        page_size: Number of results per page
+    """
+    params: dict[str, str] = {"block_id": block_id}
+    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/comments", params=params)).raise_for_status()
+    return response.json()  # type: ignore[return-value]
+
+
+async def create_comment(
+    session: niquests.AsyncSession,
+    *,
+    parent: dict[str, str],
+    rich_text: list[dict[str, Any]],
+    discussion_id: str | None = None,
+) -> Comment:
+    """Create a comment on a page or in an existing discussion.
+
+    Args:
+        session: Authenticated niquests session
+        parent: Parent object, e.g. {"page_id": "..."} for page-level comments
+        rich_text: The comment content as rich text array
+        discussion_id: Optional discussion ID to reply to an existing thread
+    """
+    payload: dict[str, Any] = {
+        "parent": parent,
+        "rich_text": rich_text,
+    }
+    if discussion_id:
+        payload["discussion_id"] = discussion_id
+
+    response = await session.post(f"{NOTION_API_URL}/v1/comments", json=payload)
+    response.raise_for_status()
+    return response.json()  # type: ignore[return-value]
+
+
 # Search endpoint