notionary 0.1.18__py3-none-any.whl → 0.1.20__py3-none-any.whl

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 .elements.block_element_registry import BlockElementRegistry
-from .elements.block_element_registry_builder import (
+from .elements.registry.block_element_registry import BlockElementRegistry
+from .elements.registry.block_element_registry_builder import (
     BlockElementRegistryBuilder,
 )
 

notionary/database/notion_database.py

@@ -230,7 +230,9 @@ class NotionDatabase(LoggingMixin):
             if response and "last_edited_time" in response:
                 return response["last_edited_time"]
 
-            self.logger.warning("Could not retrieve last_edited_time for database %s", self.database_id)
+            self.logger.warning(
+                "Could not retrieve last_edited_time for database %s", self.database_id
+            )
             return None
 
         except Exception as e:

notionary/elements/audio_element.py

@@ -1,6 +1,7 @@
 import re
 from typing import Dict, Any, Optional, List
 from notionary.elements.notion_block_element import NotionBlockElement
+from notionary.elements.prompts.element_prompt_content import ElementPromptContent
 
 
 class AudioElement(NotionBlockElement):
@@ -121,23 +122,18 @@ class AudioElement(NotionBlockElement):
         return result
 
     @classmethod
-    def get_llm_prompt_content(cls) -> dict:
+    def get_llm_prompt_content(cls) -> ElementPromptContent:
         """Returns information for LLM prompts about this element."""
         return {
             "description": "Embeds audio content from external sources like CDNs or direct audio URLs.",
-            "when_to_use": "Use audio embeds when you want to include audio content directly in your document. Audio embeds are useful for podcasts, music, voice recordings, or any content that benefits from audio explanation.",
-            "syntax": [
-                "$[](https://example.com/audio.mp3) - Audio without caption",
-                "$[Caption text](https://example.com/audio.mp3) - Audio with caption",
-            ],
-            "supported_sources": [
-                "Direct links to audio files (.mp3, .wav, .ogg, etc.)",
-                "Google Cloud Storage links (storage.googleapis.com)",
-                "Other audio hosting platforms supported by Notion",
-            ],
+            "syntax": "$[Caption](https://example.com/audio.mp3)",
             "examples": [
                 "$[Podcast Episode](https://storage.googleapis.com/audio_summaries/ep_ai_summary_127d02ec-ca12-4312-a5ed-cb14b185480c.mp3)",
                 "$[Voice recording](https://example.com/audio/recording.mp3)",
                 "$[](https://storage.googleapis.com/audio_summaries/example.mp3)",
             ],
+            "when_to_use": (
+                "Use audio embeds when you want to include audio content directly in your document. "
+                "Audio embeds are useful for podcasts, music, voice recordings, or any content that benefits from audio explanation."
+            ),
         }

notionary/elements/bookmark_element.py

@@ -1,8 +1,8 @@
 import re
 from typing import Dict, Any, Optional, List, Tuple
-from typing_extensions import override
 
 from notionary.elements.notion_block_element import NotionBlockElement
+from notionary.elements.prompts.element_prompt_content import ElementPromptContent
 
 
 class BookmarkElement(NotionBlockElement):
@@ -29,7 +29,6 @@ class BookmarkElement(NotionBlockElement):
         + r"\)$"  # closing parenthesis
     )
 
-    @override
     @staticmethod
     def match_markdown(text: str) -> bool:
         """Check if text is a markdown bookmark."""
@@ -37,14 +36,11 @@ class BookmarkElement(NotionBlockElement):
             BookmarkElement.PATTERN.match(text.strip())
         )
 
-    @override
     @staticmethod
     def match_notion(block: Dict[str, Any]) -> bool:
         """Check if block is a Notion bookmark."""
-        # Handle both standard "bookmark" type and "external-bookmark" type
         return block.get("type") in ["bookmark", "external-bookmark"]
 
