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

tracktolib/notion/blocks.py

@@ -0,0 +1,459 @@
+"""Notion block creation utilities."""
+
+from __future__ import annotations
+
+import re
+from typing import TYPE_CHECKING, Any, Sequence, TypedDict
+
+if TYPE_CHECKING:
+    from .models import Block, PartialBlock
+
+__all__ = [
+    # Types
+    "ParagraphBlock",
+    "HeadingBlock",
+    "CodeBlock",
+    "BulletedListBlock",
+    "NumberedListBlock",
+    "TodoBlock",
+    "DividerBlock",
+    "QuoteBlock",
+    "NotionBlock",
+    "ExportResult",
+    # Rich text parsing
+    "parse_rich_text",
+    # Block creators
+    "make_paragraph_block",
+    "make_heading_block",
+    "make_code_block",
+    "make_bulleted_list_block",
+    "make_numbered_list_block",
+    "make_todo_block",
+    "make_divider_block",
+    "make_quote_block",
+    # Block comparison
+    "blocks_content_equal",
+    "find_divergence_index",
+]
+
+
+class ExportResult(TypedDict):
+    """Result of exporting markdown to Notion."""
+
+    count: int
+    """Number of blocks created in the page."""
+    url: str | None
+    """URL of the created Notion page, or None if creation failed."""
+
+
+class _TextContent(TypedDict):
+    content: str
+
+
+class _Annotations(TypedDict, total=False):
+    bold: bool
+    italic: bool
+    code: bool
+    strikethrough: bool
+    underline: bool
+    color: str
+
+
+class _TextItem(TypedDict, total=False):
+    type: str
+    text: _TextContent
+    annotations: _Annotations
+
+
+class _RichTextContent(TypedDict):
+    rich_text: list[_TextItem]
+
+
+class _CodeContent(TypedDict):
+    rich_text: list[_TextItem]
+    language: str
+
+
+class _TodoContent(TypedDict):
+    rich_text: list[_TextItem]
+    checked: bool
+
+
+class _DividerContent(TypedDict):
+    pass
+
+
+class ParagraphBlock(TypedDict):
+    """Notion paragraph block structure."""
+
+    object: str
+    type: str
+    paragraph: _RichTextContent
+
+
+class HeadingBlock(TypedDict):
+    """Notion heading block structure."""
+
+    object: str
+    type: str
+    heading_1: _RichTextContent
+    heading_2: _RichTextContent
+    heading_3: _RichTextContent
+
+
+class CodeBlock(TypedDict):
+    """Notion code block structure."""
+
+    object: str
+    type: str
+    code: _CodeContent
+
+
+class BulletedListBlock(TypedDict):
+    """Notion bulleted list item block structure."""
+
+    object: str
+    type: str
+    bulleted_list_item: _RichTextContent
+
+
+class NumberedListBlock(TypedDict):
+    """Notion numbered list item block structure."""
+
+    object: str
+    type: str
+    numbered_list_item: _RichTextContent
+
+
+class TodoBlock(TypedDict):
+    """Notion to_do block structure."""
+
+    object: str
+    type: str
+    to_do: _TodoContent
+
+
+class DividerBlock(TypedDict):
+    """Notion divider block structure."""
+
+    object: str
+    type: str
+    divider: _DividerContent
+
+
+class QuoteBlock(TypedDict):
+    """Notion quote block structure."""
+
+    object: str
+    type: str
+    quote: _RichTextContent
+
+
+# Union type for all block types
+NotionBlock = (
+    ParagraphBlock
+    | HeadingBlock
+    | CodeBlock
+    | BulletedListBlock
+    | NumberedListBlock
+    | TodoBlock
+    | DividerBlock
+    | QuoteBlock
+)
+
+# Language aliases for code blocks
+LANGUAGE_ALIASES = {
+    "js": "javascript",
+    "ts": "typescript",
+    "py": "python",
+    "rb": "ruby",
+    "sh": "shell",
+    "bash": "shell",
+    "zsh": "shell",
+    "yml": "yaml",
+    "": "plain text",
+}
+
+# Pattern to match bold, code, or italic (in order of priority)
+# Note: underscore italics use lookahead/lookbehind to avoid matching underscores
+# inside identifiers like my_var_name
+_INLINE_FORMAT_PATTERN = re.compile(
+    r"(\*\*(.+?)\*\*|__(.+?)__|`([^`]+)`|\*([^*]+)\*|(?<![a-zA-Z0-9])_([^_]+)_(?![a-zA-Z0-9]))"
+)
+
+
+def parse_rich_text(text: str) -> list[_TextItem]:
+    """Parse markdown inline formatting to Notion rich_text array.
+
+    Handles:
+    - **bold** or __bold__
+    - `inline code`
+    - *italic* or _italic_
+    """
+    rich_text: list[_TextItem] = []
+    pos = 0
+    for match in _INLINE_FORMAT_PATTERN.finditer(text):
+        # Add plain text before the match
+        if match.start() > pos:
+            plain = text[pos : match.start()]
+            if plain:
+                rich_text.append({"type": "text", "text": {"content": plain}})
+
+        full_match = match.group(0)
+        if full_match.startswith("**") or full_match.startswith("__"):
+            # Bold
+            content = match.group(2) or match.group(3)
+            rich_text.append(
+                {
+                    "type": "text",
+                    "text": {"content": content},
+                    "annotations": {"bold": True},
+                }
+            )
+        elif full_match.startswith("`"):
+            # Inline code
+            content = match.group(4)
+            rich_text.append(
+                {
+                    "type": "text",
+                    "text": {"content": content},
+                    "annotations": {"code": True},
+                }
+            )
+        else:
+            # Italic
+            content = match.group(5) or match.group(6)
+            rich_text.append(
+                {
+                    "type": "text",
+                    "text": {"content": content},
+                    "annotations": {"italic": True},
+                }
+            )
+
+        pos = match.end()
+
+    # Add remaining plain text
+    if pos < len(text):
+        remaining = text[pos:]
+        if remaining:
+            rich_text.append({"type": "text", "text": {"content": remaining}})
+
+    # If no formatting found, return plain text
+    if not rich_text:
+        rich_text.append({"type": "text", "text": {"content": text}})
+
+    return rich_text
+
+
+def make_paragraph_block(text: str) -> ParagraphBlock:
+    """Create a Notion paragraph block with rich text formatting.
+
+    Args:
+        text: The paragraph text (max 2000 characters)
+
+    Raises:
+        ValueError: If text exceeds 2000 characters (Notion's limit)
+    """
+    if len(text) > 2000:
+        raise ValueError(f"Text exceeds Notion limit of 2000 characters ({len(text)} chars). Pre-chunk the text.")
+    return {
+        "object": "block",
+        "type": "paragraph",
+        "paragraph": {
+            "rich_text": parse_rich_text(text),
+        },
+    }
+
+
+def make_heading_block(text: str, level: int) -> dict[str, Any]:
+    """Create a Notion heading block (h1, h2, h3).
+
+    Args:
+        text: The heading text
+        level: Heading level (1-6). Levels 4-6 are mapped to h3.
+    """
+    # Notion only supports h1, h2, h3 - map others to h3
+    heading_type = f"heading_{min(level, 3)}"
+    return {
+        "object": "block",
+        "type": heading_type,
+        heading_type: {
+            "rich_text": parse_rich_text(text),
+        },
+    }
+
+
+def make_code_block(code: str, language: str = "plain text", *, chunk_size: int = 2000) -> list[dict[str, Any]]:
+    """Create Notion code block(s).
+
+    If code exceeds chunk_size characters, it is split into multiple blocks
+    to preserve the full content.
+
+    Args:
+        code: The code content
+        language: Programming language (supports aliases like 'py', 'js', 'ts')
+        chunk_size: Maximum characters per block (default 2000, Notion's limit)
+
+    Returns:
+        List of code block dicts (usually one, multiple if code > chunk_size chars)
+    """
+    notion_lang = LANGUAGE_ALIASES.get(language.lower(), language.lower())
+
+    blocks: list[dict[str, Any]] = []
+    for i in range(0, len(code), chunk_size):
+        chunk = code[i : i + chunk_size]
+        blocks.append(
+            {
+                "object": "block",
+                "type": "code",
+                "code": {
+                    "rich_text": [{"type": "text", "text": {"content": chunk}}],
+                    "language": notion_lang,
+                },
+            }
+        )
+
+    return blocks
+
+
+def make_bulleted_list_block(text: str) -> BulletedListBlock:
+    """Create a Notion bulleted list item block."""
+    return {
+        "object": "block",
+        "type": "bulleted_list_item",
+        "bulleted_list_item": {
+            "rich_text": parse_rich_text(text),
+        },
+    }
+
+
+def make_numbered_list_block(text: str) -> NumberedListBlock:
+    """Create a Notion numbered list item block."""
+    return {
+        "object": "block",
+        "type": "numbered_list_item",
+        "numbered_list_item": {
+            "rich_text": parse_rich_text(text),
+        },
+    }
+
+
+def make_todo_block(text: str, checked: bool = False) -> TodoBlock:
+    """Create a Notion to_do block (checkbox item)."""
+    return {
+        "object": "block",
+        "type": "to_do",
+        "to_do": {
+            "rich_text": parse_rich_text(text),
+            "checked": checked,
+        },
+    }
+
+
+def make_divider_block() -> DividerBlock:
+    """Create a Notion divider block (horizontal rule)."""
+    return {
+        "object": "block",
+        "type": "divider",
+        "divider": {},
+    }
+
+
+def make_quote_block(text: str) -> QuoteBlock:
+    """Create a Notion quote block with rich text formatting."""
+    return {
+        "object": "block",
+        "type": "quote",
+        "quote": {
+            "rich_text": parse_rich_text(text),
+        },
+    }
+
+
+def _extract_block_content(block: Block | PartialBlock | NotionBlock | dict[str, Any]) -> dict[str, Any]:
+    """Extract only the content-relevant parts of a block for comparison.
+
+    Ignores metadata like id, created_time, last_edited_time, etc.
+    """
+    from .markdown import rich_text_to_markdown
+
+    block_type = block.get("type")
+    if not block_type:
+        return {}
+
+    block_data = block.get(block_type, {})
+
+    if block_type == "divider":
+        return {"type": "divider"}
+
+    if block_type in ("paragraph", "heading_1", "heading_2", "heading_3", "bulleted_list_item", "numbered_list_item"):
+        rich_text = block_data.get("rich_text", [])
+        return {"type": block_type, "text": rich_text_to_markdown(rich_text)}
+
+    if block_type == "to_do":
+        rich_text = block_data.get("rich_text", [])
+        return {
+            "type": block_type,
+            "text": rich_text_to_markdown(rich_text),
+            "checked": block_data.get("checked", False),
+        }
+
+    if block_type == "code":
+        rich_text = block_data.get("rich_text", [])
+        code = "".join(item.get("text", {}).get("content", "") for item in rich_text)
+        return {"type": block_type, "code": code, "language": block_data.get("language", "")}
+
+    if block_type in ("quote", "callout"):
+        rich_text = block_data.get("rich_text", [])
+        result: dict[str, Any] = {"type": block_type, "text": rich_text_to_markdown(rich_text)}
+        if block_type == "callout":
+            icon = block_data.get("icon", {})
+            result["emoji"] = icon.get("emoji", "")
+        return result
+
+    return {"type": block_type}
+
+
+def blocks_content_equal(
+    existing: Block | PartialBlock | dict[str, Any],
+    new: NotionBlock | dict[str, Any],
+) -> bool:
+    """Check if two blocks have equivalent content.
+
+    Compares only content-relevant fields, ignoring metadata like IDs and timestamps.
+    This allows comparing an existing Notion block (with full metadata) against
+    a newly created block (without IDs).
+
+    Args:
+        existing: An existing block from Notion (has id, timestamps, etc.)
+        new: A new block to compare (may not have id/timestamps)
+
+    Returns:
+        True if the blocks have equivalent content
+    """
+    return _extract_block_content(existing) == _extract_block_content(new)
+
+
+def find_divergence_index(
+    existing_blocks: Sequence[Block | PartialBlock] | Sequence[dict[str, Any]],
+    new_blocks: Sequence[NotionBlock | dict[str, Any]],
+) -> int:
+    """Find the index where existing blocks start to differ from new blocks.
+
+    Compares blocks from the start until a difference is found.
+    Blocks that match are preserved (keeping their IDs and comments).
+
+    Args:
+        existing_blocks: Current blocks from Notion
+        new_blocks: New blocks to replace the content
+
+    Returns:
+        Index of first differing block. Returns min(len(existing), len(new))
+        if all compared blocks match.
+    """
+    min_len = min(len(existing_blocks), len(new_blocks))
+    for i in range(min_len):
+        if not blocks_content_equal(existing_blocks[i], new_blocks[i]):
+            return i
+    return min_len

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