notionary 0.2.21__py3-none-any.whl → 0.2.22__py3-none-any.whl

notionary/blocks/syntax_prompt_builder.py

@@ -0,0 +1,137 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from textwrap import dedent
+from typing import TYPE_CHECKING, Optional
+
+
+if TYPE_CHECKING:
+    from notionary.blocks.registry.block_registry import BlockRegistry
+
+
+@dataclass
+class BlockElementMarkdownInformation:
+    """Metadata describing how a Notion block maps to Markdown syntax."""
+
+    block_type: str
+    description: str
+    syntax_examples: list[str]
+    usage_guidelines: str
+
+
+class SyntaxPromptBuilder:
+    """
+    Builds a comprehensive markdown syntax reference from a block registry.
+    Iterates over all registered elements and collects their system prompt information.
+    """
+
+    def __init__(self, block_registry: BlockRegistry):
+        self.block_registry = block_registry
+
+    def build_markdown_reference(self) -> str:
+        """
+        Build a complete markdown syntax reference string.
+        """
+        sections = [
+            self._build_header(),
+            *self._build_element_sections(),
+        ]
+
+        return "\n\n".join(sections)
+
+    def build_concise_reference(self) -> str:
+        """
+        Build a more concise reference suitable for system prompts.
+        """
+        lines = ["# Notionary Markdown Syntax"]
+
+        for element_class in self.block_registry.get_elements():
+            info: Optional[BlockElementMarkdownInformation] = (
+                element_class.get_system_prompt_information()
+            )
+            if info and info.syntax_examples:
+                # Just show the first example for conciseness
+                example = info.syntax_examples[0]
+                lines.append(f"- {info.block_type}: `{example}`")
+
+        return "\n".join(lines)
+
+    def get_blocks_with_information(self) -> list[str]:
+        """Get list of block names that provide system prompt information."""
+        blocks = []
+
+        for element_class in self.block_registry.get_elements():
+            info: Optional[BlockElementMarkdownInformation] = (
+                element_class.get_system_prompt_information()
+            )
+            if info:
+                blocks.append(info.block_type)
+
+        return blocks
+
+    def _build_header(self) -> str:
+        """Build the header section of the reference."""
+        return dedent(
+            """
+            # Notionary Markdown Syntax Reference
+
+            This comprehensive reference documents all supported markdown syntax for converting between Markdown and Notion blocks.
+            
+            Each block type includes:
+            - **Description:** What the block does
+            - **When to use:** Guidelines for appropriate usage
+            - **Syntax:** Complete syntax examples with variations
+        """
+        ).strip()
+
+    def _build_element_sections(self) -> list[str]:
+        """Build sections for all registered elements."""
+        sections = []
+
+        for element_class in self.block_registry.get_elements():
+            info = element_class.get_system_prompt_information()
+            if info:
+                sections.append(self._build_element_section(info))
+
+        return sections
+
+    def _build_element_section(self, info: BlockElementMarkdownInformation) -> str:
+        """Build a well-structured section for a single block element."""
+        section_parts = [
+            f"## {info.block_type}",
+            "",
+            f"**Description:** {info.description}",
+            "",
+        ]
+
+        if info.usage_guidelines:
+            section_parts.extend(["**When to use:**", info.usage_guidelines, ""])
+
+        if info.syntax_examples:
+            section_parts.extend(
+                [
+                    "**Syntax:**",
+                    "",
+                    *self._format_syntax_examples(info.syntax_examples),
+                    "",
+                ]
+            )
+
+        return "\n".join(section_parts).rstrip()
+
+    def _format_syntax_examples(self, examples: list[str]) -> list[str]:
+        """Format syntax examples with proper markdown and clear structure."""
+        formatted = []
+
+        for i, example in enumerate(examples, 1):
+            if len(examples) > 1:
+                formatted.append(f"**Example {i}:**")
+
+            if "\n" in example:
+                # Multi-line example - use code block
+                formatted.extend(["```", example, "```", ""])
+            else:
+                # Single line - use inline code with description
+                formatted.extend([f"`{example}`", ""])
+
+        return formatted

