notionary 0.2.6__py3-none-any.whl → 0.2.8__py3-none-any.whl

notionary/database/database_discovery.py

@@ -26,29 +26,7 @@ class DatabaseDiscovery(LoggingMixin):
         self._client = client if client else NotionClient()
         self.logger.info("DatabaseDiscovery initialized")
 
-    async def discover(self, page_size: int = 100) -> List[Tuple[str, str]]:
-        """
-        Discover all accessible databases and return their titles and IDs.
-
-        Args:
-            page_size: The number of databases to fetch per request
-
-        Returns:
-            List of tuples containing (database_title, database_id)
-        """
-        databases = []
-
-        async for database in self._iter_databases(page_size):
-            db_id = database.get("id")
-            if not db_id:
-                continue
-
-            title = self._extract_database_title(database)
-            databases.append((title, db_id))
-
-        return databases
-
-    async def discover_and_print(self, page_size: int = 100) -> List[Tuple[str, str]]:
+    async def __call__(self, page_size: int = 100) -> List[Tuple[str, str]]:
         """
         Discover databases and print the results in a nicely formatted way.
 
@@ -61,7 +39,7 @@ class DatabaseDiscovery(LoggingMixin):
         Returns:
             The same list of databases as discover() for further processing
         """
-        databases = await self.discover(page_size)
+        databases = await self._discover(page_size)
 
         if not databases:
             print("\n⚠️ No databases found!")
@@ -78,6 +56,28 @@ class DatabaseDiscovery(LoggingMixin):
 
         return databases
 
+    async def _discover(self, page_size: int = 100) -> List[Tuple[str, str]]:
+        """
+        Discover all accessible databases and return their titles and IDs.
+
+        Args:
+            page_size: The number of databases to fetch per request
+
+        Returns:
+            List of tuples containing (database_title, database_id)
+        """
+        databases = []
+
+        async for database in self._iter_databases(page_size):
+            db_id = database.get("id")
+            if not db_id:
+                continue
+
+            title = self._extract_database_title(database)
+            databases.append((title, db_id))
+
+        return databases
+
     async def _iter_databases(
         self, page_size: int = 100
     ) -> AsyncGenerator[Dict[str, Any], None]:

notionary/elements/code_block_element.py

@@ -15,13 +15,17 @@ class CodeBlockElement(NotionBlockElement):
     ```language
     code content
     ```
+    Caption: optional caption text
 
     Where:
     - language is optional and specifies the programming language
     - code content is the code to be displayed
