notionary 0.2.19__py3-none-any.whl → 0.2.22__py3-none-any.whl

notionary/blocks/markdown_builder.py

@@ -1,356 +0,0 @@
-"""
-Clean Fluent Markdown Builder
-============================
-
-A direct, chainable builder for all MarkdownNode types without overengineering.
-Maps 1:1 to the available blocks with clear, expressive method names.
-"""
-
-from __future__ import annotations
-from typing import Optional, Self, Union
-
-from notionary.blocks import (
-    HeadingMarkdownNode,
-    ImageMarkdownNode,
-    ParagraphMarkdownNode,
-    AudioMarkdownNode,
-    BookmarkMarkdownNode,
-    CalloutMarkdownNode,
-    CodeMarkdownNode,
-    DividerMarkdownNode,
-    DocumentMarkdownNode,
-    EmbedMarkdownNode,
-    MentionMarkdownNode,
-    NumberedListMarkdownNode,
-    BulletedListMarkdownNode,
-    QuoteMarkdownNode,
-    TableMarkdownNode,
-    TodoMarkdownNode,
-    ToggleMarkdownNode,
-    ToggleableHeadingMarkdownNode,
-    VideoMarkdownNode,
-    MarkdownNode,
-)
-
-
-class MarkdownBuilder:
-    """
-    Fluent interface builder for creating Notion content with clean, direct methods.
-    """
-
-    def __init__(self) -> None:
-        self.children: list[MarkdownNode] = []
-
-    def h1(self, text: str) -> Self:
-        """
-        Add an H1 heading.
-
-        Args:
-            text: The heading text content
-        """
-        self.children.append(HeadingMarkdownNode(text=text, level=1))
-        return self
-
-    def h2(self, text: str) -> Self:
-        """
-        Add an H2 heading.
-
-        Args:
-            text: The heading text content
-        """
-        self.children.append(HeadingMarkdownNode(text=text, level=2))
-        return self
-
-    def h3(self, text: str) -> Self:
-        """
-        Add an H3 heading.
-
-        Args:
-            text: The heading text content
-        """
-        self.children.append(HeadingMarkdownNode(text=text, level=3))
-        return self
-
-    def heading(self, text: str, level: int = 2) -> Self:
-        """
-        Add a heading with specified level.
-
-        Args:
-            text: The heading text content
-            level: Heading level (1-3), defaults to 2
-        """
-        self.children.append(HeadingMarkdownNode(text=text, level=level))
-        return self
-
-    def paragraph(self, text: str) -> Self:
-        """
-        Add a paragraph block.
-
-        Args:
-            text: The paragraph text content
-        """
-        self.children.append(ParagraphMarkdownNode(text=text))
-        return self
-
-    def text(self, content: str) -> Self:
-        """
-        Add a text paragraph (alias for paragraph).
-
-        Args:
-            content: The text content
-        """
-        return self.paragraph(content)
-
-    def quote(self, text: str, author: Optional[str] = None) -> Self:
-        """
-        Add a blockquote.
-
-        Args:
-            text: Quote text content
-            author: Optional quote author/attribution
-        """
-        self.children.append(QuoteMarkdownNode(text=text, author=author))
-        return self
-
-    def divider(self) -> Self:
-        """Add a horizontal divider."""
-        self.children.append(DividerMarkdownNode())
-        return self
-
-    def numbered_list(self, items: list[str]) -> Self:
-        """
-        Add a numbered list.
-
-        Args:
-            items: List of text items for the numbered list
-        """
-        self.children.append(NumberedListMarkdownNode(texts=items))
-        return self
-
-    def bulleted_list(self, items: list[str]) -> Self:
-        """
-        Add a bulleted list.
-
-        Args:
-            items: List of text items for the bulleted list
-        """
-        self.children.append(BulletedListMarkdownNode(texts=items))
-        return self
-
-    def todo(self, text: str, checked: bool = False) -> Self:
-        """
-        Add a single todo item.
-
-        Args:
-            text: The todo item text
-            checked: Whether the todo item is completed, defaults to False
-        """
-        self.children.append(TodoMarkdownNode(text=text, checked=checked))
-        return self
-
-    def todo_list(
-        self, items: list[str], completed: Optional[list[bool]] = None
-    ) -> Self:
-        """
-        Add multiple todo items.
-
-        Args:
-            items: List of todo item texts
-            completed: List of completion states for each item, defaults to all False
-        """
-        if completed is None:
-            completed = [False] * len(items)
-
-        for i, item in enumerate(items):
-            is_done = completed[i] if i < len(completed) else False
-            self.children.append(TodoMarkdownNode(text=item, checked=is_done))
-        return self
-
-    def callout(self, text: str, emoji: Optional[str] = None) -> Self:
-        """
-        Add a callout block.
-
-        Args:
-            text: The callout text content
-            emoji: Optional emoji for the callout icon
-        """
-        self.children.append(CalloutMarkdownNode(text=text, emoji=emoji))
-        return self
-
-    def toggle(self, title: str, content: Optional[list[str]] = None) -> Self:
-        """
-        Add a toggle block.
-
-        Args:
-            title: The toggle title/header text
-            content: Optional list of content items inside the toggle
-        """
-        self.children.append(ToggleMarkdownNode(title=title, content=content))
-        return self
-
-    def toggleable_heading(
-        self, text: str, level: int = 2, content: Optional[list[str]] = None
-    ) -> Self:
-        """
-        Add a toggleable heading.
-
-        Args:
-            text: The heading text content
-            level: Heading level (1-3), defaults to 2
-            content: Optional list of content items inside the toggleable heading
-        """
-        self.children.append(
-            ToggleableHeadingMarkdownNode(text=text, level=level, content=content)
-        )
-        return self
-
-    def image(
-        self, url: str, caption: Optional[str] = None, alt: Optional[str] = None
-    ) -> Self:
-        """
-        Add an image.
-
-        Args:
-            url: Image URL or file path
-            caption: Optional image caption text
-            alt: Optional alternative text for accessibility
-        """
-        self.children.append(ImageMarkdownNode(url=url, caption=caption, alt=alt))
-        return self
-
-    def video(self, url: str, caption: Optional[str] = None) -> Self:
-        """
-        Add a video.
-
-        Args:
-            url: Video URL or file path
-            caption: Optional video caption text
-        """
-        self.children.append(VideoMarkdownNode(url=url, caption=caption))
-        return self
-
-    def audio(self, url: str, caption: Optional[str] = None) -> Self:
-        """
-        Add audio content.
-
-        Args:
-            url: Audio file URL or path
-            caption: Optional audio caption text
-        """
-        self.children.append(AudioMarkdownNode(url=url, caption=caption))
-        return self
-
-    def document(self, url: str, caption: Optional[str] = None) -> Self:
-        """
-        Add a document file.
-
-        Args:
-            url: Document file URL or path
-            caption: Optional document caption text
-        """
-        self.children.append(DocumentMarkdownNode(url=url, caption=caption))
-        return self
-
-    def bookmark(
-        self, url: str, title: Optional[str] = None, description: Optional[str] = None
-    ) -> Self:
-        """
-        Add a bookmark.
-
-        Args:
-            url: Bookmark URL
-            title: Optional bookmark title
-            description: Optional bookmark description text
-        """
-        self.children.append(
-            BookmarkMarkdownNode(url=url, title=title, description=description)
-        )
-        return self
-
-    def embed(self, url: str, caption: Optional[str] = None) -> Self:
-        """
-        Add an embed.
-
-        Args:
-            url: URL to embed (e.g., YouTube, Twitter, etc.)
-            caption: Optional embed caption text
-        """
-        self.children.append(EmbedMarkdownNode(url=url, caption=caption))
-        return self
-
-    def code(
-        self, code: str, language: Optional[str] = None, caption: Optional[str] = None
-    ) -> Self:
-        """
-        Add a code block.
-
-        Args:
-            code: The source code content
-            language: Optional programming language for syntax highlighting
-            caption: Optional code block caption text
-        """
-        self.children.append(
-            CodeMarkdownNode(code=code, language=language, caption=caption)
-        )
-        return self
-
-    def table(self, headers: list[str], rows: list[list[str]]) -> Self:
-        """
-        Add a table.
-
-        Args:
-            headers: List of column header texts
-            rows: List of rows, where each row is a list of cell texts
-        """
-        self.children.append(TableMarkdownNode(headers=headers, rows=rows))
-        return self
-
-    def mention_page(self, page_id: str) -> Self:
-        """
-        Add a page mention.
-
-        Args:
-            page_id: The ID of the page to mention
-        """
-        self.children.append(MentionMarkdownNode("page", page_id))
-        return self
-
-    def mention_database(self, database_id: str) -> Self:
-        """
-        Add a database mention.
-
-        Args:
-            database_id: The ID of the database to mention
-        """
-        self.children.append(MentionMarkdownNode("database", database_id))
-        return self
-
-    def mention_date(self, date: str) -> Self:
-        """
-        Add a date mention.
-
-        Args:
-            date: Date in YYYY-MM-DD format
-        """
-        self.children.append(MentionMarkdownNode("date", date))
-        return self
-
-    def add_custom(self, node: MarkdownNode) -> Self:
-        """
-        Add a custom MarkdownNode.
-
-        Args:
-            node: A custom MarkdownNode instance
-        """
-        self.children.append(node)
-        return self
-
-    def space(self) -> Self:
-        """Add vertical spacing."""
-        return self.paragraph("")
-
-    def build(self) -> str:
-        """Build and return the final markdown string."""
-        return "\n\n".join(
-            child.to_markdown() for child in self.children if child is not None
-        )

