notionary 0.2.16__py3-none-any.whl → 0.2.18__py3-none-any.whl

notionary/blocks/{image_element.py → image/image_element.py}

@@ -1,8 +1,12 @@
 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 ImageElement(NotionBlockElement):
@@ -10,23 +14,26 @@ class ImageElement(NotionBlockElement):
     Handles conversion between Markdown images and Notion image blocks.
 
     Markdown image syntax:
-    - ![Caption](https://example.com/image.jpg) - Basic image with caption
-    - ![](https://example.com/image.jpg) - Image without caption
-    - ![Caption](https://example.com/image.jpg "alt text") - Image with caption and alt text
+    - [image](https://example.com/image.jpg) - Simple image with URL only
+    - [image](https://example.com/image.jpg "Caption") - Image with URL and caption
+
+    Where:
+    - URL is the required image URL
+    - Caption is an optional descriptive text (enclosed in quotes)
     """
 
-    # Regex pattern for image syntax with optional alt text
+    # Regex pattern for image syntax with optional caption
     PATTERN = re.compile(
-        r"^\!\[(.*?)\]"  # ![Caption] part
-        + r'\((https?://[^\s"]+)'  # (URL part
-        + r'(?:\s+"([^"]+)")?'  # Optional alt text in quotes
+        r"^\[image\]\("  # [image]( prefix
+        + r'(https?://[^\s"]+)'  # URL (required)
+        + r'(?:\s+"([^"]+)")?'  # Optional caption in quotes
         + r"\)$"  # closing parenthesis
     )
 
     @classmethod
     def match_markdown(cls, text: str) -> bool:
         """Check if text is a markdown image."""
-        return text.strip().startswith("![") and bool(
+        return text.strip().startswith("[image]") and bool(
             ImageElement.PATTERN.match(text.strip())
         )
 
@@ -36,31 +43,33 @@ class ImageElement(NotionBlockElement):
         return block.get("type") == "image"
 
     @classmethod
-    def markdown_to_notion(cls, text: str) -> Optional[Dict[str, Any]]:
+    def markdown_to_notion(cls, text: str) -> NotionBlockResult:
         """Convert markdown image to Notion image block."""
         image_match = ImageElement.PATTERN.match(text.strip())
         if not image_match:
             return None
 
-        caption = image_match.group(1)
-        url = image_match.group(2)
+        url = image_match.group(1)
+        caption = image_match.group(2)
 
         if not url:
             return None
 
-        # Prepare the image block
-        image_block = {
-            "type": "image",
-            "image": {"type": "external", "external": {"url": url}},
-        }
+        image_data = {"type": "external", "external": {"url": url}}
 
         # Add caption if provided
         if caption:
-            image_block["image"]["caption"] = [
-                {"type": "text", "text": {"content": caption}}
-            ]
+            image_data["caption"] = [{"type": "text", "text": {"content": caption}}]
+        else:
+            image_data["caption"] = []
+
+        # Prepare the image block
+        image_block = {"type": "image", "image": image_data}
+
+        # Add empty paragraph after image
+        empty_paragraph = {"type": "paragraph", "paragraph": {"rich_text": []}}
 
-        return image_block
+        return [image_block, empty_paragraph]
 
     @classmethod
     def notion_to_markdown(cls, block: Dict[str, Any]) -> Optional[str]:
@@ -71,23 +80,37 @@ class ImageElement(NotionBlockElement):
         image_data = block.get("image", {})
 
         # Handle both external and file (uploaded) images
-        if image_data.get("type") == "external":
-            url = image_data.get("external", {}).get("url", "")
-        elif image_data.get("type") == "file":
-            url = image_data.get("file", {}).get("url", "")
-        else:
-            return None
-
+        url = ImageElement._extract_image_url(image_data)
         if not url:
             return None
 
-        # Extract caption if available
-        caption = ""
         caption_rich_text = image_data.get("caption", [])
-        if caption_rich_text:
-            caption = ImageElement._extract_text_content(caption_rich_text)
 
-        return f"![{caption}]({url})"
+        if not caption_rich_text:
+            # Simple image with URL only
+            return f"[image]({url})"
+
+        # Extract caption text
+        caption = ImageElement._extract_text_content(caption_rich_text)
+
+        if caption:
+            return f'[image]({url} "{caption}")'
+
+        return f"[image]({url})"
+
+    @classmethod
+    def is_multiline(cls) -> bool:
+        """Images are single-line elements."""
+        return False
+
+    @classmethod
+    def _extract_image_url(cls, image_data: Dict[str, Any]) -> str:
+        """Extract URL from image data, handling both external and uploaded images."""
+        if image_data.get("type") == "external":
+            return image_data.get("external", {}).get("url", "")
+        elif image_data.get("type") == "file":
+            return image_data.get("file", {}).get("url", "")
+        return ""
 
     @classmethod
     def _extract_text_content(cls, rich_text: List[Dict[str, Any]]) -> str:
@@ -100,10 +123,6 @@ class ImageElement(NotionBlockElement):
                 result += text_obj.get("plain_text", "")
         return result
 
-    @classmethod
-    def is_multiline(cls) -> bool:
-        return False
-
     @classmethod
     def get_llm_prompt_content(cls) -> ElementPromptContent:
         """
@@ -119,12 +138,13 @@ class ImageElement(NotionBlockElement):
                 "that enhance your document. Images can make complex information easier to understand, create visual interest, "
                 "or provide evidence for your points."
             )
-            .with_syntax("![Caption](https://example.com/image.jpg)")
+            .with_syntax('[image](https://example.com/image.jpg "Optional caption")')
             .with_examples(
                 [
-                    "![Data visualization showing monthly trends](https://example.com/chart.png)",
-                    "![](https://example.com/screenshot.jpg)",
-                    '![Company logo](https://company.com/logo.png "Company Inc. logo")',
+                    "[image](https://example.com/chart.png)",
+                    '[image](https://example.com/screenshot.jpg "Data visualization showing monthly trends")',
+                    '[image](https://company.com/logo.png "Company Inc. logo")',
+                    '[image](https://example.com/diagram.jpg "System architecture overview")',
                 ]
             )
             .build()

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",
+]