+    - Caption line is optional and must appear immediately after the closing ```
     """
 
-    PATTERN = re.compile(r"```(\w*)\n([\s\S]+?)```", re.MULTILINE)
+    PATTERN = re.compile(
+        r"```(\w*)\n([\s\S]+?)```(?:\n(?:Caption|caption):\s*(.+))?", re.MULTILINE
+    )
 
     @classmethod
     def match_markdown(cls, text: str) -> bool:
@@ -42,25 +46,18 @@ class CodeBlockElement(NotionBlockElement):
 
         language = match.group(1) or "plain text"
         content = match.group(2)
+        caption = match.group(3)
 
         if content.endswith("\n"):
             content = content[:-1]
 
-        return {
+        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,
                     }
                 ],
@@ -68,6 +65,18 @@ class CodeBlockElement(NotionBlockElement):
             },
         }
 
+        # Add caption if provided
+        if caption and caption.strip():
+            block["code"]["caption"] = [
+                {
+                    "type": "text",
+                    "text": {"content": caption.strip()},
+                    "plain_text": caption.strip(),
+                }
+            ]
+
+        return block
+
     @classmethod
     def notion_to_markdown(cls, block: Dict[str, Any]) -> Optional[str]:
         """Convert Notion code block to markdown code block."""
@@ -84,8 +93,20 @@ class CodeBlockElement(NotionBlockElement):
 
         language = code_data.get("language", "")
 
+        # 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", "")
+
         # Format as a markdown code block
-        return f"```{language}\n{content}\n```"
+        result = f"```{language}\n{content}\n```"
+
+        # Add caption if present
+        if caption_text.strip():
+            result += f"\nCaption: {caption_text}"
+
+        return result
 
     @classmethod
     def find_matches(cls, text: str) -> List[Tuple[int, int, Dict[str, Any]]]:
@@ -102,6 +123,7 @@ class CodeBlockElement(NotionBlockElement):
         for match in CodeBlockElement.PATTERN.finditer(text):
             language = match.group(1) or "plain text"
             content = match.group(2)
+            caption = match.group(3)
 
             # Remove trailing newline if present
             if content.endswith("\n"):
@@ -121,6 +143,16 @@ class CodeBlockElement(NotionBlockElement):
                 },
             }
 
+            # Add caption if provided
+            if caption and caption.strip():
+                block["code"]["caption"] = [
+                    {
+                        "type": "text",
+                        "text": {"content": caption.strip()},
+                        "plain_text": caption.strip(),
+                    }
+                ]
+
             matches.append((match.start(), match.end(), block))
 
         return matches
@@ -139,25 +171,34 @@ class CodeBlockElement(NotionBlockElement):
             .with_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."
+                "examples, or diagram syntax. Also suitable for explaining or visualizing systems with diagram languages. "
+                "Code blocks can include optional captions for better documentation."
             )
             .with_usage_guidelines(
                 "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."
+                "JSON structures, or system diagrams. Especially helpful when structure and formatting are essential. "
+                "Add captions to provide context, explanations, or titles for your code blocks."
+            )
+            .with_syntax(
+                "```language\ncode content\n```\nCaption: optional caption text\n\n"
+                "OR\n\n"
+                "```language\ncode content\n```"
             )
-            .with_syntax("```language\ncode content\n```")
             .with_examples(
                 [
-                    "```python\nprint('Hello, world!')\n```",
-                    '```json\n{"name": "Alice", "age": 30}\n```',
-                    "```mermaid\nflowchart TD\n  A --> B\n```",
+                    "```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
                 ]
             )
             .with_avoidance_guidelines(
                 "NEVER EVER wrap markdown content with ```markdown. Markdown should be written directly without code block formatting. "
                 "NEVER use ```markdown under any circumstances. "
                 "For Mermaid diagrams, use ONLY the default styling without colors, backgrounds, or custom styling attributes. "
-                "Keep Mermaid diagrams simple and minimal without any styling or color modifications."
+                "Keep Mermaid diagrams simple and minimal without any styling or color modifications. "
+                "Captions must appear immediately after the closing ``` on a new line starting with 'Caption:' - "
+                "no empty lines between the code block and the caption."
             )
             .build()
         )

notionary/elements/column_element.py