-    @override
     @staticmethod
     def markdown_to_notion(text: str) -> Optional[Dict[str, Any]]:
         """Convert markdown bookmark to Notion bookmark block."""
@@ -124,7 +120,6 @@ class BookmarkElement(NotionBlockElement):
 
         return {"type": "bookmark", "bookmark": bookmark_data}
 
-    @override
     @staticmethod
     def notion_to_markdown(block: Dict[str, Any]) -> Optional[str]:
         """Convert Notion bookmark block to markdown bookmark."""
@@ -133,13 +128,10 @@ class BookmarkElement(NotionBlockElement):
         if block_type == "bookmark":
             bookmark_data = block.get("bookmark", {})
         elif block_type == "external-bookmark":
-            # Handle external-bookmark type
-            # Extract URL from the external-bookmark structure
             url = block.get("url", "")
             if not url:
                 return None
 
-            # For external bookmarks, create a simple bookmark format
             return f"[bookmark]({url})"
         else:
             return None
@@ -160,12 +152,12 @@ class BookmarkElement(NotionBlockElement):
 
         if title and description:
             return f'[bookmark]({url} "{title}" "{description}")'
-        elif title:
+
+        if title:
             return f'[bookmark]({url} "{title}")'
-        else:
-            return f"[bookmark]({url})"
 
-    @override
+        return f"[bookmark]({url})"
+
     @staticmethod
     def is_multiline() -> bool:
         """Bookmarks are single-line elements."""
@@ -191,34 +183,30 @@ class BookmarkElement(NotionBlockElement):
         if not caption:
             return "", ""
 
-        # Extract the full text content from caption
         full_text = BookmarkElement._extract_text_content(caption)
 
-        # Check if the text contains a separator
         if " - " in full_text:
             parts = full_text.split(" - ", 1)
             return parts[0].strip(), parts[1].strip()
-        else:
-            # If no separator, assume the whole content is the title
-            return full_text.strip(), ""
 
-    @override
+        return full_text.strip(), ""
+
     @classmethod
-    def get_llm_prompt_content(cls) -> dict:
+    def get_llm_prompt_content(cls) -> ElementPromptContent:
         """
-        Returns a dictionary with all information needed for LLM prompts about this element.
-        Includes description, usage guidance, syntax options, and examples.
+        Returns structured LLM prompt metadata for the bookmark element.
         """
         return {
             "description": "Creates a bookmark that links to an external website.",
-            "when_to_use": "Use bookmarks when you want to reference external content while keeping the page clean and organized. Bookmarks display a preview card for the linked content.",
-            "syntax": [
-                "[bookmark](https://example.com) - Simple bookmark with URL only",
-                '[bookmark](https://example.com "Title") - Bookmark with URL and title',
-                '[bookmark](https://example.com "Title" "Description") - Bookmark with URL, title, and description',
-            ],
+            "when_to_use": (
+                "Use bookmarks when you want to reference external content while keeping the page clean and organized. "
+                "Bookmarks display a preview card for the linked content."
+            ),
+            "syntax": '[bookmark](https://example.com "Optional Title" "Optional Description")',
             "examples": [
-                '[bookmark](https://notion.so "Notion Homepage" "Your connected workspace")',
+                "[bookmark](https://example.com)",
+                '[bookmark](https://example.com "Example Title")',
+                '[bookmark](https://example.com "Example Title" "Example description of the site")',
                 '[bookmark](https://github.com "GitHub" "Where the world builds software")',
             ],
         }

notionary/elements/bulleted_list_element.py

