notionary 0.1.24__py3-none-any.whl → 0.1.26__py3-none-any.whl

notionary/elements/paragraph_element.py

@@ -1,17 +1,18 @@
 from typing import Dict, Any, Optional
-from typing_extensions import override
 
 from notionary.elements.notion_block_element import NotionBlockElement
-from notionary.elements.prompts.element_prompt_content import ElementPromptContent
+from notionary.elements.prompts.element_prompt_content import (
+    ElementPromptBuilder,
+    ElementPromptContent,
+)
 from notionary.elements.text_inline_formatter import TextInlineFormatter
 
 
 class ParagraphElement(NotionBlockElement):
     """Handles conversion between Markdown paragraphs and Notion paragraph blocks."""
 
-    @override
-    @staticmethod
-    def match_markdown(text: str) -> bool:
+    @classmethod
+    def match_markdown(cls, text: str) -> bool:
         """
         Check if text is a markdown paragraph.
         Paragraphs are essentially any text that isn't matched by other block elements.
@@ -19,15 +20,13 @@ class ParagraphElement(NotionBlockElement):
         """
         return True
 
-    @override
-    @staticmethod
-    def match_notion(block: Dict[str, Any]) -> bool:
+    @classmethod
+    def match_notion(cls, block: Dict[str, Any]) -> bool:
         """Check if block is a Notion paragraph."""
         return block.get("type") == "paragraph"
 
-    @override
-    @staticmethod
-    def markdown_to_notion(text: str) -> Optional[Dict[str, Any]]:
+    @classmethod
+    def markdown_to_notion(cls, text: str) -> Optional[Dict[str, Any]]:
         """Convert markdown paragraph to Notion paragraph block."""
         if not text.strip():
             return None
@@ -39,9 +38,8 @@ class ParagraphElement(NotionBlockElement):
             },
         }
 
-    @override
-    @staticmethod
-    def notion_to_markdown(block: Dict[str, Any]) -> Optional[str]:
+    @classmethod
+    def notion_to_markdown(cls, block: Dict[str, Any]) -> Optional[str]:
         """Convert Notion paragraph block to markdown paragraph."""
         if block.get("type") != "paragraph":
             return None
@@ -52,26 +50,34 @@ class ParagraphElement(NotionBlockElement):
         text = TextInlineFormatter.extract_text_with_formatting(rich_text)
         return text if text else None
 
-    @override
-    @staticmethod
-    def is_multiline() -> bool:
+    @classmethod
+    def is_multiline(cls) -> bool:
         return False
 
     @classmethod
     def get_llm_prompt_content(cls) -> ElementPromptContent:
         """
-        Returns structured LLM prompt metadata for the paragraph element.
+        Returns structured LLM prompt metadata for the paragraph element,
+        including information about supported inline formatting.
         """
-        return {
-            "description": "Creates standard paragraph blocks for regular text content.",
-            "when_to_use": (
-                "Use paragraphs for normal text content. Paragraphs are the default block type and will be used "
-                "when no other specific formatting is applied."
-            ),
-            "syntax": "Just write text normally without any special prefix",
-            "examples": [
-                "This is a simple paragraph with plain text.",
-                "This paragraph has **bold** and *italic* formatting.",
-                "You can also include [links](https://example.com) or `inline code`.",
-            ],
-        }
+        return (
+            ElementPromptBuilder()
+            .with_description(
+                "Creates standard paragraph blocks for regular text content with support for inline formatting: "
+                "**bold**, *italic*, `code`, ~~strikethrough~~, __underline__, and [links](url)."
+            )
+            .with_usage_guidelines(
+                "Use for normal text content. Paragraphs are the default block type when no specific formatting is applied. "
+                "Apply inline formatting to highlight key points or provide links to resources."
+            )
+            .with_syntax("Just write text normally without any special prefix")
+            .with_examples(
+                [
+                    "This is a simple paragraph with plain text.",
+                    "This paragraph has **bold** and *italic* formatting.",
+                    "You can include [links](https://example.com) or `inline code`.",
+                    "Advanced formatting: ~~strikethrough~~ and __underlined text__.",
+                ]
+            )
+            .build()
+        )