notionary/blocks/mention/__init__.py

@@ -1,7 +0,0 @@
-from .mention_element import MentionElement
-from .mention_markdown_node import MentionMarkdownNode
-
-__all__ = [
-    "MentionElement",
-    "MentionMarkdownNode",
-]

notionary/blocks/mention/mention_element.py

@@ -1,229 +0,0 @@
-import re
-from typing import Dict, Any, Optional, List
-
-from notionary.blocks import NotionBlockElement
-from notionary.blocks import (
-    ElementPromptContent,
-    ElementPromptBuilder,
-    NotionBlockResult,
-)
-
-
-class MentionElement(NotionBlockElement):
-    """
-    Handles conversion between Markdown mentions and Notion mention elements.
-
-    Markdown mention syntax:
-    - @[page-id] - Mention a page by its ID
-    - @date[YYYY-MM-DD] - Mention a date
-    - @db[database-id] - Mention a database by its ID
-    """
-
-    MENTION_TYPES = {
-        "page": {
-            "pattern": r"@\[([0-9a-f-]+)\]",
-            "create_mention": lambda id_value: {
-                "type": "mention",
-                "mention": {"type": "page", "page": {"id": id_value}},
-            },
-            "get_plain_text": lambda mention: f"Page {mention['mention']['page']['id']}",
-            "to_markdown": lambda mention: f"@[{mention['mention']['page']['id']}]",
-        },
-        "date": {
-            "pattern": r"@date\[(\d{4}-\d{2}-\d{2})\]",
-            "create_mention": lambda date_value: {
-                "type": "mention",
-                "mention": {"type": "date", "date": {"start": date_value, "end": None}},
-            },
-            "get_plain_text": lambda mention: mention["mention"]["date"]["start"],
-            "to_markdown": lambda mention: f"@date[{mention['mention']['date']['start']}]",
-        },
-        "database": {
-            "pattern": r"@db\[([0-9a-f-]+)\]",
-            "create_mention": lambda db_id: {
-                "type": "mention",
-                "mention": {"type": "database", "database": {"id": db_id}},
-            },
-            "get_plain_text": lambda mention: f"Database {mention['mention']['database']['id']}",
-            "to_markdown": lambda mention: f"@db[{mention['mention']['database']['id']}]",
-        },
-    }
-
-    @classmethod
-    def match_markdown(cls, text: str) -> bool:
-        """Check if text contains a markdown mention."""
-        for mention_type in MentionElement.MENTION_TYPES.values():
-            if re.search(mention_type["pattern"], text):
-                return True
-        return False
-
-    @classmethod
-    def match_notion(cls, block: Dict[str, Any]) -> bool:
-        """Check if block contains a mention."""
-        supported_block_types = [
-            "paragraph",
-            "heading_1",
-            "heading_2",
-            "heading_3",
-            "bulleted_list_item",
-            "numbered_list_item",
-        ]
-
-        if block.get("type") not in supported_block_types:
-            return False
-
-        block_content = block.get(block.get("type"), {})
-        rich_text = block_content.get("rich_text", [])
-
-        return any(text_item.get("type") == "mention" for text_item in rich_text)
-
-    @classmethod
-    def markdown_to_notion(cls, text: str) -> NotionBlockResult:
-        """Convert markdown text with mentions to a Notion paragraph block."""
-        if not MentionElement.match_markdown(text):
-            return None
-
-        rich_text = MentionElement._process_markdown_with_mentions(text)
-
-        return {
-            "type": "paragraph",
-            "paragraph": {"rich_text": rich_text, "color": "default"},
-        }
-
-    @classmethod
-    def _process_markdown_with_mentions(cls, text: str) -> List[Dict[str, Any]]:
-        """Convert markdown mentions to Notion rich_text format."""
-        mentions = []
-
-        for mention_type, config in MentionElement.MENTION_TYPES.items():
-            for match in re.finditer(config["pattern"], text):
-                mentions.append(
-                    {
-                        "start": match.start(),
-                        "end": match.end(),
-                        "type": mention_type,
-                        "value": match.group(1),
-                        "original": match.group(0),
-                    }
-                )
-
-        mentions.sort(key=lambda m: m["start"])
-
-        # Build rich_text list
-        rich_text = []
-        position = 0
-
-        for mention in mentions:
-            if mention["start"] > position:
-                rich_text.append(
-                    MentionElement._create_text_item(text[position : mention["start"]])
-                )
-
-            # Add the mention
-            mention_obj = MentionElement.MENTION_TYPES[mention["type"]][
-                "create_mention"
-            ](mention["value"])
-
-            # Add annotations and plain text
-            mention_obj["annotations"] = MentionElement._default_annotations()
-            mention_obj["plain_text"] = MentionElement.MENTION_TYPES[mention["type"]][
-                "get_plain_text"
-            ](mention_obj)
-
-            rich_text.append(mention_obj)
-            position = mention["end"]
-
-        # Add remaining text if any
-        if position < len(text):
-            rich_text.append(MentionElement._create_text_item(text[position:]))
-
-        return rich_text
-
-    @classmethod
-    def _create_text_item(cls, content: str) -> Dict[str, Any]:
-        """Create a text item with default annotations."""
-        text_item = {
-            "type": "text",
-            "text": {"content": content, "link": None},
-            "annotations": MentionElement._default_annotations(),
-            "plain_text": content,
-        }
-        return text_item
-
-    @classmethod
-    def _default_annotations(cls) -> Dict[str, Any]:
-        """Return default annotations for rich text."""
-        return {
-            "bold": False,
-            "italic": False,
-            "strikethrough": False,
-            "underline": False,
-            "code": False,
-            "color": "default",
-        }
-
-    @classmethod
-    def notion_to_markdown(cls, block: Dict[str, Any]) -> Optional[str]:
-        """Extract mentions from Notion block and convert to markdown format."""
-        block_type = block.get("type")
-        if not block_type or block_type not in block:
-            return None
-
-        block_content = block.get(block_type, {})
-        rich_text = block_content.get("rich_text", [])
-
-        processed_text = MentionElement._process_rich_text_with_mentions(rich_text)
-
-        if processed_text:
-            return processed_text
-
-        return None
-
-    @classmethod
-    def _process_rich_text_with_mentions(cls, rich_text: List[Dict[str, Any]]) -> str:
-        """Convert rich text with mentions to markdown string."""
-        result = []
-
-        for item in rich_text:
-            if item.get("type") == "mention":
-                mention = item.get("mention", {})
-                mention_type = mention.get("type")
-
-                if mention_type in MentionElement.MENTION_TYPES:
-                    result.append(
-                        MentionElement.MENTION_TYPES[mention_type]["to_markdown"](item)
-                    )
-                else:
-                    result.append(item.get("plain_text", "@[unknown]"))
-            else:
-                result.append(item.get("plain_text", ""))
-
-        return "".join(result)
-
-    @classmethod
-    def is_multiline(cls) -> bool:
-        return False
-
-    @classmethod
-    def get_llm_prompt_content(cls) -> ElementPromptContent:
-        """
-        Returns structured LLM prompt metadata for the mention element.
-        """
-        return (
-            ElementPromptBuilder()
-            .with_description(
-                "References to Notion pages, databases, or dates within text content."
-            )
-            .with_usage_guidelines(
-                "When you want to link to other Notion content within your text."
-            )
-            .with_syntax("@[page-id]")
-            .with_examples(
-                [
-                    "Check the meeting notes at @[1a6389d5-7bd3-80c5-9a87-e90b034989d0]",
-                    "Deadline is @date[2023-12-31]",
-                    "Use the structure in @db[1a6389d5-7bd3-80e9-b199-000cfb3fa0b3]",
-                ]
-            )
-            .build()
-        )