@@ -0,0 +1,353 @@
+import re
+from typing import Dict, Any, Optional, List, Tuple, Callable
+
+from notionary.elements.notion_block_element import NotionBlockElement
+from notionary.prompting.element_prompt_content import ElementPromptContent
+
+
+class ColumnElement(NotionBlockElement):
+    """
+    Handles conversion between custom Markdown column syntax and Notion column blocks.
+
+    Markdown column syntax:
+    ::: columns
+    ::: column
+    Content for first column
+    :::
+    ::: column
+    Content for second column
+    :::
+    :::
+
+    This creates a column layout in Notion with the specified content in each column.
+    """
+
+    COLUMNS_START = re.compile(r"^:::\s*columns\s*$")
+    COLUMN_START = re.compile(r"^:::\s*column\s*$")
+    BLOCK_END = re.compile(r"^:::\s*$")
+
+    _converter_callback = None
+
+    @classmethod
+    def set_converter_callback(
+        cls, callback: Callable[[str], List[Dict[str, Any]]]
+    ) -> None:
+        """
+        Setze die Callback-Funktion, die zum Konvertieren von Markdown zu Notion-Blöcken verwendet wird.
+
+        Args:
+            callback: Funktion, die Markdown-Text annimmt und eine Liste von Notion-Blöcken zurückgibt
+        """
+        cls._converter_callback = callback
+
+    @staticmethod
+    def match_markdown(text: str) -> bool:
+        """Check if text starts a columns block."""
+        return bool(ColumnElement.COLUMNS_START.match(text.strip()))
+
+    @staticmethod
+    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]]:
+        """
+        Convert markdown column syntax to Notion column blocks.
+
+        Note: This only processes the first line (columns start).
+        The full column content needs to be processed separately.
+        """
+        if not ColumnElement.COLUMNS_START.match(text.strip()):
+            return None
+
+        # Create an empty column_list block
+        # Child columns will be added by the column processor
+        return {"type": "column_list", "column_list": {"children": []}}
+
+    @staticmethod
+    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
+
+        column_children = block.get("column_list", {}).get("children", [])
+
+        # Start the columns block
+        result = ["::: columns"]
+
+        # Process each column
+        for column_block in column_children:
+            if column_block.get("type") == "column":
+                result.append("::: column")
+
+            for _ in column_block.get("column", {}).get("children", []):
+                result.append("  [Column content]")  # Placeholder
+
+                result.append(":::")
+
+        # End the columns block
+        result.append(":::")
+
+        return "\n".join(result)
+
+    @staticmethod
+    def is_multiline() -> bool:
+        """Column blocks span multiple lines."""
+        return True
+
+    @classmethod
+    def find_matches(
+        cls, text: str, converter_callback: Optional[Callable] = None
+    ) -> List[Tuple[int, int, Dict[str, Any]]]:
+        """
+        Find all column block matches in the text and return their positions and blocks.
+
+        Args:
+            text: The input markdown text
+            converter_callback: Optional callback to convert nested content
+
+        Returns:
+            List of tuples (start_pos, end_pos, block)
+        """
+        # Wenn ein Callback übergeben wurde, nutze diesen, sonst die gespeicherte Referenz
+        converter = converter_callback or cls._converter_callback
+        if not converter:
+            raise ValueError(
+                "No converter callback provided for ColumnElement. Call set_converter_callback first or provide converter_callback parameter."
+            )
+
+        matches = []
+        lines = text.split("\n")
+        i = 0
+
+        while i < len(lines):
+            # Skip non-column lines
+            if not ColumnElement.COLUMNS_START.match(lines[i].strip()):
+                i += 1
+                continue
+
+            # Process a column block and add to matches
+            column_block_info = cls._process_column_block(
+                lines=lines, start_index=i, converter_callback=converter
+            )
+            matches.append(column_block_info)
+
+            # Skip to the end of the processed column block
+            i = column_block_info[3]  # i is returned as the 4th element in the tuple
+
+        return [(start, end, block) for start, end, block, _ in matches]
+
+    @classmethod
+    def _process_column_block(
+        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.
+
+        Args:
+            lines: All lines of the text
+            start_index: Index of the column block start line
+            converter_callback: Callback function to convert markdown to notion blocks
+
+        Returns:
+            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_children = []
+
+        next_index = cls._collect_columns(
+            lines, start_index + 1, columns_children, converter_callback
+        )
+
+        # Add columns to the main block
+        if columns_children:
+            columns_block["column_list"]["children"] = columns_children
+
+        # Calculate positions
+        start_pos = sum(len(lines[j]) + 1 for j in range(columns_start))
+        end_pos = sum(len(lines[j]) + 1 for j in range(next_index))
+
+        return (start_pos, end_pos, columns_block, next_index)
+
+    @classmethod
+    def _collect_columns(
+        cls,
+        lines: List[str],
+        start_index: int,
+        columns_children: List[Dict[str, Any]],
+        converter_callback: Callable,
+    ) -> int:
+        """
+        Collect all columns within a column block structure.
+
+        Args:
+            lines: All lines of the text
+            start_index: Index to start collecting from
+            columns_children: List to append collected columns to
+            converter_callback: Callback function to convert column content
+
+        Returns:
+            Next line index after all columns have been processed
+        """
+        i = start_index
+        in_column = False
+        column_content = []
+
+        while i < len(lines):
+            current_line = lines[i].strip()
+
+            if cls.COLUMNS_START.match(current_line):
+                break
+
+            if cls.COLUMN_START.match(current_line):
+                cls._finalize_column(
+                    column_content, columns_children, in_column, converter_callback
+                )
+                column_content = []
+                in_column = True
+                i += 1
+                continue
+
+            if cls.BLOCK_END.match(current_line) and in_column:
+                cls._finalize_column(
+                    column_content, columns_children, in_column, converter_callback
+                )
+                column_content = []
+                in_column = False
+                i += 1
+                continue
+
+            if cls.BLOCK_END.match(current_line) and not in_column:
+                i += 1
+                break
+
+            if in_column:
+                column_content.append(lines[i])
+
+            i += 1
+
+        cls._finalize_column(
+            column_content, columns_children, in_column, converter_callback
+        )
+
+        return i
+
+    @staticmethod
+    def _finalize_column(
+        column_content: List[str],
+        columns_children: List[Dict[str, Any]],
+        in_column: bool,
+        converter_callback: Callable,
+    ) -> None:
+        """
+        Finalize a column by processing its content and adding it to the columns_children list.
+
+        Args:
+            column_content: Content lines of the column
+            columns_children: List to append the column block to
+            in_column: Whether we're currently in a column (if False, does nothing)
+            converter_callback: Callback function to convert column content
+        """
+        if not (in_column and column_content):
+            return
+        
+        processed_content = ColumnElement._preprocess_column_content(column_content)
+
+        column_blocks = converter_callback("\n".join(processed_content))
+
+        # Create column block
+        column_block = {"type": "column", "column": {"children": column_blocks}}
+        columns_children.append(column_block)
+
+    @classmethod
+    def is_multiline(cls) -> bool:
+        """Column blocks span multiple lines."""
+        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
+        """
+        from notionary.page.markdown_to_notion_converter import MarkdownToNotionConverter
+
+        processed_lines = []
+        found_first_heading = False
+        spacer_marker = MarkdownToNotionConverter.SPACER_MARKER
+        
+        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
+
+    @classmethod
+    def get_llm_prompt_content(cls) -> ElementPromptContent:
+        """
+        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\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"
+                ":::",
+            ],
+        }