@@ -0,0 +1,69 @@
+import re
+from typing import Dict, Any, Optional
+from typing_extensions import override
+from notionary.elements.notion_block_element import NotionBlockElement
+from notionary.elements.prompts.element_prompt_content import ElementPromptContent
+from notionary.elements.text_inline_formatter import TextInlineFormatter
+
+
+class BulletedListElement(NotionBlockElement):
+    """Class for converting between Markdown bullet lists and Notion bulleted list items."""
+
+    @override
+    @staticmethod
+    def markdown_to_notion(text: str) -> Optional[Dict[str, Any]]:
+        """Convert markdown bulleted list item to Notion block."""
+        pattern = re.compile(
+            r"^(\s*)[*\-+]\s+(?!\[[ x]\])(.+)$"
+        )  # Avoid matching todo items
+        list_match = pattern.match(text)
+        if not list_match:
+            return None
+
+        content = list_match.group(2)
+
+        # Use parse_inline_formatting to handle rich text
+        rich_text = TextInlineFormatter.parse_inline_formatting(content)
+
+        return {
+            "type": "bulleted_list_item",
+            "bulleted_list_item": {"rich_text": rich_text, "color": "default"},
+        }
+
+    @staticmethod
+    def notion_to_markdown(block: Dict[str, Any]) -> Optional[str]:
+        """Convert Notion bulleted list item block to markdown."""
+        if block.get("type") != "bulleted_list_item":
+            return None
+
+        rich_text = block.get("bulleted_list_item", {}).get("rich_text", [])
+        content = TextInlineFormatter.extract_text_with_formatting(rich_text)
+
+        return f"- {content}"
+
+    @staticmethod
+    def match_markdown(text: str) -> bool:
+        """Check if this element can handle the given markdown text."""
+        pattern = re.compile(r"^(\s*)[*\-+]\s+(?!\[[ x]\])(.+)$")
+        return bool(pattern.match(text))
+
+    @staticmethod
+    def match_notion(block: Dict[str, Any]) -> bool:
+        """Check if this element can handle the given Notion block."""
+        return block.get("type") == "bulleted_list_item"
+
+    @classmethod
+    def get_llm_prompt_content(cls) -> ElementPromptContent:
+        """
+        Returns structured LLM prompt metadata for the bulleted list element.
+        """
+        return {
+            "description": "Creates bulleted list items for unordered lists.",
+            "when_to_use": "Use for lists where order doesn't matter, such as features, options, or items without hierarchy.",
+            "syntax": "- Item text",
+            "examples": [
+                "- First item\n- Second item\n- Third item",
+                "* Apple\n* Banana\n* Cherry",
+                "+ Task A\n+ Task B",
+            ],
+        }

notionary/elements/callout_element.py

@@ -1,7 +1,8 @@
+import re
 from typing import Dict, Any, Optional
 from typing_extensions import override
-import re
 
+from notionary.elements.prompts.element_prompt_content import ElementPromptContent
 from notionary.elements.text_inline_formatter import TextInlineFormatter
 from notionary.elements.notion_block_element import NotionBlockElement
 
@@ -12,53 +13,21 @@ class CalloutElement(NotionBlockElement):
 
     Markdown callout syntax:
     - !> [emoji] Text - Callout with custom emoji
-    - !> {color} [emoji] Text - Callout with custom color and emoji
-    - !> Text - Simple callout with default emoji and color
+    - !> Text - Simple callout with default emoji
 
     Where:
