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

notionary/blocks/file/file_element.py

@@ -0,0 +1,112 @@
+from __future__ import annotations
+
+import re
+from typing import Optional
+
+from notionary.blocks.base_block_element import BaseBlockElement
+from notionary.blocks.file.file_element_models import (
+    CreateFileBlock,
+    ExternalFile,
+    FileBlock,
+    FileType,
+)
+from notionary.blocks.mixins.captions import CaptionMixin
+from notionary.blocks.syntax_prompt_builder import BlockElementMarkdownInformation
+from notionary.blocks.models import Block, BlockCreateResult, BlockType
+
+
+class FileElement(BaseBlockElement, CaptionMixin):
+    """
+    Handles conversion between Markdown file embeds and Notion file blocks.
+
+    Markdown file syntax:
+    - [file](https://example.com/document.pdf) - URL only
+    - [file](https://example.com/document.pdf)(caption:Annual Report) - URL with caption
+    - (caption:Important document)[file](https://example.com/doc.pdf) - caption before URL
+
+    Supports external file URLs with optional captions.
+    """
+
+    # Simple pattern that matches just the file link, CaptionMixin handles caption separately
+    FILE_PATTERN = re.compile(r"\[file\]\((https?://[^\s\"]+)\)")
+
+    @classmethod
+    def _extract_file_url(cls, text: str) -> Optional[str]:
+        """Extract file URL from text, handling caption patterns."""
+        # First remove any captions to get clean text for URL extraction
+        clean_text = cls.remove_caption(text)
+
+        # Now extract the URL from clean text
+        match = cls.FILE_PATTERN.search(clean_text)
+        if match:
+            return match.group(1)
+
+        return None
+
+    @classmethod
+    def match_notion(cls, block: Block) -> bool:
+        # Notion file block covers files
+        return block.type == BlockType.FILE and block.file
+
+    @classmethod
+    async def markdown_to_notion(cls, text: str) -> BlockCreateResult:
+        """Convert markdown file link to Notion FileBlock."""
+        # Use our helper method to extract the URL
+        url = cls._extract_file_url(text.strip())
+        if not url:
+            return None
+
+        # Use mixin to extract caption (if present anywhere in text)
+        caption_text = cls.extract_caption(text.strip())
+        caption_rich_text = cls.build_caption_rich_text(caption_text or "")
+
+        # Build FileBlock using FileType enum
+        file_block = FileBlock(
+            type=FileType.EXTERNAL,
+            external=ExternalFile(url=url),
+            caption=caption_rich_text,
+        )
+
+        return CreateFileBlock(file=file_block)
+
+    @classmethod
+    async def notion_to_markdown(cls, block: Block) -> Optional[str]:
+        if block.type != BlockType.FILE or not block.file:
+            return None
+
+        fb: FileBlock = block.file
+
+        # Determine URL (only external and file types are valid for Markdown)
+        if fb.type == FileType.EXTERNAL and fb.external:
+            url = fb.external.url
+        elif fb.type == FileType.FILE and fb.file:
+            url = fb.file.url
+        elif fb.type == FileType.FILE_UPLOAD:
+            # Uploaded file has no stable URL for Markdown
+            return None
+        else:
+            return None
+
+        result = f"[file]({url})"
+
+        # Add caption if present
+        caption_markdown = await cls.format_caption_for_markdown(fb.caption or [])
+        if caption_markdown:
+            result += caption_markdown
+
+        return result
+
+    @classmethod
+    def get_system_prompt_information(cls) -> Optional[BlockElementMarkdownInformation]:
+        """Get system prompt information for file blocks."""
+        return BlockElementMarkdownInformation(
+            block_type=cls.__name__,
+            description="File blocks embed downloadable files from external URLs with optional captions",
+            syntax_examples=[
+                "[file](https://example.com/document.pdf)",
+                "[file](https://example.com/document.pdf)(caption:Annual Report)",
+                "(caption:Q1 Data)[file](https://example.com/spreadsheet.xlsx)",
+                "[file](https://example.com/manual.docx)(caption:**User** manual)",
+            ],
+            usage_guidelines="Use for linking to downloadable files like PDFs, documents, spreadsheets. Supports various file formats. Caption supports rich text formatting and should describe the file content or purpose.",
+        )

notionary/blocks/file/file_element_markdown_node.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from typing import Optional
+
+from pydantic import BaseModel
+
+from notionary.markdown.markdown_node import MarkdownNode
+from notionary.blocks.mixins.captions import CaptionMarkdownNodeMixin
+
+
+class FileMarkdownNodeParams(BaseModel):
+    url: str
+    caption: Optional[str] = None
+
+
+class FileMarkdownNode(MarkdownNode, CaptionMarkdownNodeMixin):
+    """
+    Programmatic interface for creating Notion-style Markdown file embeds.
+    """
+
+    def __init__(self, url: str, caption: Optional[str] = None):
+        self.url = url
+        self.caption = caption or ""
+
+    @classmethod
+    def from_params(cls, params: FileMarkdownNodeParams) -> FileMarkdownNode:
+        return cls(url=params.url, caption=params.caption)
+
+    def to_markdown(self) -> str:
+        """Return the Markdown representation.
+
+        Examples:
+        - [file](https://example.com/document.pdf)
+        - [file](https://example.com/document.pdf)(caption:User manual)
+        """
+        base_markdown = f"[file]({self.url})"
+        return self.append_caption_to_markdown(base_markdown, self.caption)

notionary/blocks/file/file_element_models.py

@@ -0,0 +1,39 @@
+from enum import Enum
+from typing import Literal, Optional
+
+from pydantic import BaseModel, Field
+
+from notionary.blocks.rich_text.rich_text_models import RichTextObject
+
+
+class FileType(str, Enum):
+    EXTERNAL = "external"
+    FILE = "file"
+    FILE_UPLOAD = "file_upload"
+
+
+class ExternalFile(BaseModel):
+    url: str
+
+
+class NotionHostedFile(BaseModel):
+    url: str
+    expiry_time: str
+
+
+class FileUploadFile(BaseModel):
+    id: str
+
+
+class FileBlock(BaseModel):
+    caption: list[RichTextObject] = Field(default_factory=list)
+    type: FileType
+    external: Optional[ExternalFile] = None
+    file: Optional[NotionHostedFile] = None
+    file_upload: Optional[FileUploadFile] = None
+    name: Optional[str] = None
+
+
+class CreateFileBlock(BaseModel):
+    type: Literal["file"] = "file"
+    file: FileBlock

notionary/blocks/guards.py

@@ -0,0 +1,22 @@
+from typing import Protocol
+
+from notionary.blocks.models import BlockCreateRequest
+from notionary.blocks.rich_text.rich_text_models import RichTextObject
+
+
+class HasRichText(Protocol):
+    """Protocol for objects that have a rich_text attribute."""
+
+    rich_text: list[RichTextObject]
+
+
+class HasChildren(Protocol):
+    """Protocol for objects that have children blocks."""
+
+    children: list[BlockCreateRequest]
+
+
+class HasRichTextAndChildren(HasRichText, HasChildren, Protocol):
+    """Protocol for objects that have both rich_text and children."""
+
+    pass

notionary/blocks/heading/__init__.py

@@ -1,7 +1,21 @@
-from .heading_element import HeadingElement
-from .heading_markdown_node import HeadingMarkdownNode
+from notionary.blocks.heading.heading_element import HeadingElement
+from notionary.blocks.heading.heading_markdown_node import (
+    HeadingMarkdownBlockParams,
+    HeadingMarkdownNode,
+)
+from notionary.blocks.heading.heading_models import (
+    CreateHeading1Block,
+    CreateHeading2Block,
+    CreateHeading3Block,
+    HeadingBlock,
+)
 
 __all__ = [
     "HeadingElement",
+    "HeadingBlock",
+    "CreateHeading1Block",
+    "CreateHeading2Block",
+    "CreateHeading3Block",
     "HeadingMarkdownNode",
+    "HeadingMarkdownBlockParams",
 ]

notionary/blocks/heading/heading_element.py

@@ -1,98 +1,112 @@
-import re
-from typing import Dict, Any, Optional
+from __future__ import annotations
 