notionary/blocks/table/table_element.py

@@ -4,9 +4,16 @@ import re
 from typing import Optional
 
 from notionary.blocks.base_block_element import BaseBlockElement
+from notionary.blocks.syntax_prompt_builder import BlockElementMarkdownInformation
 from notionary.blocks.models import Block, BlockCreateResult
+from notionary.blocks.rich_text.rich_text_models import RichTextObject
 from notionary.blocks.rich_text.text_inline_formatter import TextInlineFormatter
-from notionary.blocks.table.table_models import CreateTableBlock, TableBlock
+from notionary.blocks.table.table_models import (
+    CreateTableBlock,
+    TableBlock,
+    CreateTableRowBlock,
+    TableRowBlock,
+)
 from notionary.blocks.types import BlockType
 
 
@@ -17,12 +24,11 @@ class TableElement(BaseBlockElement):
 
     Markdown table syntax:
     | Header 1 | Header 2 | Header 3 |
-    [table rows as child lines]
+    | -------- | -------- | -------- |
+    | Cell 1   | Cell 2   | Cell 3   |
     """
 
-    # Pattern für Table-Zeilen (jede Zeile die mit | startet und endet)
     ROW_PATTERN = re.compile(r"^\s*\|(.+)\|\s*$")
-    # Pattern für Separator-Zeilen
     SEPARATOR_PATTERN = re.compile(r"^\s*\|([\s\-:|]+)\|\s*$")
 
     @classmethod
@@ -31,7 +37,7 @@ class TableElement(BaseBlockElement):
         return block.type == BlockType.TABLE and block.table
 
     @classmethod
-    def markdown_to_notion(cls, text: str) -> BlockCreateResult:
+    async def markdown_to_notion(cls, text: str) -> BlockCreateResult:
         """Convert opening table row to Notion table block."""
         if not cls.ROW_PATTERN.match(text.strip()):
             return None
@@ -40,7 +46,6 @@ class TableElement(BaseBlockElement):
         header_cells = cls._parse_table_row(text)
         col_count = len(header_cells)
 
-        # Create empty TableBlock - content will be added by stack processor
         table_block = TableBlock(
             table_width=col_count,
             has_column_header=True,
@@ -51,7 +56,91 @@ class TableElement(BaseBlockElement):
         return CreateTableBlock(table=table_block)
 
     @classmethod
-    def notion_to_markdown(cls, block: Block) -> Optional[str]:
+    async def create_from_markdown_table(
+        cls, table_lines: list[str]
+    ) -> BlockCreateResult:
+        """
+        Create a complete table block from markdown table lines.
+        """
+        if not table_lines:
+            return None
+
+        first_row = None
+        for line in table_lines:
+            line = line.strip()
+            if line and cls.ROW_PATTERN.match(line):
+                first_row = line
+                break
+
+        if not first_row:
+            return None
+
+        # Parse header row to determine column count
+        header_cells = cls._parse_table_row(first_row)
+        col_count = len(header_cells)
+
+        # Process all table lines
+        table_rows, separator_found = await cls._process_table_lines(table_lines)
+
+        # Create complete TableBlock
+        table_block = TableBlock(
+            table_width=col_count,
+            has_column_header=separator_found,
+            has_row_header=False,
+            children=table_rows,
+        )
+
+        return CreateTableBlock(table=table_block)
+
+    @classmethod
+    async def _process_table_lines(
+        cls, table_lines: list[str]
+    ) -> tuple[list[CreateTableRowBlock], bool]:
+        """Process all table lines and return rows and separator status."""
+        table_rows = []
+        separator_found = False
+
+        for line in table_lines:
+            line = line.strip()
+            if not line:
+                continue
+
+            if cls._is_separator_line(line):
+                separator_found = True
+                continue
+
+            if cls.ROW_PATTERN.match(line):
+                table_row = await cls._create_table_row_from_line(line)
+                table_rows.append(table_row)
+
+        return table_rows, separator_found
+
+    @classmethod
+    def _is_separator_line(cls, line: str) -> bool:
+        """Check if line is a table separator (|---|---|)."""
+        return cls.SEPARATOR_PATTERN.match(line) is not None
+
+    @classmethod
+    async def _create_table_row_from_line(cls, line: str) -> CreateTableRowBlock:
+        """Create a table row block from a markdown line."""
+        cells = cls._parse_table_row(line)
+        rich_text_cells = []
+        for cell in cells:
+            rich_text_cell = await cls._convert_cell_to_rich_text(cell)
+            rich_text_cells.append(rich_text_cell)
+        table_row = TableRowBlock(cells=rich_text_cells)
+        return CreateTableRowBlock(table_row=table_row)
+
+    @classmethod
+    async def _convert_cell_to_rich_text(cls, cell: str) -> list[RichTextObject]:
+        """Convert cell text to rich text objects."""
+        rich_text = await TextInlineFormatter.parse_inline_formatting(cell)
+        if not rich_text:
+            rich_text = [RichTextObject.from_plain_text(cell)]
+        return rich_text
+
+    @classmethod
+    async def notion_to_markdown(cls, block: Block) -> Optional[str]:
         """Convert Notion table block to markdown table."""
         if block.type != BlockType.TABLE:
             return None
@@ -80,7 +169,7 @@ class TableElement(BaseBlockElement):
         header_processed = False
 
         for child in children:
-            if child.type != "table_row":
+            if child.type != BlockType.TABLE_ROW:
                 continue
 
             if not child.table_row:
@@ -91,7 +180,7 @@ class TableElement(BaseBlockElement):
 
             row_cells = []
             for cell in cells:
-                cell_text = TextInlineFormatter.extract_text_with_formatting(cell)
+                cell_text = await TextInlineFormatter.extract_text_with_formatting(cell)
                 row_cells.append(cell_text or "")
 
             row = "| " + " | ".join(row_cells) + " |"
@@ -122,3 +211,15 @@ class TableElement(BaseBlockElement):
     def is_table_row(cls, line: str) -> bool:
         """Check if a line is a valid table row."""
         return bool(cls.ROW_PATTERN.match(line.strip()))
+
+    @classmethod
+    def get_system_prompt_information(cls) -> Optional[BlockElementMarkdownInformation]:
+        """Get system prompt information for table blocks."""
+        return BlockElementMarkdownInformation(
+            block_type=cls.__name__,
+            description="Table blocks create structured data in rows and columns with headers",
+            syntax_examples=[
+                "| Name | Age | City |\n| -------- | -------- | -------- |\n| Alice | 25 | Berlin |\n| Bob | 30 | Munich |"
+            ],
+            usage_guidelines="Use for structured data presentation. First row is header, second row is separator with dashes, following rows are data. Cells are separated by | characters.",
+        )

notionary/blocks/table_of_contents/table_of_contents_element.py

@@ -4,6 +4,7 @@ import re
 from typing import Optional
 
 from notionary.blocks.base_block_element import BaseBlockElement
+from notionary.blocks.syntax_prompt_builder import BlockElementMarkdownInformation
 from notionary.blocks.models import Block, BlockCreateResult
 from notionary.blocks.table_of_contents.table_of_contents_models import (
     CreateTableOfContentsBlock,
@@ -29,7 +30,7 @@ class TableOfContentsElement(BaseBlockElement):
         return block.type == BlockType.TABLE_OF_CONTENTS and block.table_of_contents
 
     @classmethod
-    def markdown_to_notion(cls, text: str) -> BlockCreateResult:
+    async def markdown_to_notion(cls, text: str) -> BlockCreateResult:
         if not (input_match := cls.PATTERN.match(text.strip())):
             return None
 
@@ -39,7 +40,7 @@ class TableOfContentsElement(BaseBlockElement):
         )
 
     @classmethod
-    def notion_to_markdown(cls, block: Block) -> Optional[str]:
+    async def notion_to_markdown(cls, block: Block) -> Optional[str]:
         # Fix: Use 'or' instead of 'and'
         if block.type != BlockType.TABLE_OF_CONTENTS or not block.table_of_contents:
             return None
@@ -49,3 +50,19 @@ class TableOfContentsElement(BaseBlockElement):
         if color == "default":
             return "[toc]"
         return f"[toc]({color})"
+
+    @classmethod
+    @classmethod
+    def get_system_prompt_information(cls) -> Optional[BlockElementMarkdownInformation]:
+        """Get system prompt information for table of contents blocks."""
+        return BlockElementMarkdownInformation(
+            block_type=cls.__name__,
+            description="Table of contents blocks automatically generate navigation for page headings",
+            syntax_examples=[
+                "[toc]",
+                "[toc](blue)",
+                "[toc](blue_background)",
+                "[toc](gray_background)",
+            ],
+            usage_guidelines="Use to automatically generate a clickable table of contents from page headings. Optional color parameter changes the appearance. Default color is gray.",
+        )

notionary/blocks/todo/todo_element.py

@@ -4,6 +4,7 @@ import re
 from typing import TYPE_CHECKING, Optional
 
 from notionary.blocks.base_block_element import BaseBlockElement
+from notionary.blocks.syntax_prompt_builder import BlockElementMarkdownInformation
 from notionary.blocks.models import Block, BlockCreateResult, BlockType
 from notionary.blocks.rich_text.text_inline_formatter import TextInlineFormatter
 from notionary.blocks.todo.todo_models import CreateToDoBlock, ToDoBlock
@@ -28,7 +29,7 @@ class TodoElement(BaseBlockElement):
         return block.type == BlockType.TO_DO and block.to_do
 
     @classmethod
-    def markdown_to_notion(cls, text: str) -> BlockCreateResult:
+    async def markdown_to_notion(cls, text: str) -> BlockCreateResult:
         """Convert markdown todo or done item to Notion to_do block."""
         m_done = cls.DONE_PATTERN.match(text)
         m_todo = None if m_done else cls.PATTERN.match(text)
@@ -43,7 +44,7 @@ class TodoElement(BaseBlockElement):
             return None
 
         # build rich text
-        rich = TextInlineFormatter.parse_inline_formatting(content)
+        rich = await TextInlineFormatter.parse_inline_formatting(content)
 
         todo_content = ToDoBlock(
             rich_text=rich,
@@ -53,12 +54,28 @@ class TodoElement(BaseBlockElement):
         return CreateToDoBlock(to_do=todo_content)
 
     @classmethod
-    def notion_to_markdown(cls, block: Block) -> Optional[str]:
+    async def notion_to_markdown(cls, block: Block) -> Optional[str]:
         """Convert Notion to_do block to markdown todo item."""
         if block.type != BlockType.TO_DO or not block.to_do:
             return None
 
         td = block.to_do
-        content = TextInlineFormatter.extract_text_with_formatting(td.rich_text)
+        content = await TextInlineFormatter.extract_text_with_formatting(td.rich_text)
         checkbox = "[x]" if td.checked else "[ ]"
         return f"- {checkbox} {content}"
+
+    @classmethod
+    def get_system_prompt_information(cls) -> Optional[BlockElementMarkdownInformation]:
+        """Get system prompt information for todo blocks."""
+        return BlockElementMarkdownInformation(
+            block_type=cls.__name__,
+            description="Todo blocks create interactive checkboxes for task management",
+            syntax_examples=[
+                "- [ ] Unchecked todo item",
+                "- [x] Checked todo item",
+                "* [ ] Todo with asterisk",
+                "+ [ ] Todo with plus sign",
+                "- [x] Completed task",
+            ],
+            usage_guidelines="Use for task lists and checkboxes. [ ] for unchecked, [x] for checked items. Supports -, *, or + as bullet markers. Interactive in Notion interface.",
+        )

notionary/blocks/toggle/toggle_element.py

@@ -4,6 +4,7 @@ import re
 from typing import Optional
 
 from notionary.blocks.base_block_element import BaseBlockElement
+from notionary.blocks.syntax_prompt_builder import BlockElementMarkdownInformation
 from notionary.blocks.models import Block, BlockCreateResult, BlockType
 from notionary.blocks.rich_text.rich_text_models import RichTextObject
 from notionary.blocks.rich_text.text_inline_formatter import TextInlineFormatter
@@ -27,7 +28,7 @@ class ToggleElement(BaseBlockElement):
         return block.type == BlockType.TOGGLE
 
     @classmethod
-    def markdown_to_notion(cls, text: str) -> BlockCreateResult:
+    async def markdown_to_notion(cls, text: str) -> BlockCreateResult:
         """
         Convert markdown toggle line to Notion ToggleBlock.
         Children are automatically handled by the StackBasedMarkdownConverter.