-    - {color} can be one of Notion's color options (e.g., "blue_background")
     - [emoji] is any emoji character
     - Text is the callout content with optional inline formatting
     """
 
-    COLOR_PATTERN = r"(?:(?:{([a-z_]+)})?\s*)?"
     EMOJI_PATTERN = r"(?:\[([^\]]+)\])?\s*"
     TEXT_PATTERN = r"(.+)"
 
-    # Combine the patterns
-    PATTERN = re.compile(
-        r"^!>\s+"  # Callout prefix
-        + COLOR_PATTERN
-        + EMOJI_PATTERN
-        + TEXT_PATTERN
-        + r"$"  # End of line
-    )
+    PATTERN = re.compile(r"^!>\s+" + EMOJI_PATTERN + TEXT_PATTERN + r"$")
 
     DEFAULT_EMOJI = "💡"
     DEFAULT_COLOR = "gray_background"
 
-    VALID_COLORS = [
-        "default",
-        "gray",
-        "brown",
-        "orange",
-        "yellow",
-        "green",
-        "blue",
-        "purple",
-        "pink",
-        "red",
-        "gray_background",
-        "brown_background",
-        "orange_background",
-        "yellow_background",
-        "green_background",
-        "blue_background",
-        "purple_background",
-        "pink_background",
-        "red_background",
-    ]
-
     @override
     @staticmethod
     def match_markdown(text: str) -> bool:
@@ -81,22 +50,18 @@ class CalloutElement(NotionBlockElement):
         if not callout_match:
             return None
 
-        color = callout_match.group(1)
-        emoji = callout_match.group(2)
-        content = callout_match.group(3)
+        emoji = callout_match.group(1)
+        content = callout_match.group(2)
 
         if not emoji:
             emoji = CalloutElement.DEFAULT_EMOJI
 
-        if not color or color not in CalloutElement.VALID_COLORS:
-            color = CalloutElement.DEFAULT_COLOR
-
         return {
             "type": "callout",
             "callout": {
                 "rich_text": TextInlineFormatter.parse_inline_formatting(content),
                 "icon": {"type": "emoji", "emoji": emoji},
-                "color": color,
+                "color": CalloutElement.DEFAULT_COLOR,
             },
         }
 
@@ -110,7 +75,6 @@ class CalloutElement(NotionBlockElement):
         callout_data = block.get("callout", {})
         rich_text = callout_data.get("rich_text", [])
         icon = callout_data.get("icon", {})
-        color = callout_data.get("color", CalloutElement.DEFAULT_COLOR)
 
         text = TextInlineFormatter.extract_text_with_formatting(rich_text)
         if not text:
@@ -120,15 +84,11 @@ class CalloutElement(NotionBlockElement):
         if icon and icon.get("type") == "emoji":
             emoji = icon.get("emoji", "")
 
-        color_str = ""
-        if color and color != CalloutElement.DEFAULT_COLOR:
-            color_str = f"{{{color}}} "
-
         emoji_str = ""
-        if emoji:
+        if emoji and emoji != CalloutElement.DEFAULT_EMOJI:
             emoji_str = f"[{emoji}] "
 
-        return f"!> {color_str}{emoji_str}{text}"
+        return f"!> {emoji_str}{text}"
 
     @override
     @staticmethod
@@ -136,44 +96,22 @@ class CalloutElement(NotionBlockElement):
         return False
 
     @classmethod
-    def get_llm_prompt_content(cls) -> dict:
+    def get_llm_prompt_content(cls) -> ElementPromptContent:
         """
         Returns a dictionary with all information needed for LLM prompts about this element.
         Includes description, usage guidance, syntax options, and examples.
         """
         return {
-            "description": "Creates a callout block to highlight important information with an icon and background color.",
-            "when_to_use": "Use callouts when you want to draw attention to important information, tips, warnings, or notes that stand out from the main content.",
-            "syntax": [
-                "!> Text - Simple callout with default emoji (💡) and color (gray background)",
-                "!> [emoji] Text - Callout with custom emoji",
-                "!> {color} [emoji] Text - Callout with custom color and emoji",
-            ],
-            "color_options": [
-                "default",
-                "gray",
-                "brown",
-                "orange",
-                "yellow",
-                "green",
-                "blue",
-                "purple",
-                "pink",
-                "red",
-                "gray_background",
-                "brown_background",
-                "orange_background",
-                "yellow_background",
-                "green_background",
-                "blue_background",
-                "purple_background",
-                "pink_background",
-                "red_background",
-            ],
+            "description": "Creates a callout block to highlight important information with an icon.",
+            "when_to_use": (
+                "Use callouts when you want to draw attention to important information, "
+                "tips, warnings, or notes that stand out from the main content."
+            ),
+            "syntax": "!> [emoji] Text",
             "examples": [
                 "!> This is a default callout with the light bulb emoji",
                 "!> [🔔] This is a callout with a bell emoji",
-                "!> {blue_background} [💧] This is a blue callout with a water drop emoji",
-                "!> {yellow_background} [⚠️] Warning: This is an important note to pay attention to",
+                "!> [⚠️] Warning: This is an important note to pay attention to",
+                "!> [💡] Tip: Add emoji that matches your content's purpose",
             ],
         }

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 typing import Dict, Any, Optional, List, Tuple
 from notionary.elements.notion_block_element import NotionBlockElement
+from notionary.elements.prompts.element_prompt_content import ElementPromptContent
 
 
 class CodeBlockElement(NotionBlockElement):
@@ -20,19 +20,16 @@ class CodeBlockElement(NotionBlockElement):
 
     PATTERN = re.compile(r"```(\w*)\n([\s\S]+?)```", re.MULTILINE)
 
-    @override
     @staticmethod
     def match_markdown(text: str) -> bool:
         """Check if text contains a markdown code block."""
         return bool(CodeBlockElement.PATTERN.search(text))
 
-    @override
     @staticmethod
     def match_notion(block: Dict[str, Any]) -> bool:
         """Check if block is a Notion code block."""
         return block.get("type") == "code"
 
-    @override
     @staticmethod
     def markdown_to_notion(text: str) -> Optional[Dict[str, Any]]:
         """Convert markdown code block to Notion code block."""
@@ -68,7 +65,6 @@ class CodeBlockElement(NotionBlockElement):
             },
         }
 
-    @override
     @staticmethod
     def notion_to_markdown(block: Dict[str, Any]) -> Optional[str]:
         """Convert Notion code block to markdown code block."""
@@ -134,20 +130,29 @@ class CodeBlockElement(NotionBlockElement):
 
         return matches
 
-    @override
     @staticmethod
     def is_multiline() -> bool:
         return True
 
     @classmethod
-    def get_llm_prompt_content(cls) -> dict:
+    def get_llm_prompt_content(cls) -> ElementPromptContent:
         """