notionary/elements/prompts/element_prompt_content.py

@@ -1,9 +1,11 @@
-from typing import NotRequired, TypedDict, List
+from dataclasses import field, dataclass
+from typing import Optional, List, Self
 
 
-class ElementPromptContent(TypedDict):
+@dataclass
+class ElementPromptContent:
     """
-    Typed dictionary defining the standardized structure for element prompt content.
+    Dataclass defining the standardized structure for element prompt content.
     This ensures consistent formatting across all Notion block elements.
     """
 
@@ -13,12 +15,93 @@ class ElementPromptContent(TypedDict):
     syntax: str
     """The exact markdown syntax pattern used to create this element."""
 
-    examples: List[str]
-    """List of practical usage examples showing the element in context."""
-
     when_to_use: str
     """Guidelines explaining the appropriate scenarios for using this element."""
-    
-    avoid: NotRequired[str]
+
+    examples: List[str] = field(default_factory=list)
+    """List of practical usage examples showing the element in context."""
+
+    avoid: Optional[str] = None
     """Optional field listing scenarios when this element should be avoided."""
 
+    def __post_init__(self):
+        """Validates that the content meets minimum requirements."""
+        if not self.description:
+            raise ValueError("Description is required")
+        if not self.syntax:
+            raise ValueError("Syntax is required")
+        if not self.examples:
+            raise ValueError("At least one example is required")
+        if not self.when_to_use:
+            raise ValueError("Usage guidelines are required")
+
+
+class ElementPromptBuilder:
+    """
+    Builder class for creating ElementPromptContent with a fluent interface.
+    Provides better IDE support and validation for creating prompts.
+    """
+
+    def __init__(self) -> None:
+        self._description: Optional[str] = None
+        self._syntax: Optional[str] = None
+        self._examples: List[str] = []
+        self._when_to_use: Optional[str] = None
+        self._avoid: Optional[str] = None
+
+    def with_description(self, description: str) -> Self:
+        """Set the description of the element."""
+        self._description = description
+        return self
+
+    def with_syntax(self, syntax: str) -> Self:
+        """Set the syntax pattern for the element."""
+        self._syntax = syntax
+        return self
+
+    def add_example(self, example: str) -> Self:
+        """Add a usage example for the element."""
+        self._examples.append(example)
+        return self
+
+    def with_examples(self, examples: List[str]) -> Self:
+        """Set the list of usage examples for the element."""
+        self._examples = examples.copy()
+        return self
+
+    def with_usage_guidelines(self, when_to_use: str) -> Self:
+        """Set the usage guidelines for the element."""
+        self._when_to_use = when_to_use
+        return self
+
+    def with_avoidance_guidelines(self, avoid: str) -> Self:
+        """Set the scenarios when this element should be avoided."""
+        self._avoid = avoid
+        return self
+
+    def build(self) -> ElementPromptContent:
+        """
+        Build and validate the ElementPromptContent object.
+
+        Returns:
+            A valid ElementPromptContent object.
+
+        Raises:
+            ValueError: If any required field is missing.
+        """
+        if not self._description:
+            raise ValueError("Description is required")
+        if not self._syntax:
+            raise ValueError("Syntax is required")
+        if not self._examples:
+            raise ValueError("At least one example is required")
+        if not self._when_to_use:
+            raise ValueError("Usage guidelines are required")
+
+        return ElementPromptContent(
+            description=self._description,
+            syntax=self._syntax,
+            examples=self._examples,
+            when_to_use=self._when_to_use,
+            avoid=self._avoid,
+        )

notionary/elements/prompts/synthax_prompt_builder.py

