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

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",
+]

notionary/blocks/callout/callout_element.py

@@ -0,0 +1,132 @@
+import re
+from typing import Dict, Any, Optional, List
+
+from notionary.blocks.shared.text_inline_formatter import TextInlineFormatter
+from notionary.blocks import (
+    NotionBlockElement,
+    ElementPromptContent,
+    ElementPromptBuilder,
+    NotionBlockResult,
+)
+
+
+class CalloutElement(NotionBlockElement):
+    """
+    Handles conversion between Markdown callouts and Notion callout blocks.
+
+    Markdown callout syntax:
+    - [callout](Text) - Simple callout with default emoji
+    - [callout](Text "emoji") - Callout with custom emoji
+
+    Where:
+    - Text is the required callout content
+    - emoji is an optional emoji character (enclosed in quotes)
+    """
+
+    # Regex pattern for callout syntax with optional emoji
+    PATTERN = re.compile(
+        r"^\[callout\]\("  # [callout]( prefix
+        + r'([^"]+?)'  # Text content (required)
+        + r'(?:\s+"([^"]+)")?'  # Optional emoji in quotes
+        + r"\)$"  # closing parenthesis
+    )
+
+    # Default values
+    DEFAULT_EMOJI = "💡"
+    DEFAULT_COLOR = "gray_background"
+
+    @classmethod
+    def match_markdown(cls, text: str) -> bool:
+        """Check if text is a markdown callout."""
+        return text.strip().startswith("[callout]") and bool(
+            CalloutElement.PATTERN.match(text.strip())
+        )
+
+    @classmethod
+    def match_notion(cls, block: Dict[str, Any]) -> bool:
+        """Check if block is a Notion callout."""
+        return block.get("type") == "callout"
+
+    @classmethod
+    def markdown_to_notion(cls, text: str) -> NotionBlockResult:
+        """Convert markdown callout to Notion callout block."""
+        callout_match = CalloutElement.PATTERN.match(text.strip())
+        if not callout_match:
+            return None
+
+        content = callout_match.group(1)
+        emoji = callout_match.group(2)
+
+        if not content:
+            return None
+
+        # Use default emoji if none provided
+        if not emoji:
+            emoji = CalloutElement.DEFAULT_EMOJI
+
+        callout_data = {
+            "rich_text": TextInlineFormatter.parse_inline_formatting(content.strip()),
+            "icon": {"type": "emoji", "emoji": emoji},
+            "color": CalloutElement.DEFAULT_COLOR,
+        }
+
+        return {"type": "callout", "callout": callout_data}
+
+    @classmethod
+    def notion_to_markdown(cls, 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", {})
+
+        content = TextInlineFormatter.extract_text_with_formatting(rich_text)
+        if not content:
+            return None
+
+        emoji = CalloutElement._extract_emoji(icon)
+
+        if emoji and emoji != CalloutElement.DEFAULT_EMOJI:
+            return f'[callout]({content} "{emoji}")'
+
+        return f"[callout]({content})"
+
+    @classmethod
+    def is_multiline(cls) -> bool:
+        """Callouts are single-line elements."""
+        return False
+
+    @classmethod
+    def _extract_emoji(cls, icon: Dict[str, Any]) -> str:
+        """Extract emoji from Notion icon object."""
+        if icon and icon.get("type") == "emoji":
+            return icon.get("emoji", "")
+        return ""
+
+    @classmethod
+    def get_llm_prompt_content(cls) -> ElementPromptContent:
+        """
+        Returns structured LLM prompt metadata for the callout element.
+        """
+        return (
+            ElementPromptBuilder()
+            .with_description(
+                "Creates a callout block to highlight important information with an icon."
+            )
+            .with_usage_guidelines(
+                "Use callouts when you want to draw attention to important information, "
+                "tips, warnings, or notes that stand out from the main content."
+            )
+            .with_syntax('[callout](Text content "Optional emoji")')
+            .with_examples(
+                [
+                    "[callout](This is a default callout with the light bulb emoji)",
+                    '[callout](This is a callout with a bell emoji "🔔")',
+                    '[callout](Warning: This is an important note "⚠️")',
+                    '[callout](Tip: Add emoji that matches your content\'s purpose "💡")',
+                ]
+            )
+            .build()
+        )

notionary/blocks/callout/callout_markdown_node.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from typing import Optional
+from pydantic import BaseModel
+from notionary.blocks.markdown_node import MarkdownNode
+
+
+class CalloutMarkdownBlockParams(BaseModel):
+    text: str
+    emoji: Optional[str] = None
+
+
+class CalloutMarkdownNode(MarkdownNode):
+    """
+    Programmatic interface for creating Notion-style callout Markdown blocks.
+    Example: [callout](This is important "⚠️")
+    """
+
+    def __init__(self, text: str, emoji: Optional[str] = None):
+        self.text = text
+        self.emoji = emoji
+
+    @classmethod
+    def from_params(cls, params: CalloutMarkdownBlockParams) -> CalloutMarkdownNode:
+        return cls(text=params.text, emoji=params.emoji)
+
+    def to_markdown(self) -> str:
+        if self.emoji and self.emoji != "💡":
+            return f'[callout]({self.text} "{self.emoji}")'
+        else:
+            return f"[callout]({self.text})"

notionary/blocks/code/__init__.py

@@ -0,0 +1,7 @@
+from .code_element import CodeElement
+from .code_markdown_node import CodeMarkdownNode
+
+__all__ = [
+    "CodeElement",
+    "CodeMarkdownNode",
+]

notionary/blocks/{code_block_element.py → code/code_element.py}

@@ -1,11 +1,16 @@
 import re
 
-from typing import Dict, Any, Optional, List, Tuple
+from typing import Optional, Any
 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 CodeBlockElement(NotionBlockElement):
+class CodeElement(NotionBlockElement):
     """
     Handles conversion between Markdown code blocks and Notion code blocks.
 
@@ -28,17 +33,17 @@ class CodeBlockElement(NotionBlockElement):
     @classmethod
     def match_markdown(cls, text: str) -> bool:
         """Check if text contains a markdown code block."""
-        return bool(CodeBlockElement.PATTERN.search(text))
+        return bool(cls.PATTERN.search(text))
 
     @classmethod
-    def match_notion(cls, block: Dict[str, Any]) -> bool:
+    def match_notion(cls, block: dict[str, any]) -> bool:
         """Check if block is a Notion code block."""
         return block.get("type") == "code"
 
     @classmethod
-    def markdown_to_notion(cls, text: str) -> Optional[Dict[str, Any]]:
+    def markdown_to_notion(cls, text: str) -> NotionBlockResult:
         """Convert markdown code block to Notion code block."""
-        match = CodeBlockElement.PATTERN.search(text)
+        match = cls.PATTERN.search(text)
         if not match:
             return None
 
@@ -49,65 +54,73 @@ class CodeBlockElement(NotionBlockElement):
         if content.endswith("\n"):
             content = content[:-1]
 
+        # Create code block with rich text
+        content_rich_text = RichTextObject.from_plain_text(content)
+
         block = {
             "type": "code",
             "code": {
-                "rich_text": [
-                    {
-                        "type": "text",
-                        "text": {"content": content},
-                        "plain_text": content,
-                    }
-                ],
+                "rich_text": [content_rich_text.model_dump()],
                 "language": language,
             },
         }
 
         # Add caption if provided
         if caption and caption.strip():
-            block["code"]["caption"] = [
-                {
-                    "type": "text",
-                    "text": {"content": caption.strip()},
-                    "plain_text": caption.strip(),
-                }
-            ]
+            caption_rich_text = RichTextObject.from_plain_text(caption.strip())
+            block["code"]["caption"] = [caption_rich_text.model_dump()]
+
+        # Leerer Paragraph nach dem Code-Block
+        empty_paragraph = {"type": "paragraph", "paragraph": {"rich_text": []}}
 
-        return block
+        return [block, empty_paragraph]
 
     @classmethod
-    def notion_to_markdown(cls, block: Dict[str, Any]) -> Optional[str]:
-        """Convert Notion code block to markdown code block."""
+    def notion_to_markdown(cls, block: dict[str, Any]) -> Optional[str]:
+        """Convert Notion code block to Markdown."""
         if block.get("type") != "code":
             return None
 
         code_data = block.get("code", {})
+        language = code_data.get("language", "")
         rich_text = code_data.get("rich_text", [])
+        caption = code_data.get("caption", [])
+
+        def extract_content(rich_text_list):
+            """Extract code content from rich_text array."""
+            return "".join(
+                text.get("text", {}).get("content", "")
+                if text.get("type") == "text"
+                else text.get("plain_text", "")
+                for text in rich_text_list
+            )
 
-        # Extract the code content
-        content = ""
-        for text_block in rich_text:
-            content += text_block.get("plain_text", "")
+        def extract_caption(caption_list):
+            """Extract caption text from caption array."""
+            return "".join(
+                c.get("text", {}).get("content", "")
+                for c in caption_list
+                if c.get("type") == "text"
+            )
 
-        language = code_data.get("language", "")
+        code_content = extract_content(rich_text)
+        caption_text = extract_caption(caption)
 
-        # Extract caption if present
-        caption_text = ""
-        caption_data = code_data.get("caption", [])
-        for caption_block in caption_data:
-            caption_text += caption_block.get("plain_text", "")
+        # Handle language - convert "plain text" back to empty string for markdown
+        if language == "plain text":
+            language = ""
 
-        # Format as a markdown code block
-        result = f"```{language}\n{content}\n```"
+        # Build markdown code block
+        result = f"```{language}\n{code_content}\n```" if language else f"```\n{code_content}\n```"
 
         # Add caption if present
-        if caption_text.strip():
+        if caption_text:
             result += f"\nCaption: {caption_text}"
 
         return result
 
     @classmethod
-    def find_matches(cls, text: str) -> List[Tuple[int, int, Dict[str, Any]]]:
+    def find_matches(cls, text: str) -> list[tuple[int, int, dict[str, any]]]:
         """
         Find all code block matches in the text and return their positions.
 
@@ -118,7 +131,7 @@ class CodeBlockElement(NotionBlockElement):
             List of tuples with (start_pos, end_pos, block)
         """
         matches = []
-        for match in CodeBlockElement.PATTERN.finditer(text):
+        for match in CodeElement.PATTERN.finditer(text):
             language = match.group(1) or "plain text"
             content = match.group(2)
             caption = match.group(3)
@@ -187,7 +200,7 @@ class CodeBlockElement(NotionBlockElement):
                     "```python\nprint('Hello, world!')\n```\nCaption: Basic Python greeting example",
                     '```json\n{"name": "Alice", "age": 30}\n```\nCaption: User data structure',
                     "```mermaid\nflowchart TD\n  A --> B\n```\nCaption: Simple flow diagram",
-                    '```bash\ngit commit -m "Initial commit"\n```',  # Without caption
+                    '```bash\ngit commit -m "Initial commit"\n```',
                 ]
             )
             .with_avoidance_guidelines(
@@ -200,3 +213,22 @@ class CodeBlockElement(NotionBlockElement):
             )
             .build()
         )
+
+    @staticmethod
+    def extract_content(rich_text_list: list[dict[str, Any]]) -> str:
+        """Extract code content from rich_text array."""
+        return "".join(
+            text.get("text", {}).get("content", "")
+            if text.get("type") == "text"
+            else text.get("plain_text", "")
+            for text in rich_text_list
+        )
+
+    @staticmethod
+    def extract_caption(caption_list: list[dict[str, Any]]) -> str:
+        """Extract caption text from caption array."""
+        return "".join(
+            c.get("text", {}).get("content", "")
+            for c in caption_list
+            if c.get("type") == "text"
+        )

notionary/blocks/code/code_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 CodeMarkdownBlockParams(BaseModel):
+    code: str
+    language: Optional[str] = None
+    caption: Optional[str] = None
+
+
+class CodeMarkdownNode(MarkdownNode):
+    """
+    Programmatic interface for creating Notion-style Markdown code blocks.
+    Example:
+        ```python
+        print("Hello, world!")
+        ```
+        Caption: Basic usage
+    """
+
+    def __init__(
+        self,
+        code: str,
+        language: Optional[str] = None,
+        caption: Optional[str] = None,
+    ):
+        self.code = code
+        self.language = language or ""
+        self.caption = caption
+
+    @classmethod
+    def from_params(cls, params: CodeMarkdownBlockParams) -> CodeMarkdownNode:
+        return cls(code=params.code, language=params.language, caption=params.caption)
+
+    def to_markdown(self) -> str:
+        lang = self.language or ""
+        content = f"```{lang}\n{self.code}\n```"
+        if self.caption:
+            content += f"\nCaption: {self.caption}"
+        return content

notionary/blocks/column/__init__.py

@@ -0,0 +1,5 @@
+from .column_element import ColumnElement
+
+__all__ = [
+    "ColumnElement",
+]

notionary/blocks/{column_element.py → column/column_element.py}

@@ -1,9 +1,12 @@
 import re
-from typing import Dict, Any, Optional, List, Tuple, Callable
+from typing import Optional, Callable
 
 from notionary.blocks import NotionBlockElement
-from notionary.page.formatting.spacer_rules import SPACER_MARKER
-from notionary.blocks import ElementPromptContent, ElementPromptBuilder
+from notionary.blocks import (
+    ElementPromptContent,
+    ElementPromptBuilder,
+    NotionBlockResult,
+)
 
 
 class ColumnElement(NotionBlockElement):
@@ -31,7 +34,7 @@ class ColumnElement(NotionBlockElement):
 
     @classmethod
     def set_converter_callback(
-        cls, callback: Callable[[str], List[Dict[str, Any]]]
+        cls, callback: Callable[[str], list[dict[str, any]]]
     ) -> None:
         """
         Setze die Callback-Funktion, die zum Konvertieren von Markdown zu Notion-Blöcken verwendet wird.
@@ -47,12 +50,12 @@ class ColumnElement(NotionBlockElement):
         return bool(ColumnElement.COLUMNS_START.match(text.strip()))
 
     @staticmethod
-    def match_notion(block: Dict[str, Any]) -> bool:
+    def match_notion(block: dict[str, any]) -> bool:
         """Check if block is a Notion column_list."""
         return block.get("type") == "column_list"
 
     @staticmethod
-    def markdown_to_notion(text: str) -> Optional[Dict[str, Any]]:
+    def markdown_to_notion(text: str) -> NotionBlockResult:
         """
         Convert markdown column syntax to Notion column blocks.
 
@@ -64,10 +67,10 @@ class ColumnElement(NotionBlockElement):
 
         # Create an empty column_list block
         # Child columns will be added by the column processor
-        return {"type": "column_list", "column_list": {"children": []}}
+        return [{"type": "column_list", "column_list": {"children": []}}]
 
     @staticmethod
-    def notion_to_markdown(block: Dict[str, Any]) -> Optional[str]:
+    def notion_to_markdown(block: dict[str, any]) -> Optional[str]:
         """Convert Notion column_list block to markdown column syntax."""
         if block.get("type") != "column_list":
             return None
@@ -100,7 +103,7 @@ class ColumnElement(NotionBlockElement):
     @classmethod
     def find_matches(
         cls, text: str, converter_callback: Optional[Callable] = None
-    ) -> List[Tuple[int, int, Dict[str, Any]]]:
+    ) -> list[tuple[int, int, dict[str, any]]]:
         """
         Find all column block matches in the text and return their positions and blocks.
 
@@ -141,8 +144,8 @@ class ColumnElement(NotionBlockElement):
 
     @classmethod
     def _process_column_block(
-        cls, lines: List[str], start_index: int, converter_callback: Callable
-    ) -> Tuple[int, int, Dict[str, Any], int]:
+        cls, lines: list[str], start_index: int, converter_callback: Callable
+    ) -> tuple[int, int, dict[str, any], int]:
         """
         Process a complete column block structure from the given starting line.
 
@@ -155,7 +158,8 @@ class ColumnElement(NotionBlockElement):
             Tuple of (start_pos, end_pos, block, next_line_index)
         """
         columns_start = start_index