notionary/blocks/mention/mention_markdown_node.py

@@ -1,38 +0,0 @@
-from __future__ import annotations
-from typing import Literal
-from pydantic import BaseModel
-from notionary.blocks.markdown_node import MarkdownNode
-
-
-class MentionMarkdownBlockParams(BaseModel):
-    mention_type: Literal["page", "database", "date"]
-    value: str
-
-
-class MentionMarkdownNode(MarkdownNode):
-    """
-    Programmatic interface for creating Notion-style Markdown mentions.
-    Supports: page, database, date.
-    Examples: @[page-id], @db[database-id], @date[YYYY-MM-DD]
-    """
-
-    def __init__(self, mention_type: str, value: str):
-        allowed = {"page", "database", "date"}
-        if mention_type not in allowed:
-            raise ValueError(f"mention_type must be one of {allowed}")
-        self.mention_type = mention_type
-        self.value = value
-
-    @classmethod
-    def from_params(cls, params: MentionMarkdownBlockParams) -> MentionMarkdownNode:
-        return cls(mention_type=params.mention_type, value=params.value)
-
-    def to_markdown(self) -> str:
-        if self.mention_type == "page":
-            return f"@[{self.value}]"
-        elif self.mention_type == "database":
-            return f"@db[{self.value}]"
-        elif self.mention_type == "date":
-            return f"@date[{self.value}]"
-        else:
-            return f"@[{self.value}]"