-from notionary.blocks import NotionBlockElement
-from notionary.blocks import (
-    ElementPromptContent,
-    ElementPromptBuilder,
-    NotionBlockResult,
+import re
+from typing import Optional, cast
+
+from notionary.blocks.base_block_element import BaseBlockElement
+from notionary.blocks.heading.heading_models import (
+    CreateHeading1Block,
+    CreateHeading2Block,
+    CreateHeading3Block,
+    HeadingBlock,
 )
-from notionary.blocks.shared.text_inline_formatter import TextInlineFormatter
+from notionary.blocks.syntax_prompt_builder import BlockElementMarkdownInformation
+from notionary.blocks.models import Block, BlockCreateResult, BlockType
+from notionary.blocks.rich_text.text_inline_formatter import TextInlineFormatter
+from notionary.blocks.types import BlockColor
 
 
-class HeadingElement(NotionBlockElement):
+class HeadingElement(BaseBlockElement):
     """Handles conversion between Markdown headings and Notion heading blocks."""
 
-    # Pattern: #, ## oder ###, dann mind. 1 Leerzeichen/Tab, dann mind. 1 sichtbares Zeichen (kein Whitespace-only)
     PATTERN = re.compile(r"^(#{1,3})[ \t]+(.+)$")
 
     @classmethod
-    def match_markdown(cls, text: str) -> bool:
-        """Check if text is a markdown heading with non-empty content."""
-        match = cls.PATTERN.match(text)
-        if not match:
-            return False
-        content = match.group(2)
-        return bool(content.strip())  # Reject headings with only whitespace
-
-    @classmethod
-    def match_notion(cls, block: Dict[str, Any]) -> bool:
-        """Check if block is a Notion heading."""
-        block_type: str = block.get("type", "")
-        return block_type.startswith("heading_") and block_type[-1] in "123"
+    def match_notion(cls, block: Block) -> bool:
+        return (
+            block.type
+            in (
+                BlockType.HEADING_1,
+                BlockType.HEADING_2,
+                BlockType.HEADING_3,
+            )
+            and getattr(block, block.type.value) is not None
+        )
 
     @classmethod
-    def markdown_to_notion(cls, text: str) -> NotionBlockResult:
-        """Convert markdown heading to Notion heading block with preceding empty paragraph."""
-        match = cls.PATTERN.match(text)
+    async def markdown_to_notion(cls, text: str) -> BlockCreateResult:
+        """Convert markdown headings (#, ##, ###) to Notion HeadingBlock."""
+        match = cls.PATTERN.match(text.strip())
         if not match:
             return None
 
         level = len(match.group(1))
-        if not 1 <= level <= 3:
+        if level < 1 or level > 3:
             return None
 
-        content = match.group(2).lstrip()  # Entferne führende Leerzeichen im Content
-        if not content.strip():
-            return None  # Leerer Inhalt nach Entfernen der Whitespaces
+        content = match.group(2).strip()
+        if not content:
+            return None
 
-        header_block = {
-            "type": f"heading_{level}",
-            f"heading_{level}": {
-                "rich_text": TextInlineFormatter.parse_inline_formatting(content)
-            },
-        }
-        return [header_block]
+        rich_text = await TextInlineFormatter.parse_inline_formatting(content)
+        heading_content = HeadingBlock(
+            rich_text=rich_text, color=BlockColor.DEFAULT, is_toggleable=False
+        )
 
-    @classmethod
-    def notion_to_markdown(cls, block: Dict[str, Any]) -> Optional[str]:
-        """Convert Notion heading block to markdown heading."""
-        block_type = block.get("type", "")
+        if level == 1:
+            return CreateHeading1Block(heading_1=heading_content)
+        elif level == 2:
+            return CreateHeading2Block(heading_2=heading_content)
+        else:
+            return CreateHeading3Block(heading_3=heading_content)
 
-        if not block_type.startswith("heading_"):
+    @classmethod
+    async def notion_to_markdown(cls, block: Block) -> Optional[str]:
+        # Only handle heading blocks via BlockType enum
+        if block.type not in (
+            BlockType.HEADING_1,
+            BlockType.HEADING_2,
+            BlockType.HEADING_3,
+        ):
             return None
 
-        try:
-            level = int(block_type[-1])
-            if not 1 <= level <= 3:
-                return None
-        except ValueError:
+        # Determine heading level from enum
+        if block.type == BlockType.HEADING_1:
+            level = 1
+        elif block.type == BlockType.HEADING_2:
+            level = 2
+        else:
+            level = 3
+
+        heading_obj = getattr(block, block.type.value)
+        if not heading_obj:
             return None
 
-        heading_data = block.get(block_type, {})
-        rich_text = heading_data.get("rich_text", [])
+        heading_data = cast(HeadingBlock, heading_obj)
+        if not heading_data.rich_text:
+            return None
 
-        text = TextInlineFormatter.extract_text_with_formatting(rich_text)
-        prefix = "#" * level
-        return f"{prefix} {text}" if text else None
+        text = await TextInlineFormatter.extract_text_with_formatting(
+            heading_data.rich_text
+        )
+        if not text:
+            return None
 
-    @classmethod
-    def is_multiline(cls) -> bool:
-        return False
+        # Use hash-style for all heading levels
+        return f"{('#' * level)} {text}"
 
     @classmethod
-    def get_llm_prompt_content(cls) -> ElementPromptContent:
-        return (
-            ElementPromptBuilder()
-            .with_description(
-                "Use Markdown headings (#, ##, ###) to structure content hierarchically."
-            )
-            .with_usage_guidelines(
-                "Use to group content into sections and define a visual hierarchy."
-            )
-            .with_avoidance_guidelines(
-                "Only H1-H3 syntax is supported. H4 and deeper heading levels are not available."
-            )
-            .with_standard_markdown()
-            .build()
+    def get_system_prompt_information(cls) -> Optional[BlockElementMarkdownInformation]:
+        """Get system prompt information for heading blocks."""
+        return BlockElementMarkdownInformation(
+            block_type=cls.__name__,
+            description="Heading blocks create hierarchical document structure with different levels",
+            syntax_examples=[
+                "# Heading Level 1",
+                "## Heading Level 2",
+                "### Heading Level 3",
+                "# Heading with **bold text**",
+                "## Heading with *italic text*",
+            ],
+            usage_guidelines="Use # for main titles, ## for sections, ### for subsections. Supports inline formatting. Only levels 1-3 are supported in Notion.",
         )

notionary/blocks/heading/heading_markdown_node.py

@@ -1,7 +1,8 @@
 from __future__ import annotations
 
 from pydantic import BaseModel
-from notionary.blocks.markdown_node import MarkdownNode
+
+from notionary.markdown.markdown_node import MarkdownNode
 
 
 class HeadingMarkdownBlockParams(BaseModel):

notionary/blocks/heading/heading_models.py

@@ -0,0 +1,29 @@
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+from notionary.blocks.models import Block
+from notionary.blocks.rich_text.rich_text_models import RichTextObject
+from notionary.blocks.types import BlockColor
+
+
+class HeadingBlock(BaseModel):
+    rich_text: list[RichTextObject]
+    color: BlockColor = BlockColor.DEFAULT
+    is_toggleable: bool = False
+    children: list[Block] = Field(default_factory=list)
+
+
+class CreateHeading1Block(BaseModel):
+    type: Literal["heading_1"] = "heading_1"
+    heading_1: HeadingBlock
+
+
+class CreateHeading2Block(BaseModel):
+    type: Literal["heading_2"] = "heading_2"
+    heading_2: HeadingBlock
+
+
+class CreateHeading3Block(BaseModel):
+    type: Literal["heading_3"] = "heading_3"
+    heading_3: HeadingBlock

notionary/blocks/image_block/__init__.py

@@ -0,0 +1,13 @@
+from notionary.blocks.image_block.image_element import ImageElement
+from notionary.blocks.image_block.image_markdown_node import (
+    ImageMarkdownBlockParams,
+    ImageMarkdownNode,
+)
+from notionary.blocks.image_block.image_models import CreateImageBlock
+
+__all__ = [
+    "ImageElement",
+    "CreateImageBlock",
+    "ImageMarkdownNode",
+    "ImageMarkdownBlockParams",
+]

notionary/blocks/image_block/image_element.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+import re
+from typing import Optional
+
+from notionary.blocks.base_block_element import BaseBlockElement
+from notionary.blocks.file.file_element_models import ExternalFile, FileType
+from notionary.blocks.image_block.image_models import CreateImageBlock, FileBlock
+from notionary.blocks.mixins.captions import CaptionMixin
+from notionary.blocks.syntax_prompt_builder import BlockElementMarkdownInformation
+from notionary.blocks.models import Block, BlockCreateResult, BlockType
+
+
+class ImageElement(BaseBlockElement, CaptionMixin):
+    """
+    Handles conversion between Markdown images and Notion image blocks.
+
+    Markdown image syntax:
+    - [image](https://example.com/image.jpg) - URL only
+    - [image](https://example.com/image.jpg)(caption:This is a caption) - URL with caption
+    - (caption:Profile picture)[image](https://example.com/avatar.jpg) - caption before URL
+    """
+
+    # Flexible pattern that can handle caption in any position
+    IMAGE_PATTERN = re.compile(r"\[image\]\((https?://[^\s\"]+)\)")
+
+    @classmethod
+    def match_notion(cls, block: Block) -> bool:
+        return block.type == BlockType.IMAGE and block.image
+
+    @classmethod
+    async def markdown_to_notion(cls, text: str) -> BlockCreateResult:
+        """Convert markdown image syntax to Notion ImageBlock."""
+        clean_text = cls.remove_caption(text.strip())
+
+        # Use our own regex to find the image URL
+        image_match = cls.IMAGE_PATTERN.search(clean_text)
+        if not image_match:
+            return None
+
+        url = image_match.group(1)
+
+        caption_text = cls.extract_caption(text.strip())
+        caption_rich_text = cls.build_caption_rich_text(caption_text or "")
+
+        # Build ImageBlock
+        image_block = FileBlock(
+            type="external", external=ExternalFile(url=url), caption=caption_rich_text
+        )
+
+        return CreateImageBlock(image=image_block)
+
+    @classmethod
+    async def notion_to_markdown(cls, block: Block) -> Optional[str]:
+        if block.type != BlockType.IMAGE or not block.image:
+            return None
+
+        fo = block.image
+
+        if fo.type == FileType.EXTERNAL and fo.external:
+            url = fo.external.url
+        elif fo.type == FileType.FILE and fo.file:
+            url = fo.file.url
+        else:
+            return None
+
+        result = f"[image]({url})"
+
+        # Add caption if present
+        caption_markdown = await cls.format_caption_for_markdown(fo.caption or [])
+        if caption_markdown:
+            result += caption_markdown
+
+        return result
+
+    @classmethod
+    def get_system_prompt_information(cls) -> Optional[BlockElementMarkdownInformation]:
+        """Get system prompt information for image blocks."""
+        return BlockElementMarkdownInformation(
+            block_type=cls.__name__,
+            description="Image blocks display images from external URLs with optional captions",
+            syntax_examples=[
+                "[image](https://example.com/photo.jpg)",
+                "[image](https://example.com/diagram.png)(caption:Architecture Diagram)",
+                "(caption:Sales Chart)[image](https://example.com/chart.svg)",
+                "[image](https://example.com/screenshot.png)(caption:Dashboard **overview**)",
+            ],
+            usage_guidelines="Use for displaying images from external URLs. Supports common image formats (jpg, png, gif, svg, webp). Caption supports rich text formatting and describes the image content.",
+        )

notionary/blocks/{image → image_block}/image_markdown_node.py

@@ -1,8 +1,11 @@
 from __future__ import annotations
 
 from typing import Optional
+
 from pydantic import BaseModel
-from notionary.blocks.markdown_node import MarkdownNode
+
+from notionary.markdown.markdown_node import MarkdownNode
+from notionary.blocks.mixins.captions import CaptionMarkdownNodeMixin
 
 
 class ImageMarkdownBlockParams(BaseModel):
@@ -10,10 +13,9 @@ class ImageMarkdownBlockParams(BaseModel):
     caption: Optional[str] = None
 
 
-class ImageMarkdownNode(MarkdownNode):
+class ImageMarkdownNode(MarkdownNode, CaptionMarkdownNodeMixin):
     """
     Programmatic interface for creating Notion-style image blocks.
-    Example: [image](https://example.com/image.jpg "Optional caption")
     """
 
     def __init__(
@@ -28,6 +30,11 @@ class ImageMarkdownNode(MarkdownNode):
         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})"
+        """Return the Markdown representation.
+
+        Examples:
+        - [image](https://example.com/screenshot.png)
+        - [image](https://example.com/screenshot.png)(caption:Dashboard overview)
+        """
+        base_markdown = f"[image]({self.url})"
+        return self.append_caption_to_markdown(base_markdown, self.caption)

notionary/blocks/image_block/image_models.py

@@ -0,0 +1,10 @@
+from typing import Literal
+
+from pydantic import BaseModel
+
+from notionary.blocks.file.file_element_models import FileBlock
+
+
+class CreateImageBlock(BaseModel):
+    type: Literal["image"] = "image"
+    image: FileBlock

notionary/blocks/mixins/captions/__init__.py

@@ -0,0 +1,4 @@
+from .caption_mixin import CaptionMixin
+from .caption_markdown_node_mixin import CaptionMarkdownNodeMixin
+
+__all__ = ["CaptionMixin", "CaptionMarkdownNodeMixin"]

notionary/blocks/mixins/captions/caption_markdown_node_mixin.py

@@ -0,0 +1,31 @@
+from typing import Optional
+
+
+class CaptionMarkdownNodeMixin:
+    """Mixin to add caption functionality to MarkdownNode classes."""
+
+    @classmethod
+    def append_caption_to_markdown(
+        cls, base_markdown: str, caption: Optional[str]
+    ) -> str:
+        """
+        Append caption to existing markdown if caption is present.
+        Returns: base_markdown + "(caption:...)" or just base_markdown
+        """
+        if not caption:
+            return base_markdown
+        return f"{base_markdown}(caption:{caption})"
+
+    @classmethod
+    def format_caption_for_markdown(cls, caption: Optional[str]) -> str:
+        """
+        Format caption text for markdown output.
+        Returns: "(caption:...)" or empty string
+        """
+        if not caption:
+            return ""
+        return f"(caption:{caption})"
+
+    def has_caption(self) -> bool:
+        """Check if this node has a caption."""
+        return hasattr(self, "caption") and bool(getattr(self, "caption", None))