-        columns_block = cls.markdown_to_notion(lines[start_index].strip())
+        columns_blocks = cls.markdown_to_notion(lines[start_index].strip())
+        columns_block = columns_blocks[0] if columns_blocks else None
         columns_children = []
 
         next_index = cls._collect_columns(
@@ -163,7 +167,7 @@ class ColumnElement(NotionBlockElement):
         )
 
         # Add columns to the main block
-        if columns_children:
+        if columns_children and columns_block:
             columns_block["column_list"]["children"] = columns_children
 
         # Calculate positions
@@ -175,9 +179,9 @@ class ColumnElement(NotionBlockElement):
     @classmethod
     def _collect_columns(
         cls,
-        lines: List[str],
+        lines: list[str],
         start_index: int,
-        columns_children: List[Dict[str, Any]],
+        columns_children: list[dict[str, any]],
         converter_callback: Callable,
     ) -> int:
         """
@@ -237,8 +241,8 @@ class ColumnElement(NotionBlockElement):
 
     @staticmethod
     def _finalize_column(
-        column_content: List[str],
-        columns_children: List[Dict[str, Any]],
+        column_content: list[str],
+        columns_children: list[dict[str, any]],
         in_column: bool,
         converter_callback: Callable,
     ) -> None:
@@ -268,44 +272,9 @@ class ColumnElement(NotionBlockElement):
         return True
 
     @staticmethod
-    def _preprocess_column_content(lines: List[str]) -> List[str]:
-        """
-        Preprocess column content to handle special cases like first headings.
-
-        This removes any spacer markers that might have been added before the first
-        heading in a column, as each column should have its own heading context.
-
-        Args:
-            lines: The lines of content for the column
-
-        Returns:
-            Processed lines ready for conversion
-        """
-        processed_lines = []
-        found_first_heading = False
-
-        i = 0
-        while i < len(lines):
-            line = lines[i]
-
-            # Check if this is a heading line
-            if re.match(r"^(#{1,6})\s+(.+)$", line.strip()):
-                # If it's the first heading, look ahead to check for spacer
-                if (
-                    not found_first_heading
-                    and i > 0
-                    and processed_lines
-                    and processed_lines[-1] == SPACER_MARKER
-                ):
-                    # Remove spacer before first heading in column
-                    processed_lines.pop()
-
-                found_first_heading = True
-
-            processed_lines.append(line)
-            i += 1
-
-        return processed_lines
+    def _preprocess_column_content(lines: list[str]) -> list[str]:
+        """Remove all spacer markers from column content."""
+        return [line for line in lines if line.strip() != "---spacer---"]
 
     @classmethod
     def get_llm_prompt_content(cls) -> ElementPromptContent:

notionary/blocks/divider/__init__.py

@@ -0,0 +1,7 @@
+from .divider_element import DividerElement
+from .divider_markdown_node import DividerMarkdownNode
+
+__all__ = [
+    "DividerElement",
+    "DividerMarkdownNode",
+]

notionary/blocks/{divider_element.py → divider/divider_element.py}

@@ -2,7 +2,11 @@ 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,
+)
 
 
 class DividerElement(NotionBlockElement):
@@ -26,12 +30,16 @@ class DividerElement(NotionBlockElement):
         return block.get("type") == "divider"
 
     @classmethod
-    def markdown_to_notion(cls, text: str) -> Optional[Dict[str, Any]]:
+    def markdown_to_notion(cls, text: str) -> NotionBlockResult:
         """Convert markdown divider to Notion divider block."""
         if not DividerElement.match_markdown(text):
             return None
 
-        return {"type": "divider", "divider": {}}
+        empty_paragraph = {"type": "paragraph", "paragraph": {"rich_text": []}}
+
+        divider_block = {"type": "divider", "divider": {}}
+
+        return [empty_paragraph, divider_block]
 
     @classmethod
     def notion_to_markdown(cls, block: Dict[str, Any]) -> Optional[str]: