notionary 0.1.13__tar.gz → 0.1.14__tar.gz

{notionary-0.1.13 → notionary-0.1.14}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: notionary
-Version: 0.1.13
+Version: 0.1.14
 Summary: A toolkit to convert between Markdown and Notion blocks
 Home-page: https://github.com/mathisarends/notionary
 Author: Mathis Arends

{notionary-0.1.13 → notionary-0.1.14}/notionary/__init__.py

@@ -7,8 +7,8 @@ from .database.database_discovery import DatabaseDiscovery
 from .page.notion_page import NotionPage
 from .page.notion_page_factory import NotionPageFactory
 
-from .converters.registry.block_element_registry import BlockElementRegistry
-from .converters.registry.block_element_registry_builder import (
+from .elements.block_element_registry import BlockElementRegistry
+from .elements.block_element_registry_builder import (
     BlockElementRegistryBuilder,
 )
 

{notionary-0.1.13/notionary/converters → notionary-0.1.14/notionary}/elements/audio_element.py

@@ -1,6 +1,6 @@
 import re
 from typing import Dict, Any, Optional, List
-from notionary.converters.elements.notion_block_element import NotionBlockElement
+from notionary.elements.notion_block_element import NotionBlockElement
 
 
 class AudioElement(NotionBlockElement):

{notionary-0.1.13/notionary/converters/registry → notionary-0.1.14/notionary/elements}/block_element_registry.py

@@ -1,7 +1,7 @@
 from typing import Dict, Any, Optional, List, Type
 
-from notionary.converters.elements.notion_block_element import NotionBlockElement
-from notionary.converters.elements.text_inline_formatter import TextInlineFormatter
+from notionary.elements.notion_block_element import NotionBlockElement
+from notionary.elements.text_inline_formatter import TextInlineFormatter
 
 
 class BlockElementRegistry:
@@ -96,9 +96,6 @@ class BlockElementRegistry:
         # Create a copy of registered elements
         element_classes = self._elements.copy()
 
-        # TODO: Das hier besser formattieren und über debug level lösen . )
-        print("Elements in registry:", element_classes)
-
         formatter_names = [e.__name__ for e in element_classes]
         if "TextInlineFormatter" not in formatter_names:
             element_classes = [TextInlineFormatter] + element_classes

notionary-0.1.14/notionary/elements/block_element_registry_builder.py

@@ -0,0 +1,401 @@
+from __future__ import annotations
+from typing import List, Type
+from collections import OrderedDict
+
+from notionary.elements.audio_element import AudioElement
+from notionary.elements.embed_element import EmbedElement
+from notionary.elements.mention_element import MentionElement
+from notionary.elements.notion_block_element import NotionBlockElement
+from notionary.elements.block_element_registry import (
+    BlockElementRegistry,
+)
+
+from notionary.elements.paragraph_element import ParagraphElement
+from notionary.elements.heading_element import HeadingElement
+from notionary.elements.callout_element import CalloutElement
+from notionary.elements.code_block_element import CodeBlockElement
+from notionary.elements.divider_element import DividerElement
+from notionary.elements.table_element import TableElement
+from notionary.elements.todo_lists import TodoElement
+from notionary.elements.list_element import (
+    BulletedListElement,
+    NumberedListElement,
+)
+from notionary.elements.qoute_element import QuoteElement
+from notionary.elements.image_element import ImageElement
+from notionary.elements.video_element import VideoElement
+from notionary.elements.toggle_element import ToggleElement
+from notionary.elements.bookmark_element import BookmarkElement
+from notionary.elements.column_element import ColumnElement
+
+
+class BlockElementRegistryBuilder:
+    """
+    True builder for constructing BlockElementRegistry instances.
+
+    This builder allows for incremental construction of registry instances
+    with specific configurations of block elements.
+    """
+
+    def __init__(self):
+        """Initialize a new builder with an empty element list."""
+        self._elements = OrderedDict()
+
+    @classmethod
+    def start_empty(cls) -> BlockElementRegistryBuilder:
+        """
+        Start with a completely empty registry builder.
+
+        Returns:
+            A new builder instance with no elements
+        """
+        return cls()
+
+    @classmethod
+    def start_minimal(cls) -> BlockElementRegistryBuilder:
+        """
+        Start with a minimal set of essential elements.
+
+        Returns:
+            A new builder instance with basic elements
+        """
+        builder = cls()
+        return builder.with_headings().with_lists().with_paragraphs()
+
+    @classmethod
+    def start_standard(cls) -> BlockElementRegistryBuilder:
+        """
+        Start with all standard elements in recommended order.
+
+        Returns:
+            A new builder instance with all standard elements
+        """
+        builder = cls()
+        return (
+            builder.with_headings()
+            .with_callouts()
+            .with_code()
+            .with_dividers()
+            .with_tables()
+            .with_columns()
+            .with_lists()
+            .with_toggles()
+            .with_quotes()
+            .with_todos()
+            .with_bookmarks()
+            .with_images()
+            .with_videos()
+            .with_embeds()
+            .with_audio()
+            .with_mention()
+            .with_paragraphs()
+        )
+
+    # Element manipulation methods
+
+    def add_element(
+        self, element_class: Type[NotionBlockElement]
+    ) -> BlockElementRegistryBuilder:
+        """
+        Add an element class to the registry configuration.
+        If the element already exists, it's moved to the end.
+
+        Args:
+            element_class: The element class to add
+
+        Returns:
+            Self for method chaining
+        """
+        self._elements.pop(element_class.__name__, None)
+        self._elements[element_class.__name__] = element_class
+
+        return self
+
+    def add_elements(
+        self, element_classes: List[Type[NotionBlockElement]]
+    ) -> BlockElementRegistryBuilder:
+        """
+        Add multiple element classes to the registry configuration.
+
+        Args:
+            element_classes: List of element classes to add
+
+        Returns:
+            Self for method chaining
+        """
+        for element_class in element_classes:
+            self.add_element(element_class)
+        return self
+
+    def remove_element(
+        self, element_class: Type[NotionBlockElement]
+    ) -> BlockElementRegistryBuilder:
+        """
+        Remove an element class from the registry configuration.
+
+        Args:
+            element_class: The element class to remove
+
+        Returns:
+            Self for method chaining
+        """
+        self._elements.pop(element_class.__name__, None)
+        return self
+
+    def move_element_to_end(
+        self, element_class: Type[NotionBlockElement]
+    ) -> BlockElementRegistryBuilder:
+        """
+        Move an existing element to the end of the registry.
+        If the element doesn't exist, it will be added.
+
+        Args:
+            element_class: The element class to move
+
+        Returns:
+            Self for method chaining
+        """
+        return self.add_element(element_class)  # add_element already handles this logic
+
+    def _ensure_paragraph_at_end(self) -> None:
+        """
+        Internal method to ensure ParagraphElement is the last element in the registry.
+        """
+        if ParagraphElement.__name__ in self._elements:
+            paragraph_class = self._elements.pop(ParagraphElement.__name__)
+            self._elements[ParagraphElement.__name__] = paragraph_class
+
+    def with_paragraphs(self) -> BlockElementRegistryBuilder:
+        """
+        Add support for paragraph elements.
+
+        Returns:
+            Self for method chaining
+        """
+        return self.add_element(ParagraphElement)
+
+    def with_headings(self) -> BlockElementRegistryBuilder:
+        """
+        Add support for heading elements.
+
+        Returns:
+            Self for method chaining
+        """
+        return self.add_element(HeadingElement)
+
+    def with_callouts(self) -> BlockElementRegistryBuilder:
+        """
+        Add support for callout elements.
+
+        Returns:
+            Self for method chaining
+        """
+        return self.add_element(CalloutElement)
+
+    def with_code(self) -> BlockElementRegistryBuilder:
+        """
+        Add support for code blocks.
+
+        Returns:
+            Self for method chaining
+        """
+        return self.add_element(CodeBlockElement)
+
+    def with_dividers(self) -> BlockElementRegistryBuilder:
+        """
+        Add support for divider elements.
+
+        Returns:
+            Self for method chaining
+        """
+        return self.add_element(DividerElement)
+
+    def with_tables(self) -> BlockElementRegistryBuilder:
+        """
+        Add support for tables.
+
+        Returns:
+            Self for method chaining
+        """
+        return self.add_element(TableElement)
+
+    def with_columns(self) -> BlockElementRegistryBuilder:
+        """
+        Add support for column elements.
+
+        Returns:
+            Self for method chaining
+        """
+        return self.add_element(ColumnElement)
+
+    def with_lists(self) -> BlockElementRegistryBuilder:
+        """
+        Add support for list elements.
+
+        Returns:
+            Self for method chaining
+        """
+        return self.add_element(BulletedListElement).add_element(NumberedListElement)
+
+    def with_toggles(self) -> BlockElementRegistryBuilder:
+        """
+        Add support for toggle elements.
+
+        Returns:
+            Self for method chaining
+        """
+        return self.add_element(ToggleElement)
+
+    def with_quotes(self) -> BlockElementRegistryBuilder:
+        """
+        Add support for quote elements.
+
+        Returns:
+            Self for method chaining
+        """
+        return self.add_element(QuoteElement)
+
+    def with_todos(self) -> BlockElementRegistryBuilder:
+        """
+        Add support for todo elements.
+
+        Returns:
+            Self for method chaining
+        """
+        return self.add_element(TodoElement)
+
+    def with_bookmarks(self) -> BlockElementRegistryBuilder:
+        """
+        Add support for bookmark elements.
+
+        Returns:
+            Self for method chaining
+        """
+        return self.add_element(BookmarkElement)
+
+    def with_images(self) -> BlockElementRegistryBuilder:
+        """
+        Add support for image elements.
+
+        Returns:
+            Self for method chaining
+        """
+        return self.add_element(ImageElement)
+
+    def with_videos(self) -> BlockElementRegistryBuilder:
+        """
+        Add support for video elements.
+
+        Returns:
+            Self for method chaining
+        """
+        return self.add_element(VideoElement)
+
+    def with_embeds(self) -> BlockElementRegistryBuilder:
+        """
+        Add support for embed elements.
+
+        Returns:
+            Self for method chaining
+        """
+        return self.add_element(EmbedElement)
+
+    def with_audio(self) -> BlockElementRegistryBuilder:
+        """
+        Add support for audio elements.
+
+        Returns:
+            Self for method chaining
+        """
+        return self.add_element(AudioElement)
+
+    def with_rich_content(self) -> BlockElementRegistryBuilder:
+        """
+        Add support for rich content elements (callouts, toggles, etc.).
+
+        Returns:
+            Self for method chaining
+        """
+        return self.with_callouts().with_toggles().with_quotes()
+
+    def with_media_support(self) -> BlockElementRegistryBuilder:
+        """
+        Add support for media elements (images, videos, audio).
+
+        Returns:
+            Self for method chaining
+        """
+        return self.with_images().with_videos().with_audio()
+
+    def with_task_support(self) -> BlockElementRegistryBuilder:
+        """
+        Add support for task-related elements (todos).
+
+        Returns:
+            Self for method chaining
+        """
+        return self.with_todos()
+    
+    def with_mention(self) -> BlockElementRegistryBuilder:
+        return self.add_element(MentionElement)
+
+    def build(self) -> BlockElementRegistry:
+        """
+        Build and return the configured BlockElementRegistry instance.
+
+        This automatically ensures that ParagraphElement is at the end
+        of the registry (if present) as a fallback element, unless
+        this behavior was explicitly disabled.
+
+        Returns:
+            A configured BlockElementRegistry instance
+        """
+        if ParagraphElement.__name__ not in self._elements:
+            # Add paragraph as fallback if not present
+            self.add_element(ParagraphElement)
+        else:
+            # Ensure it's at the end
+            self._ensure_paragraph_at_end()
+
+        registry = BlockElementRegistry()
+
+        # Add elements in the recorded order
+        for element_class in self._elements.values():
+            registry.register(element_class)
+
+        return registry
+
+    @classmethod
+    def create_standard_registry(cls) -> BlockElementRegistry:
+        """
+        Factory method to directly create a standard registry.
+
+        Returns:
+            A fully configured registry instance
+        """
+        return cls.start_standard().build()
+
+    @classmethod
+    def create_minimal_registry(cls) -> BlockElementRegistry:
+        """
+        Factory method to directly create a minimal registry.
+
+        Returns:
+            A minimal registry instance
+        """
+        return cls.start_minimal().build()
+
+    @classmethod
+    def create_custom_registry(
+        cls, element_classes: List[Type[NotionBlockElement]]
+    ) -> BlockElementRegistry:
+        """
+        Factory method to directly create a custom registry.
+
+        Args:
+            element_classes: List of element classes to register
+
+        Returns:
+            A custom configured registry instance
+        """
+        return cls().add_elements(element_classes).build()

{notionary-0.1.13/notionary/converters → notionary-0.1.14/notionary}/elements/bookmark_element.py

@@ -2,7 +2,7 @@ import re
 from typing import Dict, Any, Optional, List, Tuple
 from typing_extensions import override
 
-from notionary.converters.elements.notion_block_element import NotionBlockElement
+from notionary.elements.notion_block_element import NotionBlockElement
 
 
 class BookmarkElement(NotionBlockElement):

{notionary-0.1.13/notionary/converters → notionary-0.1.14/notionary}/elements/callout_element.py

@@ -2,8 +2,8 @@ from typing import Dict, Any, Optional
 from typing_extensions import override
 import re
 
-from notionary.converters.elements.text_inline_formatter import TextInlineFormatter
-from notionary.converters.elements.notion_block_element import NotionBlockElement
+from notionary.elements.text_inline_formatter import TextInlineFormatter
+from notionary.elements.notion_block_element import NotionBlockElement
 
 
 class CalloutElement(NotionBlockElement):

{notionary-0.1.13/notionary/converters → notionary-0.1.14/notionary}/elements/code_block_element.py

@@ -1,7 +1,7 @@
 from typing import Dict, Any, Optional, List, Tuple
 from typing_extensions import override
 import re
-from notionary.converters.elements.notion_block_element import NotionBlockElement
+from notionary.elements.notion_block_element import NotionBlockElement
 
 
 class CodeBlockElement(NotionBlockElement):

{notionary-0.1.13/notionary/converters → notionary-0.1.14/notionary}/elements/column_element.py

@@ -2,7 +2,7 @@ import re
 from typing import Dict, Any, Optional, List, Tuple, Callable
 from typing_extensions import override
 
-from notionary.converters.elements.notion_block_element import NotionBlockElement
+from notionary.elements.notion_block_element import NotionBlockElement
 
 
 class ColumnElement(NotionBlockElement):

{notionary-0.1.13/notionary/converters → notionary-0.1.14/notionary}/elements/divider_element.py

@@ -4,7 +4,7 @@ from typing import Dict, Any, Optional
 from typing_extensions import override
 import re
 
-from notionary.converters.elements.notion_block_element import NotionBlockElement
+from notionary.elements.notion_block_element import NotionBlockElement
 
 
 class DividerElement(NotionBlockElement):

{notionary-0.1.13/notionary/converters → notionary-0.1.14/notionary}/elements/embed_element.py

@@ -1,6 +1,6 @@
 import re
 from typing import Dict, Any, Optional, List
-from notionary.converters.elements.notion_block_element import NotionBlockElement
+from notionary.elements.notion_block_element import NotionBlockElement
 
 
 class EmbedElement(NotionBlockElement):

{notionary-0.1.13/notionary/converters → notionary-0.1.14/notionary}/elements/heading_element.py

@@ -2,8 +2,8 @@ from typing import Dict, Any, Optional
 from typing_extensions import override
 import re
 
-from notionary.converters.elements.notion_block_element import NotionBlockElement
-from notionary.converters.elements.text_inline_formatter import TextInlineFormatter
+from notionary.elements.notion_block_element import NotionBlockElement
+from notionary.elements.text_inline_formatter import TextInlineFormatter
 
 
 class HeadingElement(NotionBlockElement):

{notionary-0.1.13/notionary/converters → notionary-0.1.14/notionary}/elements/image_element.py

@@ -1,7 +1,7 @@
 import re
 from typing import Dict, Any, Optional, List
 from typing_extensions import override
-from notionary.converters.elements.notion_block_element import NotionBlockElement
+from notionary.elements.notion_block_element import NotionBlockElement
 
 
 class ImageElement(NotionBlockElement):

{notionary-0.1.13/notionary/converters → notionary-0.1.14/notionary}/elements/list_element.py

@@ -1,8 +1,8 @@
 import re
 from typing import Dict, Any, Optional
 from typing_extensions import override
-from notionary.converters.elements.notion_block_element import NotionBlockElement
-from notionary.converters.elements.text_inline_formatter import TextInlineFormatter
+from notionary.elements.notion_block_element import NotionBlockElement
+from notionary.elements.text_inline_formatter import TextInlineFormatter
 
 
 class BulletedListElement(NotionBlockElement):

notionary-0.1.14/notionary/elements/mention_element.py

@@ -0,0 +1,135 @@
+from typing import Dict, Any, Optional, List
+from typing_extensions import override
+
+from notionary.elements.notion_block_element import NotionBlockElement
+
+class MentionElement(NotionBlockElement):
+    """
+    Handles conversion between Markdown mentions and Notion mention elements.
+    
+    Markdown mention syntax:
+    - @[page-id] - Mention a page by its ID
+    
+    Note: This element primarily supports Notion-to-Markdown conversion,
+    as page mentions in Markdown would typically require knowing internal page IDs.
+    """
+    
+    @override
+    @staticmethod
+    def match_markdown(text: str) -> bool:
+        """Check if text is a markdown mention."""
+        return False
+    
+    @override
+    @staticmethod
+    def match_notion(block: Dict[str, Any]) -> bool:
+        """Check if block contains a mention."""
+        if block.get("type") not in ["paragraph", "heading_1", "heading_2", "heading_3", "bulleted_list_item", "numbered_list_item"]:
+            return False
+            
+        block_content = block.get(block.get("type"), {})
+        rich_text = block_content.get("rich_text", [])
+        
+        for text_item in rich_text:
+            if text_item.get("type") == "mention":
+                return True
+                
+        return False
+    
+    @override
+    @staticmethod
+    def markdown_to_notion(text: str) -> Optional[Dict[str, Any]]:
+        """Convert markdown mention to Notion mention block."""
+        # This would be handled within rich text processing rather than as a standalone block
+        return None
+    
+    @override
+    @staticmethod
+    def notion_to_markdown(block: Dict[str, Any]) -> Optional[str]:
+        """Extract mentions from Notion block and convert to markdown format."""
+        block_type = block.get("type")
+        if not block_type or block_type not in block:
+            return None
+            
+        block_content = block.get(block_type, {})
+        rich_text = block_content.get("rich_text", [])
+        
+        processed_text = MentionElement._process_rich_text_with_mentions(rich_text)
+        
+        if MentionElement._is_only_mentions(rich_text):
+            return processed_text
+            
+        return None
+    
+    @staticmethod
+    def _process_rich_text_with_mentions(rich_text: List[Dict[str, Any]]) -> str:
+        """Process rich text array and convert any mentions to markdown format."""
+        result = []
+        
+        for item in rich_text:
+            if item.get("type") == "mention":
+                mention = item.get("mention", {})
+                mention_type = mention.get("type")
+                
+                if mention_type == "page":
+                    page_id = mention.get("page", {}).get("id", "")
+                    result.append(f"@[{page_id}]")
+                elif mention_type == "user":
+                    user_id = mention.get("user", {}).get("id", "")
+                    result.append(f"@user[{user_id}]")
+                elif mention_type == "date":
+                    date_value = mention.get("date", {}).get("start", "")
+                    result.append(f"@date[{date_value}]")
+                elif mention_type == "database":
+                    db_id = mention.get("database", {}).get("id", "")
+                    result.append(f"@db[{db_id}]")
+                else:
+                    # Unknown mention type, fallback to plain text if available
+                    result.append(item.get("plain_text", "@[unknown]"))
+            else:
+                # Regular text item
+                result.append(item.get("plain_text", ""))
+                
+        return "".join(result)
+    
+    @staticmethod
+    def _is_only_mentions(rich_text: List[Dict[str, Any]]) -> bool:
+        """Check if rich_text array contains only mentions."""
+        if not rich_text:
+            return False
+            
+        for item in rich_text:
+            if item.get("type") != "mention":
+                return False
+                
+        return True
+    
+    @override
+    @staticmethod
+    def is_multiline() -> bool:
+        return False
+    
+    @classmethod
+    def get_llm_prompt_content(cls) -> dict:
+        """
+        Returns a dictionary with all information needed for LLM prompts about this element.
+        """
+        return {
+            "description": "References to Notion pages, users, databases, or dates within text content.",
+            "when_to_use": "Mentions are typically part of rich text content rather than standalone elements. They're used to link to other Notion content or users.",
+            "syntax": [
+                "@[page-id] - Reference to a Notion page",
+                "@user[user-id] - Reference to a Notion user",
+                "@date[YYYY-MM-DD] - Reference to a date",
+                "@db[database-id] - Reference to a Notion database"
+            ],
+            "examples": [
+                "Check the meeting notes at @[1a6389d5-7bd3-80c5-9a87-e90b034989d0]",
+                "Please review this with @user[d3dbbbd7-ec00-4204-94d9-e4a46e4928db]",
+                "Deadline is @date[2023-12-31]"
+            ],
+            "limitations": [
+                "Mentions are typically created through Notion's UI rather than direct markdown input",
+                "When converting Notion content to markdown, mentions are represented with their internal IDs"
+            ]
+        }