@@ -36,7 +37,7 @@ class ToggleElement(BaseBlockElement):
             return None
 
         title = match.group(1).strip()
-        rich_text = TextInlineFormatter.parse_inline_formatting(title)
+        rich_text = await TextInlineFormatter.parse_inline_formatting(title)
 
         # Create toggle block with empty children - they will be populated automatically
         toggle_content = ToggleBlock(
@@ -46,7 +47,7 @@ class ToggleElement(BaseBlockElement):
         return CreateToggleBlock(toggle=toggle_content)
 
     @classmethod
-    def notion_to_markdown(cls, block: Block) -> Optional[str]:
+    async def notion_to_markdown(cls, block: Block) -> Optional[str]:
         """
         Converts a Notion toggle block into markdown using the ultra-simplified +++ syntax.
         """
@@ -94,3 +95,18 @@ class ToggleElement(BaseBlockElement):
                 elif "plain_text" in text_obj:
                     result += text_obj.get("plain_text", "")
         return result
+
+    @classmethod
+    @classmethod
+    def get_system_prompt_information(cls) -> Optional[BlockElementMarkdownInformation]:
+        """Get system prompt information for toggle blocks."""
+        return BlockElementMarkdownInformation(
+            block_type=cls.__name__,
+            description="Toggle blocks create collapsible sections with expandable content",
+            syntax_examples=[
+                "+++Title\nContent goes here\n+++",
+                "+++Details\nMore information\nAdditional content\n+++",
+                "+++FAQ\nFrequently asked questions\n+++",
+            ],
+            usage_guidelines="Use for collapsible content sections. Start with +++Title, add content, end with +++. Great for FAQs, details, or organizing long content.",
+        )

notionary/blocks/toggle/toggle_markdown_node.py

@@ -32,7 +32,7 @@ class ToggleMarkdownNode(MarkdownNode):
         return cls(title=params.title, children=params.children)
 
     def to_markdown(self) -> str:
-        result = f"+++ {self.title}"
+        result = f"+++{self.title}"
 
         if not self.children:
             result += "\n+++"

notionary/blocks/toggleable_heading/toggleable_heading_element.py

@@ -10,6 +10,7 @@ from notionary.blocks.heading.heading_models import (
     CreateHeading3Block,
     HeadingBlock,
 )
+from notionary.blocks.syntax_prompt_builder import BlockElementMarkdownInformation
 from notionary.blocks.models import Block, BlockCreateResult, BlockType
 from notionary.blocks.rich_text.text_inline_formatter import TextInlineFormatter
 
@@ -42,7 +43,7 @@ class ToggleableHeadingElement(BaseBlockElement):
             return True
 
     @classmethod
-    def markdown_to_notion(cls, text: str) -> BlockCreateResult:
+    async def markdown_to_notion(cls, text: str) -> BlockCreateResult:
         """
         Convert markdown collapsible heading to a toggleable Notion HeadingBlock.
         Children are automatically handled by the StackBasedMarkdownConverter.
@@ -56,7 +57,7 @@ class ToggleableHeadingElement(BaseBlockElement):
         if level < 1 or level > 3 or not content:
             return None
 
-        rich_text = TextInlineFormatter.parse_inline_formatting(content)
+        rich_text = await TextInlineFormatter.parse_inline_formatting(content)
 
         heading_content = HeadingBlock(
             rich_text=rich_text, color="default", is_toggleable=True, children=[]
@@ -70,7 +71,7 @@ class ToggleableHeadingElement(BaseBlockElement):
             return CreateHeading3Block(heading_3=heading_content)
 
     @staticmethod
-    def notion_to_markdown(block: Block) -> Optional[str]:
+    async def notion_to_markdown(block: Block) -> Optional[str]:
         """Convert Notion toggleable heading block to markdown collapsible heading."""
         # Only handle heading blocks via BlockType enum
         if block.type not in (
@@ -92,9 +93,23 @@ class ToggleableHeadingElement(BaseBlockElement):
         if not isinstance(heading_content, HeadingBlock):
             return None
 
-        text = TextInlineFormatter.extract_text_with_formatting(
+        text = await TextInlineFormatter.extract_text_with_formatting(
             heading_content.rich_text
         )
         prefix = "#" * level
 
         return f'+++{prefix} {text or ""}'
+
+    @classmethod
+    def get_system_prompt_information(cls) -> Optional[BlockElementMarkdownInformation]:
+        """Get system prompt information for toggleable heading blocks."""
+        return BlockElementMarkdownInformation(
+            block_type=cls.__name__,
+            description="Toggleable heading blocks create collapsible sections with heading-style titles",
+            syntax_examples=[
+                "+++# Main Section\nContent goes here\n+++",
+                "+++## Subsection\nSubsection content\n+++",
+                "+++### Details\nDetailed information\n+++",
+            ],
+            usage_guidelines="Use for collapsible sections with heading structure. Combines heading levels (1-3) with toggle functionality. Great for organizing hierarchical expandable content.",
+        )

notionary/blocks/types.py

@@ -2,6 +2,12 @@ from __future__ import annotations
 
 from enum import Enum
 
+from typing import Protocol, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from notionary.blocks.models import BlockCreateRequest
+    from notionary.blocks.rich_text.rich_text_models import RichTextObject
+
 
 class BlockColor(str, Enum):
     BLUE = "blue"
@@ -59,3 +65,66 @@ class BlockType(str, Enum):
     UNSUPPORTED = "unsupported"
     VIDEO = "video"
     AUDIO = "audio"
+
+
+class MarkdownBlockType(str, Enum):
+    """
+    Extended block types for the MarkdownBuilder.
+    Includes all BlockType values and adds user-friendly aliases
+    for blocks with no direct Notion API counterpart.
+    """
+
+    # All BlockType values
+    BOOKMARK = "bookmark"
+    BREADCRUMB = "breadcrumb"
+    BULLETED_LIST_ITEM = "bulleted_list_item"
+    CALLOUT = "callout"
+    CHILD_DATABASE = "child_database"
+    CHILD_PAGE = "child_page"
+    COLUMN = "column"
+    COLUMN_LIST = "column_list"
+    CODE = "code"
+    DIVIDER = "divider"
+    EMBED = "embed"
+    EQUATION = "equation"
+    FILE = "file"
+    HEADING_1 = "heading_1"
+    HEADING_2 = "heading_2"
+    HEADING_3 = "heading_3"
+    IMAGE = "image"
+    LINK_PREVIEW = "link_preview"
+    LINK_TO_PAGE = "link_to_page"
+    NUMBERED_LIST_ITEM = "numbered_list_item"
+    PARAGRAPH = "paragraph"
+    PDF = "pdf"
+    QUOTE = "quote"
+    SYNCED_BLOCK = "synced_block"
+    TABLE = "table"
+    TABLE_OF_CONTENTS = "table_of_contents"
+    TABLE_ROW = "table_row"
+    TO_DO = "to_do"
+    TOGGLE = "toggle"
+    UNSUPPORTED = "unsupported"
+    VIDEO = "video"
+    AUDIO = "audio"
+
+    # Markdown-specific aliases
+    HEADING = "heading"
+    BULLETED_LIST = "bulleted_list"
+    NUMBERED_LIST = "numbered_list"
+    TODO = "todo"
+    TOGGLEABLE_HEADING = "toggleable_heading"
+    COLUMNS = "columns"
+    SPACE = "space"
+
+
+class HasRichText(Protocol):
+    """Protocol for objects that have a rich_text attribute."""
+
+    rich_text: list[RichTextObject]
+
+
+class HasChildren(Protocol):
+    """Protocol for objects that have children blocks."""
+
+    children: list[BlockCreateRequest]