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

notionary/blocks/document/document_element.py

@@ -0,0 +1,102 @@
+import re
+from typing import Dict, Any, Optional, List
+
+from notionary.blocks import NotionBlockElement, NotionBlockResult
+from notionary.blocks import ElementPromptContent, ElementPromptBuilder
+
+class DocumentElement(NotionBlockElement):
+    """
+    Handles conversion between Markdown document embeds and Notion file blocks.
+
+    Markdown document syntax:
+    - [document](https://example.com/document.pdf "Caption")
+    - [document](https://example.com/document.pdf)
+    """
+    # Nur noch die neue Syntax!
+    PATTERN = re.compile(
+        r'^\[document\]\('
+        r'(https?://[^\s")]+)'           # URL
+        r'(?:\s+"([^"]*)")?'             # Optional caption
+        r'\)$'
+    )
+
+    @classmethod
+    def match_markdown(cls, text: str) -> bool:
+        text = text.strip()
+        return text.startswith("[document]") and bool(cls.PATTERN.match(text))
+
+    @classmethod
+    def match_notion(cls, block: Dict[str, Any]) -> bool:
+        return block.get("type") == "file"
+
+    @classmethod
+    def markdown_to_notion(cls, text: str) -> Optional[List[Dict[str, Any]]]:
+        match = cls.PATTERN.match(text.strip())
+        if not match:
+            return None
+        url = match.group(1)
+        caption = match.group(2) or ""
+        file_block = {
+            "type": "file",
+            "file": {
+                "type": "external",
+                "external": {"url": url},
+                "caption": [{"type": "text", "text": {"content": caption}}] if caption else [],
+            }
+        }
+        # Für Konsistenz mit anderen Blöcken geben wir ein Array zurück
+        empty_paragraph = {"type": "paragraph", "paragraph": {"rich_text": []}}
+        return [file_block, empty_paragraph]
+
+    @classmethod
+    def notion_to_markdown(cls, block: Dict[str, Any]) -> Optional[str]:
+        if block.get("type") != "file":
+            return None
+        file_data = block.get("file", {})
+        url = ""
+        if file_data.get("type") == "external":
+            url = file_data.get("external", {}).get("url", "")
+        elif file_data.get("type") == "file":
+            url = file_data.get("file", {}).get("url", "")
+        if not url:
+            return None
+        caption_list = file_data.get("caption", [])
+        caption = cls._extract_text_content(caption_list)
+        if caption:
+            return f'[document]({url} "{caption}")'
+        return f'[document]({url})'
+
+    @classmethod
+    def _extract_text_content(cls, rich_text: List[Dict[str, Any]]) -> str:
+        return "".join(
+            t.get("text", {}).get("content", "")
+            for t in rich_text
+            if t.get("type") == "text"
+        ) or "".join(t.get("plain_text", "") for t in rich_text if "plain_text" in t)
+
+    @classmethod
+    def is_multiline(cls) -> bool:
+        return False
+
+    @classmethod
+    def get_llm_prompt_content(cls) -> ElementPromptContent:
+        return (
+            ElementPromptBuilder()
+            .with_description(
+                "Embeds document files from external sources like PDFs, Word docs, Excel files, or cloud storage services."
+            )
+            .with_usage_guidelines(
+                "Use document embeds for sharing contracts, reports, manuals, or any important files."
+            )
+            .with_syntax('[document](https://example.com/document.pdf "Caption")')
+            .with_examples(
+                [
+                    '[document](https://drive.google.com/file/d/1a2b3c4d5e/view "Project Proposal")',
+                    '[document](https://company.sharepoint.com/reports/q4-2024.xlsx "Q4 Financial Report")',
+                    '[document](https://cdn.company.com/docs/manual-v2.1.pdf "User Manual")',
+                    '[document](https://docs.google.com/document/d/1x2y3z4/edit "Meeting Minutes")',
+                    '[document](https://example.com/contract.pdf)',
+                ]
+            )
+            .build()
+        )

notionary/blocks/document/document_markdown_node.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from typing import Optional
+from pydantic import BaseModel
+from notionary.blocks.markdown_node import MarkdownNode
+
+class DocumentMarkdownNodeParams(BaseModel):
+    url: str
+    caption: Optional[str] = None
+
+class DocumentMarkdownNode(MarkdownNode):
+    """
+    Programmatic interface for creating Notion-style Markdown document/file embeds.
+    Example: [document](https://example.com/file.pdf "My Caption")
+    """
+
+    def __init__(self, url: str, caption: Optional[str] = None):
+        self.url = url
+        self.caption = caption or ""
+
+    @classmethod
+    def from_params(cls, params: DocumentMarkdownNodeParams) -> DocumentMarkdownNode:
+        return cls(url=params.url, caption=params.caption)
+
+    def to_markdown(self) -> str:
+        """
+        Convert to markdown as [document](url "caption") or [document](url) if caption is empty.
+        """
+        if self.caption:
+            return f'[document]({self.url} "{self.caption}")'
+        return f'[document]({self.url})'

notionary/blocks/embed/__init__.py