@@ -13,33 +13,81 @@ class MarkdownSyntaxPromptBuilder:
     SYSTEM_PROMPT_TEMPLATE = """You are a knowledgeable assistant that helps users create content for Notion pages.
 Notion supports standard Markdown with some special extensions for creating rich content.
 
+# Understanding Notion Blocks
+Notion documents are composed of individual blocks. Each block has a specific type (paragraph, heading, list item, etc.) and format. 
+The Markdown syntax you use directly maps to these Notion blocks.
+
+## Inline Formatting
+Inline formatting can be used within most block types to style your text. You can combine multiple formatting options.
+**Syntax:** **bold**, *italic*, `code`, ~~strikethrough~~, __underline__, [text](url)
+**Examples:** 
+- This text has a **bold** word.
+- This text has an *italic* word.
+- This text has `code` formatting.
+- This text has ~~strikethrough~~ formatting.
+- This text has __underlined__ formatting.
+- This has a [hyperlink](https://example.com).
+- You can **combine *different* formatting** styles.
+
+**When to use:** Use inline formatting to highlight important words, provide emphasis, show code or paths, or add hyperlinks. This helps create visual hierarchy and improves scanability.
+
+## Spacers and Block Separation
+There are two ways to create visual separation between blocks:
+
+1. **Empty Lines**: Simply add a blank line between blocks
+   **Syntax:** Press Enter twice between blocks
+   **Example:** 
+   First paragraph.
+
+   Second paragraph after an empty line.
+
+2. **HTML Comment Spacer**: For more deliberate spacing between logical sections
+   **Syntax:** <!-- spacer -->
+   **Example:**
+   ## First Section
+   Content here.
+   <!-- spacer -->
+   ## Second Section
+   More content here.
+
+**When to use:** Use empty lines for basic separation between blocks. Use the HTML comment spacer (<!-- spacer -->) to create more obvious visual separation between major logical sections of your document.
+
 {element_docs}
 
 CRITICAL USAGE GUIDELINES:
 
 1. Do NOT start content with a level 1 heading (# Heading). In Notion, the page title is already displayed in the metadata, so starting with an H1 heading is redundant. Begin with H2 (## Heading) or lower for section headings.
 
-2. BACKTICK HANDLING - EXTREMELY IMPORTANT:
+2. INLINE FORMATTING - VERY IMPORTANT:
+   ✅ You can use inline formatting within almost any block type.
+   ✅ Combine **bold**, *italic*, `code`, and other formatting as needed.
+   ✅ Format text to create visual hierarchy and emphasize important points.
+   ❌ DO NOT overuse formatting - be strategic with formatting for best readability.
+
+3. BACKTICK HANDLING - EXTREMELY IMPORTANT:
    ❌ NEVER wrap entire content or responses in triple backticks (```).
    ❌ DO NOT use triple backticks (```) for anything except CODE BLOCKS or DIAGRAMS.
    ❌ DO NOT use triple backticks to mark or highlight regular text or examples.
    ✅ USE triple backticks ONLY for actual programming code, pseudocode, or specialized notation.
+   ✅ For inline code, use single backticks (`code`).
    ✅ When showing Markdown syntax examples, use inline code formatting with single backticks.
 
-3. Use inline formatting (bold, italic, etc.) across all content to enhance readability.
-   Proper typography is essential for creating scannable, well-structured documents.
-
-4. Notion's extensions to Markdown provide richer formatting options than standard Markdown
-   while maintaining the familiar Markdown syntax for basic elements.
+4. BLOCK SEPARATION - IMPORTANT:
+   ✅ Use empty lines between different blocks to ensure proper rendering in Notion.
+   ✅ For major logical sections, add the HTML comment spacer: <!-- spacer -->
+   ✅ This spacer creates better visual breaks between key sections of your document.
+   ⚠️ While headings can sometimes work without an empty line before the following paragraph, including empty lines between all block types ensures consistent rendering.
 
-5. Always structure content with clear headings, lists, and paragraphs to create visually appealing
-   and well-organized documents.
+5. TOGGLE BLOCKS - NOTE:
+   ✅ For toggle blocks and collapsible headings, use pipe prefixes (|) for content.
+   ✅ Each line within a toggle should start with a pipe character followed by a space.
+   ❌ Do not use the pipe character for any other blocks.
 
 6. CONTENT FORMATTING - CRITICAL:
    ❌ DO NOT include introductory phrases like "I understand that..." or "Here's the content...".
    ✅ Provide ONLY the requested content directly without any prefacing text or meta-commentary.
    ✅ Generate just the content itself, formatted according to these guidelines.
-"""
+    """
 
     @staticmethod
     def generate_element_doc(element_class: Type[NotionBlockElement]) -> str:
@@ -59,17 +107,16 @@ CRITICAL USAGE GUIDELINES:
         # Get the element content
         content = element_class.get_llm_prompt_content()
 
-        # Format the element documentation in a compact way
         doc_parts = [
             f"## {element_name}",
-            f"{content['description']}",
-            f"**Syntax:** {content['syntax']}",
-            f"**Example:** {content['examples'][0]}" if content["examples"] else "",
-            f"**When to use:** {content['when_to_use']}",
+            f"{content.description}",
+            f"**Syntax:** {content.syntax}",
+            f"**Example:** {content.examples[0]}" if content.examples else "",
+            f"**When to use:** {content.when_to_use}",
         ]
-        
-        if "avoid" in content and content["avoid"]:
-            doc_parts.append(f"**Avoid:** {content['avoid']}")
+
+        if content.avoid:
+            doc_parts.append(f"**Avoid:** {content.avoid}")
 
         return "\n".join([part for part in doc_parts if part])
 

notionary/elements/qoute_element.py

@@ -1,85 +1,78 @@
 import re
 from typing import Dict, Any, Optional, List, Tuple
 from notionary.elements.notion_block_element import NotionBlockElement
-from notionary.elements.prompts.element_prompt_content import ElementPromptContent
+from notionary.elements.prompts.element_prompt_content import (
+    ElementPromptBuilder,
+    ElementPromptContent,
+)
 
 
 class QuoteElement(NotionBlockElement):
     """Class for converting between Markdown blockquotes and Notion quote blocks."""
 
-    @staticmethod
-    def find_matches(text: str) -> List[Tuple[int, int, Dict[str, Any]]]:
+    # Regular expression pattern to match Markdown blockquote lines
+    # Matches lines that start with optional whitespace, followed by '>',
+    # then optional whitespace, and captures any text after that
+    quote_pattern = re.compile(r"^\s*>\s?(.*)", re.MULTILINE)
+
+    @classmethod
+    def find_matches(cls, text: str) -> List[Tuple[int, int, Dict[str, Any]]]:
         """
         Find all blockquote matches in the text and return their positions and blocks.