notionary/elements/divider_element.py

@@ -57,7 +57,7 @@ class DividerElement(NotionBlockElement):
                 "Creates a horizontal divider line to visually separate sections of content."
             )
             .with_usage_guidelines(
-                "Use to create clear visual breaks between different sections without requiring headings."
+                "Use dividers only sparingly and only when the user explicitly asks for them. Dividers create strong visual breaks between content sections, so they should not be used unless specifically requested by the user."
             )
             .with_syntax("---")
             .with_examples(

notionary/elements/heading_element.py

@@ -85,7 +85,10 @@ class HeadingElement(NotionBlockElement):
             .with_usage_guidelines(
                 "Use to group content into sections and define a visual hierarchy."
             )
+            .with_avoidance_guidelines(
+                "Only H1-H3 syntax is supported. H4 and deeper heading levels are not available."
+            )
             .with_syntax("## Your Heading Text")
             .with_standard_markdown()
             .build()
-        )
+        )

notionary/elements/registry/block_registry.py

@@ -126,7 +126,7 @@ class BlockRegistry:
 
         formatter_names = [e.__name__ for e in element_classes]
         if "TextInlineFormatter" not in formatter_names:
-            element_classes = [TextInlineFormatter] + element_classes
+            element_classes = element_classes + [TextInlineFormatter]
 
         return MarkdownSyntaxPromptGenerator.generate_system_prompt(element_classes)
 

notionary/elements/registry/block_registry_builder.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 from typing import List, Type
 from collections import OrderedDict
 
+from notionary.elements.column_element import ColumnElement
 from notionary.elements.notion_block_element import NotionBlockElement
 
 from notionary.elements.audio_element import AudioElement
@@ -63,6 +64,7 @@ class BlockRegistryBuilder:
             .with_videos()
             .with_embeds()
             .with_audio()
+            .with_columns()
             .with_mention()
             .with_paragraphs()
             .with_toggleable_heading_element()
@@ -262,6 +264,12 @@ class BlockRegistryBuilder:
     def with_toggleable_heading_element(self) -> BlockRegistryBuilder:
         return self.add_element(ToggleableHeadingElement)
 
+    def with_columns(self) -> BlockRegistryBuilder:
+        """
+        Add support for column elements.
+        """
+        return self.add_element(ColumnElement)
+
     def build(self) -> BlockRegistry:
         """
         Build and return the configured BlockRegistry instance.