@@ -0,0 +1,7 @@
+from .embed_element import EmbedElement
+from .embed_markdown_node import EmbedMarkdownNode
+
+__all__ = [
+    "EmbedElement",
+    "EmbedMarkdownNode",
+]

notionary/blocks/{embed_element.py → embed/embed_element.py}

@@ -1,31 +1,44 @@
 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 EmbedElement(NotionBlockElement):
     """
     Handles conversion between Markdown embeds and Notion embed blocks.
 
-    Markdown embed syntax (custom format):
-    - <embed:Caption>(https://example.com) - Basic embed with caption
-    - <embed>(https://example.com) - Embed without caption
+    Markdown embed syntax:
+    - [embed](https://example.com) - Simple embed with URL only
+    - [embed](https://example.com "Caption") - Embed with URL and caption
+
+    Where:
+    - URL is the required embed URL
+    - Caption is an optional descriptive text (enclosed in quotes)
 
     Supports various URL types including websites, PDFs, Google Maps, Google Drive,
     Twitter/X posts, and other sources that Notion can embed.
     """
 
+    # Regex pattern for embed syntax with optional caption
     PATTERN = re.compile(
-        r"^<embed(?:\:(.*?))?>(?:\s*)" + r'\((https?://[^\s"]+)' + r"\)$"
+        r"^\[embed\]\("  # [embed]( 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 embed."""
-        text = text.strip()
-        return text.startswith("<embed") and bool(EmbedElement.PATTERN.match(text))
+        return text.strip().startswith("[embed]") and bool(
+            EmbedElement.PATTERN.match(text.strip())
+        )
 
     @classmethod
     def match_notion(cls, block: Dict[str, Any]) -> bool:
@@ -33,31 +46,33 @@ class EmbedElement(NotionBlockElement):
         return block.get("type") == "embed"
 
     @classmethod
-    def markdown_to_notion(cls, text: str) -> Optional[Dict[str, Any]]:
+    def markdown_to_notion(cls, text: str) -> NotionBlockResult:
         """Convert markdown embed to Notion embed block."""
         embed_match = EmbedElement.PATTERN.match(text.strip())
         if not embed_match:
             return None
 
-        caption = embed_match.group(1) or ""
-        url = embed_match.group(2)
+        url = embed_match.group(1)
+        caption = embed_match.group(2)
 
         if not url:
             return None
 
-        # Prepare the embed block
-        embed_block = {
-            "type": "embed",
-            "embed": {"url": url},
-        }
+        embed_data = {"url": url}
 
         # Add caption if provided
         if caption:
-            embed_block["embed"]["caption"] = [
-                {"type": "text", "text": {"content": caption}}
-            ]
+            embed_data["caption"] = [{"type": "text", "text": {"content": caption}}]
+        else:
+            embed_data["caption"] = []
 
-        return embed_block
+        # Prepare the embed block
+        embed_block = {"type": "embed", "embed": embed_data}
+
+        # Add empty paragraph after embed
+        empty_paragraph = {"type": "paragraph", "paragraph": {"rich_text": []}}
+
+        return [embed_block, empty_paragraph]
 
     @classmethod
     def notion_to_markdown(cls, block: Dict[str, Any]) -> Optional[str]:
@@ -71,16 +86,19 @@ class EmbedElement(NotionBlockElement):
         if not url:
             return None
 
-        # Extract caption if available
-        caption = ""
         caption_rich_text = embed_data.get("caption", [])
-        if caption_rich_text:
-            caption = EmbedElement._extract_text_content(caption_rich_text)
+
+        if not caption_rich_text:
+            # Simple embed with URL only
+            return f"[embed]({url})"
+
+        # Extract caption text
+        caption = EmbedElement._extract_text_content(caption_rich_text)
 
         if caption:
-            return f"<embed:{caption}>({url})"
+            return f'[embed]({url} "{caption}")'
 
-        return f"<embed>({url})"
+        return f"[embed]({url})"
 
     @classmethod
     def is_multiline(cls) -> bool:
@@ -112,14 +130,14 @@ class EmbedElement(NotionBlockElement):
                 "Use embeds when you want to include external content that isn't just a video or image. "
                 "Embeds are great for interactive content, reference materials, or live data sources."
             )
-            .with_syntax("<embed:Caption>(https://example.com)")
+            .with_syntax('[embed](https://example.com "Optional caption")')
             .with_examples(
                 [
-                    "<embed:Course materials>(https://drive.google.com/file/d/123456/view)",
-                    "<embed:Our office location>(https://www.google.com/maps?q=San+Francisco)",
-                    "<embed:Latest announcement>(https://twitter.com/NotionHQ/status/1234567890)",
-                    "<embed:Project documentation>(https://github.com/username/repo)",
-                    "<embed>(https://example.com/important-reference.pdf)",
+                    "[embed](https://drive.google.com/file/d/123456/view)",
+                    '[embed](https://www.google.com/maps?q=San+Francisco "Our office location")',
+                    '[embed](https://twitter.com/NotionHQ/status/1234567890 "Latest announcement")',
+                    '[embed](https://github.com/username/repo "Project documentation")',
+                    '[embed](https://example.com/important-reference.pdf "Course materials")',
                 ]
             )
             .build()

