notionary 0.1.2__tar.gz → 0.1.4__tar.gz

{notionary-0.1.2 → notionary-0.1.4}/PKG-INFO

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

notionary-0.1.4/notionary/core/converters/__init__.py

@@ -0,0 +1,50 @@
+# Import converters
+from .markdown_to_notion_converter import MarkdownToNotionConverter
+from .notion_to_markdown_converter import NotionToMarkdownConverter
+
+# Import registry classes
+from .registry.block_element_registry import BlockElementRegistry
+from .registry.block_element_registry_builder import BlockElementRegistryBuilder
+
+# Import elements for type hints and direct use
+from .elements.paragraph_element import ParagraphElement
+from .elements.heading_element import HeadingElement
+from .elements.callout_element import CalloutElement
+from .elements.code_block_element import CodeBlockElement
+from .elements.divider_element import DividerElement
+from .elements.table_element import TableElement
+from .elements.todo_lists import TodoElement
+from .elements.list_element import BulletedListElement, NumberedListElement
+from .elements.qoute_element import QuoteElement
+from .elements.image_element import ImageElement
+from .elements.video_element import VideoElement
+from .elements.toggle_element import ToggleElement
+from .elements.bookmark_element import BookmarkElement
+from .elements.column_element import ColumnElement
+
+default_registry = BlockElementRegistryBuilder.create_standard_registry()
+
+# Define what to export
+__all__ = [
+    "BlockElementRegistry",
+    "BlockElementRegistryBuilder",
+    "MarkdownToNotionConverter",
+    "NotionToMarkdownConverter",
+    "default_registry",
+    # Element classes
+    "ParagraphElement",
+    "HeadingElement",
+    "CalloutElement",
+    "CodeBlockElement",
+    "DividerElement",
+    "TableElement",
+    "TodoElement",
+    "QuoteElement",
+    "BulletedListElement",
+    "NumberedListElement",
+    "ImageElement",
+    "VideoElement",
+    "ToggleElement",
+    "BookmarkElement",
+    "ColumnElement",
+]

notionary-0.1.4/notionary/core/converters/elements/bookmark_element.py

@@ -0,0 +1,224 @@
+import re
+from typing import Dict, Any, Optional, List, Tuple
+from typing_extensions import override
+
+from notionary.core.converters.elements.notion_block_element import NotionBlockElement
+
+
+class BookmarkElement(NotionBlockElement):
+    """
+    Handles conversion between Markdown bookmarks and Notion bookmark blocks.
+
+    Markdown bookmark 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
+
+    Where:
+    - URL is the required bookmark URL
+    - Title is an optional title (enclosed in quotes)
+    - Description is an optional description (enclosed in quotes)
+    """
+
+    # Regex pattern for bookmark syntax with optional title and description
+    PATTERN = re.compile(
+        r"^\[bookmark\]\("  # [bookmark]( prefix
+        + r'(https?://[^\s"]+)'  # URL (required)
+        + r'(?:\s+"([^"]+)")?'  # Optional title in quotes
+        + r'(?:\s+"([^"]+)")?'  # Optional description in quotes
+        + r"\)$"  # closing parenthesis
+    )
+
+    @override
+    @staticmethod
+    def match_markdown(text: str) -> bool:
+        """Check if text is a markdown bookmark."""
+        return text.strip().startswith("[bookmark]") and bool(
+            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."""
+        bookmark_match = BookmarkElement.PATTERN.match(text.strip())
+        if not bookmark_match:
+            return None
+
+        url = bookmark_match.group(1)
+        title = bookmark_match.group(2)
+        description = bookmark_match.group(3)
+
+        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
+        else:
+            # Empty caption list to match Notion's format for bookmarks without titles
+            bookmark_data["caption"] = []
+
+        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."""
+        block_type = block.get("type", "")
+
+        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
+
+        url = bookmark_data.get("url", "")
+
+        if not url:
+            return None
+
+        caption = bookmark_data.get("caption", [])
+
+        if not caption:
+            # Simple bookmark with URL only
+            return f"[bookmark]({url})"
+
+        # Extract title and description from caption
+        title, description = BookmarkElement._parse_caption(caption)
+
+        if title and description:
+            return f'[bookmark]({url} "{title}" "{description}")'
+        elif title:
+            return f'[bookmark]({url} "{title}")'
+        else:
+            return f"[bookmark]({url})"
+
+    @override
+    @staticmethod
+    def is_multiline() -> bool:
+        """Bookmarks are single-line elements."""
+        return False
+
+    @staticmethod
+    def _extract_text_content(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
+
+    @staticmethod
+    def _parse_caption(caption: List[Dict[str, Any]]) -> Tuple[str, str]:
+        """
+        Parse Notion caption into title and description components.
+        Returns a tuple of (title, description).
+        """
+        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
+    @classmethod
+    def get_llm_prompt_content(cls) -> dict:
+        """
+        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 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',
+            ],
+            "examples": [
+                '[bookmark](https://notion.so "Notion Homepage" "Your connected workspace")',
+                '[bookmark](https://github.com "GitHub" "Where the world builds software")',
+            ],
+        }

notionary-0.1.4/notionary/core/converters/elements/callout_element.py

@@ -0,0 +1,179 @@
+from typing import Dict, Any, Optional
+from typing_extensions import override
+import re
+
+from notionary.core.converters.elements.text_inline_formatter import TextInlineFormatter
+from notionary.core.converters.elements.notion_block_element import NotionBlockElement
+
+
+class CalloutElement(NotionBlockElement):
+    """
+    Handles conversion between Markdown callouts and Notion callout blocks.
+
+    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
+
+    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
+    )
+
+    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:
+        """Check if text is a markdown callout."""
+        return text.strip().startswith("!>") and bool(
+            CalloutElement.PATTERN.match(text)
+        )
+
+    @override
+    @staticmethod
+    def match_notion(block: Dict[str, Any]) -> bool:
+        """Check if block is a Notion callout."""
+        return block.get("type") == "callout"
+
+    @override
+    @staticmethod
+    def markdown_to_notion(text: str) -> Optional[Dict[str, Any]]:
+        """Convert markdown callout to Notion callout block."""
+        callout_match = CalloutElement.PATTERN.match(text)
+        if not callout_match:
+            return None
+
+        color = callout_match.group(1)
+        emoji = callout_match.group(2)
+        content = callout_match.group(3)
+
+        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,
+            },
+        }
+
+    @override
+    @staticmethod
+    def notion_to_markdown(block: Dict[str, Any]) -> Optional[str]:
+        """Convert Notion callout block to markdown callout."""
+        if block.get("type") != "callout":
+            return None
+
+        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:
+            return None
+
+        emoji = ""
+        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:
+            emoji_str = f"[{emoji}] "
+
+        return f"!> {color_str}{emoji_str}{text}"
+
+    @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.
+        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",
+            ],
+            "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",
+            ],
+        }