-
-        Args:
-            text: The input markdown text
-
-        Returns:
-            List of tuples (start_pos, end_pos, block)
         """
-        quote_pattern = re.compile(r"^\s*>\s?(.*)", re.MULTILINE)
         matches = []
+        quote_matches = list(QuoteElement.quote_pattern.finditer(text))
 
-        # Find all potential quote line matches
-        quote_matches = list(quote_pattern.finditer(text))
         if not quote_matches:
             return []
 
-        # Group consecutive quote lines
-        i = 0
-        while i < len(quote_matches):
-            start_match = quote_matches[i]
+        current_match_index = 0
+        while current_match_index < len(quote_matches):
+            start_match = quote_matches[current_match_index]
             start_pos = start_match.start()
 
-            # Find consecutive quote lines
-            j = i + 1
-            while j < len(quote_matches):
-                # Check if this is the next line (considering newlines)
-                if (
-                    text[quote_matches[j - 1].end() : quote_matches[j].start()].count(
-                        "\n"
-                    )
-                    == 1
-                    or
-                    # Or if it's an empty line followed by a quote line
-                    (
-                        text[
-                            quote_matches[j - 1].end() : quote_matches[j].start()
-                        ].strip()
-                        == ""
-                        and text[
-                            quote_matches[j - 1].end() : quote_matches[j].start()
-                        ].count("\n")
-                        <= 2
-                    )
-                ):
-                    j += 1
-                else:
-                    break
-
-            end_pos = quote_matches[j - 1].end()
+            next_match_index = current_match_index + 1
+            while next_match_index < len(
+                quote_matches
+            ) and QuoteElement.is_consecutive_quote(
+                text, quote_matches, next_match_index
+            ):
+                next_match_index += 1
+
+            end_pos = quote_matches[next_match_index - 1].end()
             quote_text = text[start_pos:end_pos]
 
-            # Create the block
             block = QuoteElement.markdown_to_notion(quote_text)
             if block:
                 matches.append((start_pos, end_pos, block))
 
-            i = j
+            current_match_index = next_match_index
 
         return matches
 
-    @staticmethod
-    def markdown_to_notion(text: str) -> Optional[Dict[str, Any]]:
+    @classmethod
+    def is_consecutive_quote(cls, text: str, quote_matches: List, index: int) -> bool:
+        """Checks if the current quote is part of the previous quote sequence."""
+        prev_end = quote_matches[index - 1].end()
+        curr_start = quote_matches[index].start()
+        gap_text = text[prev_end:curr_start]
+
+        if gap_text.count("\n") == 1:
+            return True
+
+        if gap_text.strip() == "" and gap_text.count("\n") <= 2:
+            return True
+
+        return False
+
+    @classmethod
+    def markdown_to_notion(cls, text: str) -> Optional[Dict[str, Any]]:
         """Convert markdown blockquote to Notion block."""
         if not text:
             return None
 
-        quote_pattern = re.compile(r"^\s*>\s?(.*)", re.MULTILINE)
-
         # Check if it's a blockquote
-        if not quote_pattern.search(text):
+        if not QuoteElement.quote_pattern.search(text):
             return None
 
         # Extract quote content
@@ -88,7 +81,7 @@ class QuoteElement(NotionBlockElement):
 
         # Extract content from each line
         for line in lines:
-            quote_match = quote_pattern.match(line)
+            quote_match = QuoteElement.quote_pattern.match(line)
             if quote_match:
                 content = quote_match.group(1)
                 quote_lines.append(content)
@@ -105,8 +98,8 @@ class QuoteElement(NotionBlockElement):
 
         return {"type": "quote", "quote": {"rich_text": rich_text, "color": "default"}}
 
-    @staticmethod
-    def notion_to_markdown(block: Dict[str, Any]) -> Optional[str]:
+    @classmethod
+    def notion_to_markdown(cls, block: Dict[str, Any]) -> Optional[str]:
         """Convert Notion quote block to markdown."""
         if block.get("type") != "quote":
             return None
@@ -126,24 +119,23 @@ class QuoteElement(NotionBlockElement):
 
         return "\n".join(formatted_lines)
 
-    @staticmethod
-    def match_markdown(text: str) -> bool:
+    @classmethod
+    def match_markdown(cls, text: str) -> bool:
         """Check if this element can handle the given markdown text."""
-        quote_pattern = re.compile(r"^\s*>\s?(.*)", re.MULTILINE)
-        return bool(quote_pattern.search(text))
+        return bool(QuoteElement.quote_pattern.search(text))
 
-    @staticmethod
-    def match_notion(block: Dict[str, Any]) -> bool:
+    @classmethod
+    def match_notion(cls, block: Dict[str, Any]) -> bool:
         """Check if this element can handle the given Notion block."""
         return block.get("type") == "quote"
 
-    @staticmethod
-    def is_multiline() -> bool:
+    @classmethod
+    def is_multiline(cls) -> bool:
         """Blockquotes can span multiple lines."""
         return True
 
-    @staticmethod
-    def _extract_text_content(rich_text: List[Dict[str, Any]]) -> str:
+    @classmethod
+    def _extract_text_content(cls, rich_text: List[Dict[str, Any]]) -> str:
         """Extract plain text content from Notion rich_text elements."""
         result = ""
         for text_obj in rich_text:
@@ -158,16 +150,22 @@ class QuoteElement(NotionBlockElement):
         """
         Returns structured LLM prompt metadata for the quote element.
         """
-        return {
-            "description": "Creates blockquotes that visually distinguish quoted text.",
-            "when_to_use": (
+        return (
+            ElementPromptBuilder()
+            .with_description(
+                "Creates blockquotes that visually distinguish quoted text."
+            )
+            .with_usage_guidelines(
                 "Use blockquotes for quoting external sources, highlighting important statements, "
                 "or creating visual emphasis for key information."
-            ),
-            "syntax": "> Quoted text",
-            "examples": [
-                "> This is a simple blockquote",
-                "> This is a multi-line quote\n> that continues on the next line",
-                "> Important note:\n> This quote spans\n> multiple lines.",
-            ],
-        }
+            )
+            .with_syntax("> Quoted text")
+            .with_examples(
+                [
+                    "> This is a simple blockquote",
+                    "> This is a multi-line quote\n> that continues on the next line",
+                    "> Important note:\n> This quote spans\n> multiple lines.",
+                ]
+            )
+            .build()
+        )

notionary/elements/registry/block_element_registry.py

@@ -33,7 +33,7 @@ class BlockElementRegistry:
             self._elements.remove(element_class)
             return True
         return False
-    
+
     def contains(self, element_class: Type[NotionBlockElement]) -> bool:
         """
         Check if the registry contains the specified element class.

