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

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
 
 

tracktolib/notion/markdown.py

@@ -0,0 +1,468 @@
+"""Markdown conversion utilities for Notion blocks."""
+
+from __future__ import annotations
+
+import re
+from typing import TYPE_CHECKING, Any, Sequence
+
+from ..utils import get_chunks
+from .blocks import (
+    BulletedListBlock,
+    DividerBlock,
+    NumberedListBlock,
+    ParagraphBlock,
+    QuoteBlock,
+    TodoBlock,
+    make_bulleted_list_block,
+    make_code_block,
+    make_divider_block,
+    make_heading_block,
+    make_numbered_list_block,
+    make_paragraph_block,
+    make_quote_block,
+    make_todo_block,
+)
+
+# Union type for all Notion blocks used in markdown conversion
+NotionBlock = ParagraphBlock | DividerBlock | BulletedListBlock | NumberedListBlock | TodoBlock | QuoteBlock
+
+if TYPE_CHECKING:
+    from .models import Block, Comment, PartialBlock, RichTextItemResponse
+
+__all__ = [
+    "NOTION_CHAR_LIMIT",
+    "NotionBlock",
+    "blocks_to_markdown",
+    "blocks_to_markdown_with_comments",
+    "comments_to_markdown",
+    "markdown_to_blocks",
+    "rich_text_to_markdown",
+    "strip_comments_from_markdown",
+]
+
+# Notion's character limit per rich_text element
+NOTION_CHAR_LIMIT = 2000
+
+# Markdown block patterns (pre-compiled for performance)
+_CODE_FENCE_PATTERN = re.compile(r"^```(\w*)$")
+_HORIZONTAL_RULE_PATTERN = re.compile(r"^[-*_]{3,}\s*$")
+_HEADING_PATTERN = re.compile(r"^(#{1,6})\s+(.+)$")
+_TODO_PATTERN = re.compile(r"^\s*[-*]\s*\[([xX ])\]\s*(.*)$")
+_BULLET_PATTERN = re.compile(r"^\s*[-*]\s+(.+)$")
+_NUMBERED_PATTERN = re.compile(r"^\s*\d+\.\s+(.+)$")
+_QUOTE_PATTERN = re.compile(r"^>\s*(.*)$")
+
+
+def rich_text_to_markdown(rich_text: Sequence[RichTextItemResponse] | Sequence[dict[str, Any]]) -> str:
+    """Convert Notion rich_text array to markdown string.
+
+    Handles:
+    - Bold (annotations.bold)
+    - Italic (annotations.italic)
+    - Inline code (annotations.code)
+    - Links (text.link.url)
+    """
+    result = []
+    for item in rich_text:
+        text_obj = item.get("text", {})
+        content = text_obj.get("content", "")
+
+        if not content:
+            continue
+
+        annotations = item.get("annotations", {})
+        link = text_obj.get("link")
+
+        # Apply formatting in order: code, bold, italic
+        if annotations.get("code"):
+            content = f"`{content}`"
+        if annotations.get("bold"):
+            content = f"**{content}**"
+        if annotations.get("italic"):
+            content = f"*{content}*"
+        if link:
+            content = f"[{content}]({link['url']})"
+
+        result.append(content)
+
+    return "".join(result)
+
+
+def markdown_to_blocks(content: str) -> list[NotionBlock | dict[str, Any]]:
+    """Convert markdown content to Notion blocks with proper formatting.
+
+    Handles:
+    - Code blocks (```)
+    - Headings (# ## ### etc)
+    - Bold (**text**)
+    - Inline code (`code`)
+    - Italic (*text*)
+    - Todo items (- [ ] or - [x])
+    - Bulleted lists (- or *)
+    - Numbered lists (1. 2. etc)
+    - Horizontal rules (---)
+
+    Args:
+        content: Markdown content to convert
+
+    Returns:
+        List of Notion block objects (caller handles chunking for API limits)
+    """
+    blocks: list[NotionBlock | dict[str, Any]] = []
+    lines = content.split("\n")
+    i = 0
+
+    while i < len(lines):
+        line = lines[i]
+
+        # Check for fenced code block
+        code_match = _CODE_FENCE_PATTERN.match(line)
+        if code_match:
+            language = code_match.group(1) or "plain text"
+            code_lines = []
+            i += 1
+            while i < len(lines) and not lines[i].startswith("```"):
+                code_lines.append(lines[i])
+                i += 1
+            code_content = "\n".join(code_lines)
+            if code_content:
+                blocks.extend(make_code_block(code_content, language))
+            i += 1  # Skip closing ```
+            continue
+
+        # Check for horizontal rule (---, ***, ___)
+        if _HORIZONTAL_RULE_PATTERN.match(line):
+            blocks.append(make_divider_block())
+            i += 1
+            continue
+
+        # Check for heading
+        heading_match = _HEADING_PATTERN.match(line)
+        if heading_match:
+            level = len(heading_match.group(1))
+            text = heading_match.group(2).strip()
+            blocks.append(make_heading_block(text, level))
+            i += 1
+            continue
+
+        # Check for todo item (- [ ] or - [x]) - must be before bullet list
+        todo_match = _TODO_PATTERN.match(line)
+        if todo_match:
+            checked = todo_match.group(1).lower() == "x"
+            text = todo_match.group(2).strip()
+            blocks.append(make_todo_block(text, checked))
+            i += 1
+            continue
+
+        # Check for bulleted list
+        bullet_match = _BULLET_PATTERN.match(line)
+        if bullet_match:
+            text = bullet_match.group(1).strip()
+            blocks.append(make_bulleted_list_block(text))
+            i += 1
+            continue
+
+        # Check for numbered list
+        numbered_match = _NUMBERED_PATTERN.match(line)
+        if numbered_match:
+            text = numbered_match.group(1).strip()
+            blocks.append(make_numbered_list_block(text))
+            i += 1
+            continue
+
+        # Check for blockquote
+        quote_match = _QUOTE_PATTERN.match(line)
+        if quote_match:
+            text = quote_match.group(1)
+            blocks.append(make_quote_block(text))
+            i += 1
+            continue
+
+        # Empty line - check if it separates quote blocks
+        if not line.strip():
+            # Look ahead to see if next non-empty line is a quote
+            # and previous block was also a quote
+            if blocks and blocks[-1].get("type") == "quote":
+                j = i + 1
+                while j < len(lines) and not lines[j].strip():
+                    j += 1
+                if j < len(lines) and lines[j].startswith(">"):
+                    # Insert empty paragraph to preserve blank line between quotes
+                    blocks.append(make_paragraph_block(""))
+            i += 1
+            continue
+
+        # Regular paragraph - collect consecutive non-empty lines
+        para_lines = [line]
+        i += 1
+        while i < len(lines):
+            next_line = lines[i]
+            # Stop at special lines
+            if (
+                not next_line.strip()
+                or next_line.startswith("#")
+                or next_line.startswith("```")
+                or next_line.startswith(">")
+                or _HORIZONTAL_RULE_PATTERN.match(next_line)
+                or _TODO_PATTERN.match(next_line)
+                or _BULLET_PATTERN.match(next_line)
+                or _NUMBERED_PATTERN.match(next_line)
+            ):
+                break
+            para_lines.append(next_line)
+            i += 1
+
+        para_text = " ".join(ln.strip() for ln in para_lines)
+        if para_text:
+            # Split long paragraphs into chunks
+            if len(para_text) > NOTION_CHAR_LIMIT:
+                for chunk in get_chunks(para_text, NOTION_CHAR_LIMIT):
+                    blocks.append(make_paragraph_block("".join(chunk)))
+            else:
+                blocks.append(make_paragraph_block(para_text))
+
+    return blocks
+
+
+def _block_to_markdown(block: Block | PartialBlock | dict[str, Any]) -> str | None:
+    """Convert a single Notion block to markdown.
+
+    Returns None for unsupported block types.
+    """
+    block_type = block.get("type")
+    if not block_type:
+        return None
+
+    block_data = block.get(block_type, {})
+
+    if block_type == "paragraph":
+        rich_text = block_data.get("rich_text", [])
+        text = rich_text_to_markdown(rich_text)
+        return text if text else ""
+
+    if block_type in ("heading_1", "heading_2", "heading_3"):
+        level = int(block_type[-1])
+        rich_text = block_data.get("rich_text", [])
+        text = rich_text_to_markdown(rich_text)
+        return f"{'#' * level} {text}"
+
+    if block_type == "code":
+        rich_text = block_data.get("rich_text", [])
+        code = "".join(item.get("text", {}).get("content", "") for item in rich_text)
+        language = block_data.get("language", "")
+        # Map Notion language back to common alias
+        if language == "plain text":
+            language = ""
+        return f"```{language}\n{code}\n```"
+
+    if block_type == "bulleted_list_item":
+        rich_text = block_data.get("rich_text", [])
+        text = rich_text_to_markdown(rich_text)
+        return f"- {text}"
+
+    if block_type == "numbered_list_item":
+        rich_text = block_data.get("rich_text", [])
+        text = rich_text_to_markdown(rich_text)
+        return f"1. {text}"
+
+    if block_type == "to_do":
+        rich_text = block_data.get("rich_text", [])
+        text = rich_text_to_markdown(rich_text)
+        checked = block_data.get("checked", False)
+        checkbox = "[x]" if checked else "[ ]"
+        return f"- {checkbox} {text}"
+
+    if block_type == "divider":
+        return "---"
+
+    if block_type == "quote":
+        rich_text = block_data.get("rich_text", [])
+        text = rich_text_to_markdown(rich_text)
+        return f"> {text}"
+
+    if block_type == "callout":
+        rich_text = block_data.get("rich_text", [])
+        text = rich_text_to_markdown(rich_text)
+        icon = block_data.get("icon", {})
+        emoji = icon.get("emoji", "")
+        prefix = f"{emoji} " if emoji else ""
+        return f"> {prefix}{text}"
+
+    # Unsupported block type
+    return None
+
+
+def blocks_to_markdown(blocks: list[Block | PartialBlock] | list[dict[str, Any]]) -> str:
+    """Convert a list of Notion blocks to markdown content.
+
+    Handles:
+    - Paragraphs
+    - Headings (h1, h2, h3)
+    - Code blocks
+    - Bulleted lists
+    - Numbered lists
+    - Todo items
+    - Dividers
+    - Quotes
+    - Callouts
+
+    Args:
+        blocks: List of Notion block objects
+
+    Returns:
+        Markdown string
+    """
+    result: list[str] = []
+    prev_type: str | None = None
+
+    for block in blocks:
+        block_type = block.get("type")
+        md_line = _block_to_markdown(block)
+        if md_line is not None:
+            # Empty paragraph acts as separator (resets consecutive quote joining)
+            if block_type == "paragraph" and md_line == "":
+                prev_type = None
+                continue
+            # Join consecutive quotes with single newline
+            if prev_type == "quote" and block_type == "quote":
+                result.append(f"\n{md_line}")
+            elif result:
+                result.append(f"\n\n{md_line}")
+            else:
+                result.append(md_line)
+            prev_type = block_type
+
+    return "".join(result)
+
+
+def _inline_comment_to_markdown(comment: Comment | dict[str, Any]) -> str:
+    """Convert a single inline comment to markdown format."""
+    rich_text = comment.get("rich_text", [])
+    text = rich_text_to_markdown(rich_text)
+
+    created_by = comment.get("created_by", {})
+    author = created_by.get("name") or created_by.get("id", "Unknown")
+
+    created_time = comment.get("created_time", "")
+    if created_time:
+        timestamp = created_time[:16].replace("T", " ")
+    else:
+        timestamp = ""
+
+    header = f"**{author}**"
+    if timestamp:
+        header += f" - {timestamp}"
+
+    return f"> 💬 {header}: {text}"
+
+
+def blocks_to_markdown_with_comments(
+    blocks: list[Block | PartialBlock] | list[dict[str, Any]],
+    block_comments: dict[str, list[Comment]] | dict[str, list[dict[str, Any]]] | None = None,
+) -> str:
+    """Convert a list of Notion blocks to markdown content with inline comments.
+
+    Args:
+        blocks: List of Notion block objects
+        block_comments: Dictionary mapping block IDs to their comments
+
+    Returns:
+        Markdown string with inline comments after their respective blocks
+    """
+    if block_comments is None:
+        block_comments = {}
+
+    result: list[str] = []
+    prev_type: str | None = None
+
+    for block in blocks:
+        block_type = block.get("type")
+        md_line = _block_to_markdown(block)
+        if md_line is not None:
+            # Empty paragraph acts as separator (resets consecutive quote joining)
+            if block_type == "paragraph" and md_line == "":
+                prev_type = None
+                continue
+            # Join consecutive quotes with single newline
+            if prev_type == "quote" and block_type == "quote":
+                result.append(f"\n{md_line}")
+            elif result:
+                result.append(f"\n\n{md_line}")
+            else:
+                result.append(md_line)
+            prev_type = block_type
+
+            # Add inline comments for this block
+            block_id = block.get("id")
+            if block_id and block_id in block_comments:
+                for comment in block_comments[block_id]:
+                    comment_md = _inline_comment_to_markdown(comment)
+                    result.append(f"\n\n{comment_md}")
+                    prev_type = None  # Reset after comment
+
+    return "".join(result)
+
+
+def comments_to_markdown(comments: list[Comment] | list[dict[str, Any]]) -> str:
+    """Convert a list of Notion comments to markdown.
+
+    Each comment is formatted as a blockquote with author and timestamp.
+
+    Args:
+        comments: List of Notion comment objects
+
+    Returns:
+        Markdown string with comments section
+    """
+    if not comments:
+        return ""
+
+    lines: list[str] = ["## Comments", ""]
+
+    for comment in comments:
+        rich_text = comment.get("rich_text", [])
+        text = rich_text_to_markdown(rich_text)
+
+        # Get author info
+        created_by = comment.get("created_by", {})
+        author = created_by.get("name") or created_by.get("id", "Unknown")
+
+        # Get timestamp
+        created_time = comment.get("created_time", "")
+        if created_time:
+            # Format: 2024-01-15T10:30:00.000Z -> 2024-01-15 10:30
+            timestamp = created_time[:16].replace("T", " ")
+        else:
+            timestamp = ""
+
+        # Format as blockquote with metadata
+        header = f"**{author}**"
+        if timestamp:
+            header += f" - {timestamp}"
+
+        lines.append(f"> {header}")
+        lines.append(f"> {text}")
+        lines.append("")
+
+    return "\n".join(lines)
+
+
+def strip_comments_from_markdown(content: str) -> str:
+    """Remove comment blockquotes (> 💬) from markdown content.
+
+    This is useful when re-uploading markdown that was downloaded with comments,
+    to avoid converting comments into regular quote blocks.
+
+    Args:
+        content: Markdown content potentially containing comment blockquotes
+
+    Returns:
+        Markdown content with comment lines removed
+    """
+    lines = content.splitlines()
+    result = []
+    for line in lines:
+        if line.startswith("> 💬"):
+            continue
+        result.append(line)
+    return "\n".join(result)

tracktolib/notion/models.py

@@ -286,3 +286,29 @@ class SearchResponse(TypedDict):
     results: list[Page | PartialPage | Database | PartialDatabase]
     next_cursor: str | None
     has_more: bool
+
+
+# Comment types
+
+
+class Comment(TypedDict):
+    """Comment object response."""
+
+    object: Literal["comment"]
+    id: str
+    parent: Parent
+    discussion_id: str
+    created_time: str
+    last_edited_time: str
+    created_by: PartialUser
+    rich_text: list[RichTextItemResponse]
+
+
+class CommentListResponse(TypedDict):
+    """Response from listing comments."""
+
+    object: Literal["list"]
+    type: Literal["comment"]
+    results: list[Comment]
+    next_cursor: str | None
+    has_more: bool