notionary-0.1.4/notionary/core/converters/elements/code_block_element.py

@@ -0,0 +1,153 @@
+from typing import Dict, Any, Optional, List, Tuple
+from typing_extensions import override
+import re
+from notionary.core.converters.elements.notion_block_element import NotionBlockElement
+
+
+class CodeBlockElement(NotionBlockElement):
+    """
+    Handles conversion between Markdown code blocks and Notion code blocks.
+
+    Markdown code block syntax:
+    ```language
+    code content
+    ```
+
+    Where:
+    - language is optional and specifies the programming language
+    - code content is the code to be displayed
+    """
+
+    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."""
+        match = CodeBlockElement.PATTERN.search(text)
+        if not match:
+            return None
+
+        language = match.group(1) or "plain text"
+        content = match.group(2)
+
+        if content.endswith("\n"):
+            content = content[:-1]
+
+        return {
+            "type": "code",
+            "code": {
+                "rich_text": [
+                    {
+                        "type": "text",
+                        "text": {"content": content},
+                        "annotations": {
+                            "bold": False,
+                            "italic": False,
+                            "strikethrough": False,
+                            "underline": False,
+                            "code": False,
+                            "color": "default",
+                        },
+                        "plain_text": content,
+                    }
+                ],
+                "language": language,
+            },
+        }
+
+    @override
+    @staticmethod
+    def notion_to_markdown(block: Dict[str, Any]) -> Optional[str]:
+        """Convert Notion code block to markdown code block."""
+        if block.get("type") != "code":
+            return None
+
+        code_data = block.get("code", {})
+        rich_text = code_data.get("rich_text", [])
+
+        # Extract the code content
+        content = ""
+        for text_block in rich_text:
+            content += text_block.get("plain_text", "")
+
+        language = code_data.get("language", "")
+
+        # Format as a markdown code block
+        return f"```{language}\n{content}\n```"
+
+    @staticmethod
+    def find_matches(text: str) -> List[Tuple[int, int, Dict[str, Any]]]:
+        """
+        Find all code block matches in the text and return their positions.
+
+        Args:
+            text: The text to search in
+
+        Returns:
+            List of tuples with (start_pos, end_pos, block)
+        """
+        matches = []
+        for match in CodeBlockElement.PATTERN.finditer(text):
+            language = match.group(1) or "plain text"
+            content = match.group(2)
+
+            # Remove trailing newline if present
+            if content.endswith("\n"):
+                content = content[:-1]
+
+            block = {
+                "type": "code",
+                "code": {
+                    "rich_text": [
+                        {
+                            "type": "text",
+                            "text": {"content": content},
+                            "annotations": {
+                                "bold": False,
+                                "italic": False,
+                                "strikethrough": False,
+                                "underline": False,
+                                "code": False,
+                                "color": "default",
+                            },
+                            "plain_text": content,
+                        }
+                    ],
+                    "language": language,
+                },
+            }
+
+            matches.append((match.start(), match.end(), block))
+
+        return matches
+
+    @override
+    @staticmethod
+    def is_multiline() -> bool:
+        return True
+
+    @classmethod
+    def get_llm_prompt_content(cls) -> dict:
+        """
+        Returns a dictionary with all information needed for LLM prompts about this 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).",
+            "examples": [
+                "```python\nprint('Hello, world!')\n```",
+                "```mermaid\nflowchart TD\n  A --> B\n```",
+            ],
+        }