-        Returns a dictionary with all information needed for LLM prompts about this element.
+        Returns structured LLM prompt metadata for the code block element.
         """
         return {
-            "description": "Use fenced code blocks to format content as code. Supports language annotations like 'python', 'json', or 'mermaid'. Use when you want to display code, configurations, command-line examples, or diagram syntax. Also useful when breaking down or visualizing a system or architecture for complex problems (e.g. using mermaid).",
+            "description": (
+                "Use fenced code blocks to format content as code. Supports language annotations like "
+                "'python', 'json', or 'mermaid'. Useful for displaying code, configurations, command-line "
+                "examples, or diagram syntax. Also suitable for explaining or visualizing systems with diagram languages."
+            ),
+            "when_to_use": (
+                "Use code blocks when you want to present technical content like code snippets, terminal commands, "
+                "JSON structures, or system diagrams. Especially helpful when structure and formatting are essential."
+            ),
+            "syntax": "```language\ncode content\n```",
             "examples": [
                 "```python\nprint('Hello, world!')\n```",
+                '```json\n{"name": "Alice", "age": 30}\n```',
                 "```mermaid\nflowchart TD\n  A --> B\n```",
             ],
         }

notionary/elements/column_element.py

@@ -1,8 +1,8 @@
 import re
 from typing import Dict, Any, Optional, List, Tuple, Callable
-from typing_extensions import override
 
 from notionary.elements.notion_block_element import NotionBlockElement
+from notionary.elements.prompts.element_prompt_content import ElementPromptContent
 
 
 class ColumnElement(NotionBlockElement):
@@ -40,19 +40,16 @@ class ColumnElement(NotionBlockElement):
         """
         cls._converter_callback = callback
 