notionary/elements/registry/block_element_registry_builder.py

@@ -18,13 +18,13 @@ from notionary.elements.callout_element import CalloutElement
 from notionary.elements.code_block_element import CodeBlockElement
 from notionary.elements.divider_element import DividerElement
 from notionary.elements.table_element import TableElement
-from notionary.elements.todo_lists import TodoElement
+from notionary.elements.todo_element import TodoElement
 from notionary.elements.qoute_element import QuoteElement
 from notionary.elements.image_element import ImageElement
+from notionary.elements.toggleable_heading_element import ToggleableHeadingElement
 from notionary.elements.video_element import VideoElement
 from notionary.elements.toggle_element import ToggleElement
 from notionary.elements.bookmark_element import BookmarkElement
-from notionary.elements.column_element import ColumnElement
 
 
 class BlockElementRegistryBuilder:
@@ -51,7 +51,6 @@ class BlockElementRegistryBuilder:
             .with_code()
             .with_dividers()
             .with_tables()
-            .with_columns()
             .with_bulleted_list()
             .with_numbered_list()
             .with_toggles()
@@ -64,6 +63,7 @@ class BlockElementRegistryBuilder:
             .with_audio()
             .with_mention()
             .with_paragraphs()
+            .with_toggleable_heading_element()
         ).build()
 
     def add_element(
@@ -174,12 +174,6 @@ class BlockElementRegistryBuilder:
         """
         return self.add_element(TableElement)
 
-    def with_columns(self) -> BlockElementRegistryBuilder:
-        """
-        Add support for column elements.
-        """
-        return self.add_element(ColumnElement)
-
     def with_bulleted_list(self) -> BlockElementRegistryBuilder:
         """
         Add support for bulleted list elements (unordered lists).
@@ -249,6 +243,9 @@ class BlockElementRegistryBuilder:
     def with_mention(self) -> BlockElementRegistryBuilder:
         return self.add_element(MentionElement)
 
+    def with_toggleable_heading_element(self) -> BlockElementRegistryBuilder:
+        return self.add_element(ToggleableHeadingElement)
+
     def build(self) -> BlockElementRegistry:
         """
         Build and return the configured BlockElementRegistry instance.