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

notionary/blocks/image/image_markdown_node.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+from typing import Optional
+from pydantic import BaseModel
+from notionary.blocks.markdown_node import MarkdownNode
+
+
+class ImageMarkdownBlockParams(BaseModel):
+    url: str
+    caption: Optional[str] = None
+
+
+class ImageMarkdownNode(MarkdownNode):
+    """
+    Programmatic interface for creating Notion-style image blocks.
+    Example: [image](https://example.com/image.jpg "Optional caption")
+    """
+
+    def __init__(
+        self, url: str, caption: Optional[str] = None, alt: Optional[str] = None
+    ):
+        self.url = url
+        self.caption = caption
+        # Note: 'alt' is kept for API compatibility but not used in Notion syntax
+
+    @classmethod
+    def from_params(cls, params: ImageMarkdownBlockParams) -> ImageMarkdownNode:
+        return cls(url=params.url, caption=params.caption)
+
+    def to_markdown(self) -> str:
+        if self.caption:
+            return f'[image]({self.url} "{self.caption}")'
+        return f"[image]({self.url})"

notionary/blocks/markdown_builder.py

@@ -0,0 +1,356 @@
+"""
+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/markdown_node.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+from abc import ABC, abstractmethod
+
+
+class MarkdownNode(ABC):
+    """
+    Abstract base class for all Markdown block elements.
+    Enforces implementation of to_markdown().
+    """
+
+    @abstractmethod
+    def to_markdown(self) -> str:
+        """
+        Returns the Markdown representation of the block.
+        Must be implemented by subclasses.
+        """
+        pass
+
+    @classmethod
+    @abstractmethod
+    def from_params(cls, params) -> MarkdownNode:
+        """
+        Creates an instance from a params object.
+        Must be implemented by subclasses.
+        """
+        pass
+
+    def __str__(self):
+        return self.to_markdown()

notionary/blocks/mention/__init__.py

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

notionary/blocks/{mention_element.py → mention/mention_element.py}

@@ -2,7 +2,11 @@ import re
 from typing import Dict, Any, Optional, List
 
 from notionary.blocks import NotionBlockElement
-from notionary.blocks import ElementPromptContent, ElementPromptBuilder
+from notionary.blocks import (
+    ElementPromptContent,
+    ElementPromptBuilder,
+    NotionBlockResult,
+)
 
 
 class MentionElement(NotionBlockElement):
@@ -74,7 +78,7 @@ class MentionElement(NotionBlockElement):
         return any(text_item.get("type") == "mention" for text_item in rich_text)
 
     @classmethod
-    def markdown_to_notion(cls, text: str) -> Optional[Dict[str, Any]]:
+    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

notionary/blocks/mention/mention_markdown_node.py

@@ -0,0 +1,38 @@
+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}]"

notionary/blocks/numbered_list/__init__.py

@@ -0,0 +1,7 @@
+from .numbered_list_element import NumberedListElement
+from .numbered_list_markdown_node import NumberedListMarkdownNode
+
+__all__ = [
+    "NumberedListElement",
+    "NumberedListMarkdownNode",
+]

notionary/blocks/{numbered_list_element.py → numbered_list/numbered_list_element.py}

@@ -1,15 +1,19 @@
 import re
-from typing import Dict, Any, Optional
+from typing import Any, Optional
 from notionary.blocks import NotionBlockElement
-from notionary.blocks import ElementPromptContent, ElementPromptBuilder
-from notionary.blocks.text_inline_formatter import TextInlineFormatter
+from notionary.blocks import (
+    ElementPromptContent,
+    ElementPromptBuilder,
+    NotionBlockResult,
+)
+from notionary.blocks.shared.text_inline_formatter import TextInlineFormatter
 
 
 class NumberedListElement(NotionBlockElement):
     """Class for converting between Markdown numbered lists and Notion numbered list items."""
 
     @classmethod
-    def markdown_to_notion(cls, text: str) -> Optional[Dict[str, Any]]:
+    def markdown_to_notion(cls, text: str) -> NotionBlockResult:
         """Convert markdown numbered list item to Notion block."""
         pattern = re.compile(r"^\s*(\d+)\.\s+(.+)$")
         numbered_match = pattern.match(text)
@@ -27,7 +31,7 @@ class NumberedListElement(NotionBlockElement):
         }
 
     @classmethod
-    def notion_to_markdown(cls, block: Dict[str, Any]) -> Optional[str]:
+    def notion_to_markdown(cls, block: dict[str, Any]) -> Optional[str]:
         """Convert Notion numbered list item block to markdown."""
         if block.get("type") != "numbered_list_item":
             return None
@@ -44,7 +48,7 @@ class NumberedListElement(NotionBlockElement):
         return bool(pattern.match(text))
 
     @classmethod
-    def match_notion(cls, block: Dict[str, Any]) -> bool:
+    def match_notion(cls, block: dict[str, Any]) -> bool:
         """Check if this element can handle the given Notion block."""
         return block.get("type") == "numbered_list_item"
 

notionary/blocks/numbered_list/numbered_list_markdown_node.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+from pydantic import BaseModel
+from notionary.blocks.markdown_node import MarkdownNode
+
+
+class NumberedListMarkdownBlockParams(BaseModel):
+    texts: list[str]
+
+
+class NumberedListMarkdownNode(MarkdownNode):
+    """
+    Programmatic interface for creating Markdown numbered list items.
+    Example:
+    1. First step
+    2. Second step
+    3. Third step
+    """
+
+    def __init__(self, texts: list[str]):
+        self.texts = texts
+
+    @classmethod
+    def from_params(
+        cls, params: NumberedListMarkdownBlockParams
+    ) -> NumberedListMarkdownNode:
+        return cls(texts=params.texts)
+
+    def to_markdown(self) -> str:
+        return "\n".join(f"{i + 1}. {text}" for i, text in enumerate(self.texts))

notionary/blocks/paragraph/__init__.py

@@ -0,0 +1,7 @@
+from .paragraph_element import ParagraphElement
+from .paragraph_markdown_node import ParagraphMarkdownNode
+
+__all__ = [
+    "ParagraphElement",
+    "ParagraphMarkdownNode",
+]

notionary/blocks/{paragraph_element.py → paragraph/paragraph_element.py}

@@ -1,8 +1,12 @@
 from typing import Dict, Any, Optional
 
 from notionary.blocks import NotionBlockElement
-from notionary.blocks import ElementPromptContent, ElementPromptBuilder
-from notionary.blocks.text_inline_formatter import TextInlineFormatter
+from notionary.blocks import (
+    ElementPromptContent,
+    ElementPromptBuilder,
+    NotionBlockResult,
+)
+from notionary.blocks.shared.text_inline_formatter import TextInlineFormatter
 
 
 class ParagraphElement(NotionBlockElement):
@@ -23,7 +27,7 @@ class ParagraphElement(NotionBlockElement):
         return block.get("type") == "paragraph"
 
     @classmethod
-    def markdown_to_notion(cls, text: str) -> Optional[Dict[str, Any]]:
+    def markdown_to_notion(cls, text: str) -> NotionBlockResult:
         """Convert markdown paragraph to Notion paragraph block."""
         if not text.strip():
             return None

notionary/blocks/paragraph/paragraph_markdown_node.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from pydantic import BaseModel
+from notionary.blocks.markdown_node import MarkdownNode
+
+
+class ParagraphMarkdownBlockParams(BaseModel):
+    text: str
+
+
+class ParagraphMarkdownNode(MarkdownNode):
+    """
+    Programmatic interface for creating Markdown paragraphs.
+    Paragraphs are standard text without special block formatting.
+    """
+
+    def __init__(self, text: str):
+        self.text = text
+
+    @classmethod
+    def from_params(cls, params: ParagraphMarkdownBlockParams) -> ParagraphMarkdownNode:
+        return cls(text=params.text)
+
+    def to_markdown(self) -> str:
+        return self.text

notionary/blocks/quote/__init__.py

@@ -0,0 +1,7 @@
+from .quote_element import QuoteElement
+from .quote_markdown_node import QuoteMarkdownNode
+
+__all__ = [
+    "QuoteElement",
+    "QuoteMarkdownNode",
+]