-    @override
     @staticmethod
     def match_markdown(text: str) -> bool:
         """Check if text starts a columns block."""
         return bool(ColumnElement.COLUMNS_START.match(text.strip()))
 
-    @override
     @staticmethod
     def match_notion(block: Dict[str, Any]) -> bool:
         """Check if block is a Notion column_list."""
         return block.get("type") == "column_list"
 
-    @override
     @staticmethod
     def markdown_to_notion(text: str) -> Optional[Dict[str, Any]]:
         """
@@ -68,7 +65,6 @@ class ColumnElement(NotionBlockElement):
         # Child columns will be added by the column processor
         return {"type": "column_list", "column_list": {"children": []}}
 
-    @override
     @staticmethod
     def notion_to_markdown(block: Dict[str, Any]) -> Optional[str]:
         """Convert Notion column_list block to markdown column syntax."""
@@ -95,7 +91,6 @@ class ColumnElement(NotionBlockElement):
 
         return "\n".join(result)
 
-    @override
     @staticmethod
     def is_multiline() -> bool:
         """Column blocks span multiple lines."""
@@ -264,31 +259,49 @@ class ColumnElement(NotionBlockElement):
         columns_children.append(column_block)
 
     @classmethod
-    def get_llm_prompt_content(cls) -> dict:
+    def get_llm_prompt_content(cls) -> ElementPromptContent:
         """
-        Returns a dictionary with all information needed for LLM prompts about this element.
-        Includes description, usage guidance, syntax options, and examples.
+        Returns structured LLM prompt metadata for the column layout element.
         """
         return {
             "description": "Creates a multi-column layout that displays content side by side.",
-            "when_to_use": "Use columns sparingly, only for direct comparisons or when parallel presentation significantly improves readability. Best for pros/cons lists, feature comparisons, or pairing images with descriptions. Avoid overusing as it can complicate document structure.",
-            "syntax": [
-                "::: columns",
-                "::: column",
-                "Content for first column",
-                ":::",
-                "::: column",
-                "Content for second column",
+            "when_to_use": (
+                "Use columns sparingly, only for direct comparisons or when parallel presentation significantly improves readability. "
+                "Best for pros/cons lists, feature comparisons, or pairing images with descriptions. "
+                "Avoid overusing as it can complicate document structure."
+            ),
+            "syntax": (
+                "::: columns\n"
+                "::: column\n"
+                "Content for first column\n"
+                ":::\n"
+                "::: column\n"
+                "Content for second column\n"
+                ":::\n"
+                ":::"
+            ),
+            "examples": [
+                "::: columns\n"
+                "::: column\n"
+                "## Features\n"
+                "- Fast response time\n"
+                "- Intuitive interface\n"
+                "- Regular updates\n"
+                ":::\n"
+                "::: column\n"
+                "## Benefits\n"
+                "- Increased productivity\n"
+                "- Better collaboration\n"
+                "- Simplified workflows\n"
+                ":::\n"
                 ":::",
+                "::: columns\n"
+                "::: column\n"
+                "![Image placeholder](/api/placeholder/400/320)\n"
+                ":::\n"
+                "::: column\n"
+                "This text appears next to the image, creating a media-with-caption style layout that's perfect for documentation or articles.\n"
+                ":::\n"
                 ":::",
             ],
-            "notes": [
-                "Any Notion block can be placed within columns",
-                "Add more columns with additional '::: column' sections",
-                "Each column must close with ':::' and the entire columns section with another ':::'",
-            ],
-            "examples": [
-                "::: columns\n::: column\n## Features\n- Fast response time\n- Intuitive interface\n- Regular updates\n:::\n::: column\n## Benefits\n- Increased productivity\n- Better collaboration\n- Simplified workflows\n:::\n:::",
-                "::: columns\n::: column\n![Image placeholder](/api/placeholder/400/320)\n:::\n::: column\nThis text appears next to the image, creating a media-with-caption style layout that's perfect for documentation or articles.\n:::\n:::",
-            ],
         }