notionary/blocks/embed/embed_markdown_node.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from typing import Optional
+from pydantic import BaseModel
+from notionary.blocks.markdown_node import MarkdownNode
+
+
+class EmbedMarkdownBlockParams(BaseModel):
+    url: str
+    caption: Optional[str] = None
+
+
+class EmbedMarkdownNode(MarkdownNode):
+    """
+    Programmatic interface for creating Notion-style Markdown embed blocks.
+    Example: [embed](https://example.com "Optional caption")
+    """
+
+    def __init__(self, url: str, caption: Optional[str] = None):
+        self.url = url
+        self.caption = caption
+
+    @classmethod
+    def from_params(cls, params: EmbedMarkdownBlockParams) -> EmbedMarkdownNode:
+        return cls(url=params.url, caption=params.caption)
+
+    def to_markdown(self) -> str:
+        if self.caption:
+            return f'[embed]({self.url} "{self.caption}")'
+        return f"[embed]({self.url})"

notionary/blocks/heading/__init__.py

@@ -0,0 +1,7 @@
+from .heading_element import HeadingElement
+from .heading_markdown_node import HeadingMarkdownNode
+
+__all__ = [
+    "HeadingElement",
+    "HeadingMarkdownNode",
+]

notionary/blocks/{heading_element.py → heading/heading_element.py}

@@ -2,19 +2,28 @@ import re
 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 HeadingElement(NotionBlockElement):
     """Handles conversion between Markdown headings and Notion heading blocks."""
 
-    PATTERN = re.compile(r"^(#{1,3})\s(.+)$")
+    # 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."""
-        return bool(HeadingElement.PATTERN.match(text))
+        """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:
@@ -23,24 +32,27 @@ class HeadingElement(NotionBlockElement):
         return block_type.startswith("heading_") and block_type[-1] in "123"
 
     @classmethod
-    def markdown_to_notion(cls, text: str) -> Optional[Dict[str, Any]]:
-        """Convert markdown heading to Notion heading block."""
-        header_match = HeadingElement.PATTERN.match(text)
-        if not header_match:
+    def markdown_to_notion(cls, text: str) -> NotionBlockResult:
+        """Convert markdown heading to Notion heading block with preceding empty paragraph."""
+        match = cls.PATTERN.match(text)
+        if not match:
             return None
 
-        level = len(header_match.group(1))
+        level = len(match.group(1))
         if not 1 <= level <= 3:
             return None
 
-        content = header_match.group(2)
+        content = match.group(2).lstrip()  # Entferne führende Leerzeichen im Content
+        if not content.strip():
+            return None  # Leerer Inhalt nach Entfernen der Whitespaces
 
-        return {
+        header_block = {
             "type": f"heading_{level}",
             f"heading_{level}": {
                 "rich_text": TextInlineFormatter.parse_inline_formatting(content)
             },
         }
+        return [header_block]
 
     @classmethod
     def notion_to_markdown(cls, block: Dict[str, Any]) -> Optional[str]:
@@ -52,7 +64,6 @@ class HeadingElement(NotionBlockElement):
 
         try:
             level = int(block_type[-1])
-            # Only allow levels 1-3
             if not 1 <= level <= 3:
                 return None
         except ValueError:
@@ -63,7 +74,7 @@ class HeadingElement(NotionBlockElement):
 
         text = TextInlineFormatter.extract_text_with_formatting(rich_text)
         prefix = "#" * level
-        return f"{prefix} {text or ''}"
+        return f"{prefix} {text}" if text else None
 
     @classmethod
     def is_multiline(cls) -> bool:
@@ -71,9 +82,6 @@ class HeadingElement(NotionBlockElement):
 
     @classmethod
     def get_llm_prompt_content(cls) -> ElementPromptContent:
-        """
-        Returns structured LLM prompt metadata for the heading element.
-        """
         return (
             ElementPromptBuilder()
             .with_description(

notionary/blocks/heading/heading_markdown_node.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+from pydantic import BaseModel
+from notionary.blocks.markdown_node import MarkdownNode
+
+
+class HeadingMarkdownBlockParams(BaseModel):
+    text: str
+    level: int = 1
+
+
+class HeadingMarkdownNode(MarkdownNode):
+    """
+    Programmatic interface for creating Markdown headings (H1-H3).
+    Example: # Heading 1, ## Heading 2, ### Heading 3
+    """
+
+    def __init__(self, text: str, level: int = 1):
+        if not (1 <= level <= 3):
+            raise ValueError("Only heading levels 1-3 are supported (H1, H2, H3)")
+        self.text = text
+        self.level = level
+
+    @classmethod
+    def from_params(cls, params: HeadingMarkdownBlockParams) -> HeadingMarkdownNode:
+        return cls(text=params.text, level=params.level)
+
+    def to_markdown(self) -> str:
+        return f"{'#' * self.level} {self.text}"

notionary/blocks/image/__init__.py

@@ -0,0 +1,7 @@
+from .image_element import ImageElement
+from .image_markdown_node import ImageMarkdownNode
+
+__all__ = [
+    "ImageElement",
+    "ImageMarkdownNode",
+]

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()