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

notionary/__init__.py

@@ -2,7 +2,8 @@ from .database import NotionDatabase, DatabaseFilterBuilder
 from .page.notion_page import NotionPage
 from .workspace import NotionWorkspace
 from .user import NotionUser, NotionUserManager, NotionBotUser
-from .file_upload import NotionFileUpload, NotionFileUploadClient
+from .file_upload import NotionFileUpload
+from .blocks.markdown_builder import MarkdownBuilder
 
 __all__ = [
     "NotionDatabase",
@@ -13,5 +14,5 @@ __all__ = [
     "NotionUserManager",
     "NotionBotUser",
     "NotionFileUpload",
-    "NotionFileUploadClient",
+    "MarkdownBuilder",
 ]

notionary/blocks/__init__.py

@@ -2,62 +2,91 @@
 from .prompts.element_prompt_content import ElementPromptContent
 from .prompts.element_prompt_builder import ElementPromptBuilder
 
-from .notion_block_element import NotionBlockElement
+from .shared.notion_block_element import (
+    NotionBlockElement,
+    NotionBlockResult,
+    NotionBlock,
+)
 
+from .audio import AudioElement, AudioMarkdownNode
+from .bulleted_list import BulletedListElement, BulletedListMarkdownNode
+from .callout import CalloutElement, CalloutMarkdownNode
+from .code import CodeElement, CodeMarkdownNode
+from .column.column_element import ColumnElement
+from .divider import DividerElement, DividerMarkdownNode
+from .embed import EmbedElement, EmbedMarkdownNode
+from .heading import HeadingElement, HeadingMarkdownNode
+from .image import ImageElement, ImageMarkdownNode
+from .numbered_list import NumberedListElement, NumberedListMarkdownNode
+from .paragraph import ParagraphElement, ParagraphMarkdownNode
+from .table import TableElement, TableMarkdownNode
+from .toggle import ToggleElement, ToggleMarkdownNode
+from .todo import TodoElement, TodoMarkdownNode
+from .video import VideoElement, VideoMarkdownNode
+from .toggleable_heading import ToggleableHeadingElement, ToggleableHeadingMarkdownNode
+from .bookmark import BookmarkElement, BookmarkMarkdownNode
+from .divider import DividerElement, DividerMarkdownNode
+from .heading import HeadingElement, HeadingMarkdownNode
+from .mention import MentionElement, MentionMarkdownNode
+from .quote import QuoteElement, QuoteMarkdownNode
+from .document import DocumentElement, DocumentMarkdownNode
+from .shared.text_inline_formatter import TextInlineFormatter
 
-from .audio_element import AudioElement
-from .bulleted_list_element import BulletedListElement
-from .callout_element import CalloutElement
-from .code_block_element import CodeBlockElement
-from .column_element import ColumnElement
-from .divider_element import DividerElement
-from .embed_element import EmbedElement
-from .heading_element import HeadingElement
-from .image_element import ImageElement
-from .numbered_list_element import NumberedListElement
-from .paragraph_element import ParagraphElement
-from .table_element import TableElement
-from .toggle_element import ToggleElement
-from .todo_element import TodoElement
-from .video_element import VideoElement
-from .toggleable_heading_element import ToggleableHeadingElement
-from .bookmark_element import BookmarkElement
-from .divider_element import DividerElement
-from .heading_element import HeadingElement
-from .mention_element import MentionElement
-from .qoute_element import QuoteElement
-from .document_element import DocumentElement
+from .markdown_node import MarkdownNode
 
 from .registry.block_registry import BlockRegistry
 from .registry.block_registry_builder import BlockRegistryBuilder
-from .notion_block_client import NotionBlockClient
 
+from .shared.block_client import NotionBlockClient
 
 __all__ = [
+    "MarkdownNode",
     "ElementPromptContent",
     "ElementPromptBuilder",
     "NotionBlockElement",
     "AudioElement",
+    "AudioMarkdownNode",
     "BulletedListElement",
+    "BulletedListMarkdownNode",
     "CalloutElement",
-    "CodeBlockElement",
+    "CalloutMarkdownNode",
+    "CodeElement",
+    "CodeMarkdownNode",
     "ColumnElement",
     "DividerElement",
+    "DividerMarkdownNode",
     "EmbedElement",
+    "EmbedMarkdownNode",
     "HeadingElement",
+    "HeadingMarkdownNode",
     "ImageElement",
+    "ImageMarkdownNode",
     "NumberedListElement",
+    "NumberedListMarkdownNode",
     "ParagraphElement",
+    "ParagraphMarkdownNode",
     "TableElement",
+    "TableMarkdownNode",
     "ToggleElement",
+    "ToggleMarkdownNode",
     "TodoElement",
+    "TodoMarkdownNode",
     "VideoElement",
+    "VideoMarkdownNode",
     "ToggleableHeadingElement",
+    "ToggleableHeadingMarkdownNode",
     "BookmarkElement",
+    "BookmarkMarkdownNode",
     "MentionElement",
+    "MentionMarkdownNode",
     "QuoteElement",
+    "QuoteMarkdownNode",
     "DocumentElement",
+    "DocumentMarkdownNode",
     "BlockRegistry",
     "BlockRegistryBuilder",
+    "TextInlineFormatter",
+    "NotionBlockResult",
+    "NotionBlock",
     "NotionBlockClient",
 ]

notionary/blocks/audio/__init__.py

@@ -0,0 +1,7 @@
+from .audio_element import AudioElement
+from .audio_markdown_node import AudioMarkdownNode
+
+__all__ = [
+    "AudioElement",
+    "AudioMarkdownNode",
+]

notionary/blocks/audio/audio_element.py

@@ -0,0 +1,152 @@
+import re
+from typing import Any, Optional, List
+
+from notionary.blocks import (
+    NotionBlockElement,
+    ElementPromptContent,
+    ElementPromptBuilder,
+    NotionBlockResult,
+)
+from notionary.blocks.shared.models import RichTextObject
+
+
+class AudioElement(NotionBlockElement):
+    """
+    Handles conversion between Markdown audio embeds and Notion audio blocks.
+
+    Markdown audio syntax:
+    - [audio](https://example.com/audio.mp3) - Simple audio embed
+    - [audio](https://example.com/audio.mp3 "Caption text") - Audio with caption
+
+    Where:
+    - URL is the required audio file URL
+    - Caption is optional descriptive text (enclosed in quotes)
+    """
+
+    # Regex patterns
+    URL_PATTERN = r"(https?://[^\s\"]+)"
+    CAPTION_PATTERN = r'(?:\s+"([^"]+)")?'
+
+    PATTERN = re.compile(r"^\[audio\]\(" + URL_PATTERN + CAPTION_PATTERN + r"\)$")
+
+    # Supported audio extensions
+    SUPPORTED_EXTENSIONS = {".mp3", ".wav", ".ogg", ".oga", ".m4a"}
+
+    @classmethod
+    def match_markdown(cls, text: str) -> bool:
+        m = cls.PATTERN.match(text.strip())
+        if not m:
+            return False
+        url = m.group(1)
+        return cls._is_likely_audio_url(url)
+
+    @classmethod
+    def match_notion(cls, block: dict[str, Any]) -> bool:
+        """Check if block is a Notion audio block."""
+        return block.get("type") == "audio"
+
+    @classmethod
+    def markdown_to_notion(cls, text: str) -> NotionBlockResult:
+        """Convert markdown audio embed to Notion audio block."""
+        audio_match = cls.PATTERN.match(text.strip())
+        if not audio_match:
+            return None
+
+        url = audio_match.group(1)
+        caption_text = audio_match.group(2)
+
+        if not url:
+            return None
+
+        # Validate URL if possible
+        if not cls._is_likely_audio_url(url):
+            # Still proceed - user might know better
+            pass
+
+        audio_data = {"type": "external", "external": {"url": url}}
+
+        # Add caption if provided
+        if caption_text:
+            caption_rich_text = RichTextObject.from_plain_text(caption_text)
+            audio_data["caption"] = [caption_rich_text.model_dump()]
+        else:
+            audio_data["caption"] = []
+
+        return {"type": "audio", "audio": audio_data}
+
+    @classmethod
+    def notion_to_markdown(cls, block: dict[str, Any]) -> Optional[str]:
+        """Convert Notion audio block to markdown audio embed."""
+        if block.get("type") != "audio":
+            return None
+
+        audio_data = block.get("audio", {})
+
+        # Get URL from external source
+        if audio_data.get("type") == "external":
+            url = audio_data.get("external", {}).get("url", "")
+        else:
+            # Handle file or file_upload types if needed
+            return None
+
+        if not url:
+            return None
+
+        # Extract caption
+        caption = audio_data.get("caption", [])
+        if caption:
+            caption_text = cls._extract_text_content(caption)
+            return f'[audio]({url} "{caption_text}")'
+
+        return f"[audio]({url})"
+
+    @classmethod
+    def is_multiline(cls) -> bool:
+        """Audio embeds are single-line elements."""
+        return False
+
+    @classmethod
+    def _is_likely_audio_url(cls, url: str) -> bool:
+        """Check if URL likely points to an audio file."""
+        return any(url.lower().endswith(ext) for ext in cls.SUPPORTED_EXTENSIONS)
+
+    @classmethod
+    def _extract_text_content(cls, rich_text: List[dict[str, Any]]) -> str:
+        """Extract plain text content from Notion rich_text elements."""
+        result = ""
+        for text_obj in rich_text:
+            if text_obj.get("type") == "text":
+                result += text_obj.get("text", {}).get("content", "")
+            elif "plain_text" in text_obj:
+                result += text_obj.get("plain_text", "")
+        return result
+
+    @classmethod
+    def get_llm_prompt_content(cls) -> ElementPromptContent:
+        """
+        Returns structured LLM prompt metadata for the audio element.
+        """
+        return (
+            ElementPromptBuilder()
+            .with_description(
+                "Embeds an audio file that can be played directly in the page."
+            )
+            .with_usage_guidelines(
+                "Use audio embeds when you want to include sound files, music, podcasts, "
+                "or voice recordings. Supports common audio formats like MP3, WAV, OGG, and M4A."
+            )
+            .with_syntax('![audio](https://example.com/audio.mp3 "Optional caption")')
+            .with_examples(
+                [
+                    "[audio](https://example.com/song.mp3)",
+                    '[audio](https://example.com/podcast.mp3 "Episode 1: Introduction")',
+                    '[audio](https://example.com/sound.wav "Sound effect for presentation")',
+                    '[audio](https://example.com/recording.m4a "Voice memo from meeting")',
+                ]
+            )
+            .with_avoidance_guidelines(
+                "Ensure the URL points to a valid audio file. "
+                "Some audio formats may not be supported by all browsers."
+            )
+            .build()
+        )

notionary/blocks/audio/audio_markdown_node.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+from typing import Optional
+from pydantic import BaseModel
+
+from notionary.blocks.markdown_node import MarkdownNode
+
+
+class AudioMarkdownBlockParams(BaseModel):
+    url: str
+    caption: Optional[str] = None
+
+
+class AudioMarkdownNode(MarkdownNode):
+    """
+    Programmatic interface for creating Notion-style audio blocks.
+    """
+
+    def __init__(self, url: str, caption: Optional[str] = None):
+        self.url = url
+        self.caption = caption
+
+    @classmethod
+    def from_params(cls, params: AudioMarkdownBlockParams) -> AudioMarkdownNode:
+        return cls(url=params.url, caption=params.caption)
+
+    def to_markdown(self) -> str:
+        if self.caption:
+            return f'[audio]({self.url} "{self.caption}")'
+        return f"[audio]({self.url})"

notionary/blocks/audio/audio_models.py

@@ -0,0 +1,59 @@
+from typing import Optional
+from pydantic import BaseModel
+
+from notionary.blocks.shared.models import RichTextObject
+
+
+# TODO: Diesen Kram hier auch verwenden
+class ExternalAudioSource(BaseModel):
+    """External audio source."""
+
+    url: str
+
+
+class NotionAudioData(BaseModel):
+    """Audio block data."""
+
+    type: str = "external"
+    external: ExternalAudioSource
+    caption: list[dict] = []
+
+
+class NotionAudioBlock(BaseModel):
+    """Audio block result."""
+
+    type: str = "audio"
+    audio: NotionAudioData
+
+
+# Updated method with typed return
+@classmethod
+def markdown_to_notion(cls, text: str) -> Optional[NotionAudioBlock]:
+    """Convert markdown audio embed to Notion audio block."""
+    audio_match = cls.PATTERN.match(text.strip())
+    if not audio_match:
+        return None
+
+    url = audio_match.group(1)
+    caption_text = audio_match.group(2)
+
+    if not url:
+        return None
+
+    # Validate URL if possible
+    if not cls._is_likely_audio_url(url):
+        # Still proceed - user might know better
+        pass
+
+    # Build caption list
+    caption_list = []
+    if caption_text:
+        caption_rich_text = RichTextObject.from_plain_text(caption_text)
+        caption_list = [caption_rich_text.model_dump()]
+
+    # Create typed result
+    return NotionAudioBlock(
+        audio=NotionAudioData(
+            external=ExternalAudioSource(url=url), caption=caption_list
+        )
+    )

notionary/blocks/bookmark/__init__.py

@@ -0,0 +1,7 @@
+from .bookmark_element import BookmarkElement
+from .bookmark_markdown_node import BookmarkMarkdownNode
+
+__all__ = [
+    "BookmarkElement",
+    "BookmarkMarkdownNode",
+]

notionary/blocks/{bookmark_element.py → bookmark/bookmark_element.py}

@@ -2,7 +2,12 @@ import re
 from typing import Dict, Any, Optional, List, Tuple
 
 from notionary.blocks import NotionBlockElement
-from notionary.blocks import ElementPromptContent, ElementPromptBuilder
+from notionary.blocks import (
+    ElementPromptContent,
+    ElementPromptBuilder,
+    NotionBlockResult,
+)
+from notionary.blocks.shared.models import RichTextObject
 
 
 class BookmarkElement(NotionBlockElement):
@@ -33,7 +38,7 @@ class BookmarkElement(NotionBlockElement):
     def match_markdown(cls, text: str) -> bool:
         """Check if text is a markdown bookmark."""
         return text.strip().startswith("[bookmark]") and bool(
-            BookmarkElement.PATTERN.match(text.strip())
+            cls.PATTERN.match(text.strip())
         )
 
     @classmethod
@@ -42,7 +47,7 @@ class BookmarkElement(NotionBlockElement):
         return block.get("type") in ["bookmark", "external-bookmark"]
 
     @classmethod
-    def markdown_to_notion(cls, text: str) -> Optional[Dict[str, Any]]:
+    def markdown_to_notion(cls, text: str) -> NotionBlockResult:
         """Convert markdown bookmark to Notion bookmark block."""
         bookmark_match = BookmarkElement.PATTERN.match(text.strip())
         if not bookmark_match:
@@ -54,71 +59,21 @@ class BookmarkElement(NotionBlockElement):
 
         bookmark_data = {"url": url}
 
-        # Add caption if title or description is provided
-        if title or description:
-            caption = []
-
-            if title:
-                caption.append(
-                    {
-                        "type": "text",
-                        "text": {"content": title, "link": None},
-                        "annotations": {
-                            "bold": False,
-                            "italic": False,
-                            "strikethrough": False,
-                            "underline": False,
-                            "code": False,
-                            "color": "default",
-                        },
-                        "plain_text": title,
-                        "href": None,
-                    }
-                )
-
-                # Add a separator if both title and description are provided
-                if description:
-                    caption.append(
-                        {
-                            "type": "text",
-                            "text": {"content": " - ", "link": None},
-                            "annotations": {
-                                "bold": False,
-                                "italic": False,
-                                "strikethrough": False,
-                                "underline": False,
-                                "code": False,
-                                "color": "default",
-                            },
-                            "plain_text": " - ",
-                            "href": None,
-                        }
-                    )
-
-            if description:
-                caption.append(
-                    {
-                        "type": "text",
-                        "text": {"content": description, "link": None},
-                        "annotations": {
-                            "bold": False,
-                            "italic": False,
-                            "strikethrough": False,
-                            "underline": False,
-                            "code": False,
-                            "color": "default",
-                        },
-                        "plain_text": description,
-                        "href": None,
-                    }
-                )
-
-            bookmark_data["caption"] = caption
+        # Build caption string
+        caption_parts = []
+        if title:
+            caption_parts.append(title)
+        if description:
+            caption_parts.append(description)
+
+        if caption_parts:
+            caption_text = " - ".join(caption_parts)
+            caption_rich_text = RichTextObject.from_plain_text(caption_text)
+            bookmark_data["caption"] = [caption_rich_text.model_dump()]
         else:
-            # Empty caption list to match Notion's format for bookmarks without titles
             bookmark_data["caption"] = []
 
-        return {"type": "bookmark", "bookmark": bookmark_data}
+        return [{"type": "bookmark", "bookmark": bookmark_data}]
 
     @classmethod
     def notion_to_markdown(cls, block: Dict[str, Any]) -> Optional[str]:

notionary/blocks/bookmark/bookmark_markdown_node.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+from typing import Optional
+from pydantic import BaseModel
+
+from notionary.blocks.markdown_node import MarkdownNode
+
+
+class BookmarkMarkdownBlockParams(BaseModel):
+    url: str
+    title: Optional[str] = None
+    description: Optional[str] = None
+
+
+class BookmarkMarkdownNode(MarkdownNode):
+    """
+    Programmatic interface for creating Notion-style bookmark Markdown blocks.
+    """
+
+    def __init__(
+        self, url: str, title: Optional[str] = None, description: Optional[str] = None
+    ):
+        self.url = url
+        self.title = title
+        self.description = description
+
+    @classmethod
+    def from_params(cls, params: BookmarkMarkdownBlockParams) -> BookmarkMarkdownNode:
+        return cls(url=params.url, title=params.title, description=params.description)
+
+    def to_markdown(self) -> str:
+        """
+        Returns the Markdown representation, e.g.:
+        [bookmark](https://example.com "Title" "Description")
+        """
+        parts = [f"[bookmark]({self.url}"]
+        if self.title is not None:
+            parts.append(f'"{self.title}"')
+        if self.description is not None:
+            # Wenn title fehlt, aber description da ist, trotzdem Platzhalter für title:
+            if self.title is None:
+                parts.append('""')
+            parts.append(f'"{self.description}"')
+        return " ".join(parts) + ")"

notionary/blocks/bulleted_list/__init__.py

@@ -0,0 +1,7 @@
+from .bulleted_list_element import BulletedListElement
+from .bulleted_list_markdown_node import BulletedListMarkdownNode
+
+__all__ = [
+    "BulletedListElement",
+    "BulletedListMarkdownNode",
+]

notionary/blocks/{bulleted_list_element.py → bulleted_list/bulleted_list_element.py}

@@ -1,16 +1,20 @@
 import re
 from typing import Dict, Any, Optional
 from notionary.blocks import NotionBlockElement
-from notionary.blocks import ElementPromptContent, ElementPromptBuilder
+from notionary.blocks import (
+    ElementPromptContent,
+    ElementPromptBuilder,
+    NotionBlockResult,
+)
 
-from notionary.blocks.text_inline_formatter import TextInlineFormatter
+from notionary.blocks.shared.text_inline_formatter import TextInlineFormatter
 
 
 class BulletedListElement(NotionBlockElement):
     """Class for converting between Markdown bullet lists and Notion bulleted list items."""
 
     @classmethod
-    def markdown_to_notion(cls, text: str) -> Optional[Dict[str, Any]]:
+    def markdown_to_notion(cls, text: str) -> NotionBlockResult:
         """Convert markdown bulleted list item to Notion block."""
         pattern = re.compile(
             r"^(\s*)[*\-+]\s+(?!\[[ x]\])(.+)$"

notionary/blocks/bulleted_list/bulleted_list_markdown_node.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+from pydantic import BaseModel
+from notionary.blocks.markdown_node import MarkdownNode
+
+
+class BulletedListMarkdownBlockParams(BaseModel):
+    texts: list[str]
+
+
+class BulletedListMarkdownNode(MarkdownNode):
+    """
+    Programmatic interface for creating Markdown bulleted list items.
+    Example:
+    - First item
+    - Second item
+    - Third item
+    """
+
+    def __init__(self, texts: list[str]):
+        self.texts = texts
+
+    @classmethod
+    def from_params(
+        cls, params: BulletedListMarkdownBlockParams
+    ) -> BulletedListMarkdownNode:
+        return cls(texts=params.texts)
+
+    def to_markdown(self) -> str:
+        result = []
+        for text in self.texts:
+            result.append(f"- {text}")
+        return "\n".join(result)

notionary/blocks/callout/__init__.py

@@ -0,0 +1,7 @@
+from .callout_element import CalloutElement
+from .callout_markdown_node import CalloutMarkdownNode
+
+__all__ = [
+    "CalloutElement",
+    "CalloutMarkdownNode",
+]