notionary 0.1.25__py3-none-any.whl → 0.1.27__py3-none-any.whl

notionary/elements/embed_element.py

@@ -1,7 +1,10 @@
 import re
 from typing import Dict, Any, Optional, List
 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 EmbedElement(NotionBlockElement):
@@ -20,19 +23,19 @@ class EmbedElement(NotionBlockElement):
         r"^<embed(?:\:(.*?))?>(?:\s*)" + r'\((https?://[^\s"]+)' + r"\)$"
     )
 
-    @staticmethod
-    def match_markdown(text: str) -> bool:
+    @classmethod
+    def match_markdown(cls, text: str) -> bool:
         """Check if text is a markdown embed."""
         text = text.strip()
         return text.startswith("<embed") and bool(EmbedElement.PATTERN.match(text))
 
-    @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 embed."""
         return block.get("type") == "embed"
 
-    @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 embed to Notion embed block."""
         embed_match = EmbedElement.PATTERN.match(text.strip())
         if not embed_match:
@@ -58,8 +61,8 @@ class EmbedElement(NotionBlockElement):
 
         return embed_block
 
-    @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 embed block to markdown embed."""
         if block.get("type") != "embed":
             return None
@@ -78,16 +81,16 @@ class EmbedElement(NotionBlockElement):
 
         if caption:
             return f"<embed:{caption}>({url})"
-        else:
-            return f"<embed>({url})"
 
-    @staticmethod
-    def is_multiline() -> bool:
+        return f"<embed>({url})"
+
+    @classmethod
+    def is_multiline(cls) -> bool:
         """Embeds are single-line elements."""
         return False
 
-    @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:
@@ -102,18 +105,24 @@ class EmbedElement(NotionBlockElement):
         """
         Returns structured LLM prompt metadata for the embed element.
         """
-        return {
-            "description": "Embeds external content from websites, PDFs, Google Maps, and other sources directly in your document.",
-            "when_to_use": (
+        return (
+            ElementPromptBuilder()
+            .with_description(
+                "Embeds external content from websites, PDFs, Google Maps, and other sources directly in your document."
+            )
+            .with_usage_guidelines(
                 "Use embeds when you want to include external content that isn't just a video or image. "
                 "Embeds are great for interactive content, reference materials, or live data sources."
-            ),
-            "syntax": "<embed:Caption>(https://example.com)",
-            "examples": [
-                "<embed:Course materials>(https://drive.google.com/file/d/123456/view)",
-                "<embed:Our office location>(https://www.google.com/maps?q=San+Francisco)",
-                "<embed:Latest announcement>(https://twitter.com/NotionHQ/status/1234567890)",
-                "<embed:Project documentation>(https://github.com/username/repo)",
-                "<embed>(https://example.com/important-reference.pdf)",
-            ],
-        }
+            )
+            .with_syntax("<embed:Caption>(https://example.com)")
+            .with_examples(
+                [
+                    "<embed:Course materials>(https://drive.google.com/file/d/123456/view)",
+                    "<embed:Our office location>(https://www.google.com/maps?q=San+Francisco)",
+                    "<embed:Latest announcement>(https://twitter.com/NotionHQ/status/1234567890)",
+                    "<embed:Project documentation>(https://github.com/username/repo)",
+                    "<embed>(https://example.com/important-reference.pdf)",
+                ]
+            )
+            .build()
+        )

notionary/elements/heading_element.py

@@ -2,34 +2,40 @@ import re
 from typing import Dict, Any, Optional
 
 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 HeadingElement(NotionBlockElement):
     """Handles conversion between Markdown headings and Notion heading blocks."""
 
-    PATTERN = re.compile(r"^(#{1,6})\s(.+)$")
+    PATTERN = re.compile(r"^(#{1,3})\s(.+)$")
 
-    @staticmethod
-    def match_markdown(text: str) -> bool:
+    @classmethod
+    def match_markdown(cls, text: str) -> bool:
         """Check if text is a markdown heading."""
         return bool(HeadingElement.PATTERN.match(text))
 
-    @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 heading."""
         block_type: str = block.get("type", "")
-        return block_type.startswith("heading_") and block_type[-1] in "123456"
+        return block_type.startswith("heading_") and block_type[-1] in "123"
 
-    @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 heading to Notion heading block."""
         header_match = HeadingElement.PATTERN.match(text)
         if not header_match:
             return None
 
         level = len(header_match.group(1))
+        if not 1 <= level <= 3:
+            return None
+
         content = header_match.group(2)
 
         return {
@@ -39,8 +45,8 @@ class HeadingElement(NotionBlockElement):
             },
         }
 
-    @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 heading block to markdown heading."""
         block_type = block.get("type", "")
 
@@ -49,7 +55,8 @@ class HeadingElement(NotionBlockElement):
 
         try:
             level = int(block_type[-1])
-            if not 1 <= level <= 6:
+            # Only allow levels 1-3
+            if not 1 <= level <= 3:
                 return None
         except ValueError:
             return None
@@ -61,8 +68,8 @@ class HeadingElement(NotionBlockElement):
         prefix = "#" * level
         return f"{prefix} {text or ''}"
 
-    @staticmethod
-    def is_multiline() -> bool:
+    @classmethod
+    def is_multiline(cls) -> bool:
         return False
 
     @classmethod
@@ -70,13 +77,21 @@ class HeadingElement(NotionBlockElement):
         """
         Returns structured LLM prompt metadata for the heading element.
         """
-        return {
-            "description": "Use Markdown headings (#, ##, ###, etc.) to structure content hierarchically.",
-            "when_to_use": "Use to group content into sections and define a visual hierarchy.",
-            "syntax": "## Your Heading Text",
-            "examples": [
-                "# Main Title",
-                "## Section Title",
-                "### Subsection Title",
-            ],
-        }
+        return (
+            ElementPromptBuilder()
+            .with_description(
+                "Use Markdown headings (#, ##, ###) to structure content hierarchically."
+            )
+            .with_usage_guidelines(
+                "Use to group content into sections and define a visual hierarchy."
+            )
+            .with_syntax("## Your Heading Text")
+            .with_examples(
+                [
+                    "# Main Title",
+                    "## Section Title",
+                    "### Subsection Title",
+                ]
+            )
+            .build()
+        )

notionary/elements/image_element.py

@@ -1,7 +1,10 @@
 import re
 from typing import Dict, Any, Optional, List
 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 ImageElement(NotionBlockElement):
@@ -22,20 +25,20 @@ class ImageElement(NotionBlockElement):
         + r"\)$"  # closing parenthesis
     )
 
-    @staticmethod
-    def match_markdown(text: str) -> bool:
+    @classmethod
+    def match_markdown(cls, text: str) -> bool:
         """Check if text is a markdown image."""
         return text.strip().startswith("![") and bool(
             ImageElement.PATTERN.match(text.strip())
         )
 
-    @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 image."""
         return block.get("type") == "image"
 
-    @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 image to Notion image block."""
         image_match = ImageElement.PATTERN.match(text.strip())
         if not image_match:
@@ -61,8 +64,8 @@ class ImageElement(NotionBlockElement):
 
         return image_block
 
-    @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 image block to markdown image."""
         if block.get("type") != "image":
             return None
@@ -88,8 +91,8 @@ class ImageElement(NotionBlockElement):
 
         return f"![{caption}]({url})"
 
-    @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:
@@ -99,8 +102,8 @@ class ImageElement(NotionBlockElement):
                 result += text_obj.get("plain_text", "")
         return result
 
-    @staticmethod
-    def is_multiline() -> bool:
+    @classmethod
+    def is_multiline(cls) -> bool:
         return False
 
     @classmethod
@@ -108,17 +111,23 @@ class ImageElement(NotionBlockElement):
         """
         Returns structured LLM prompt metadata for the image element.
         """
-        return {
-            "description": "Embeds an image from an external URL into your document.",
-            "when_to_use": (
+        return (
+            ElementPromptBuilder()
+            .with_description(
+                "Embeds an image from an external URL into your document."
+            )
+            .with_usage_guidelines(
                 "Use images to include visual content such as diagrams, screenshots, charts, photos, or illustrations "
                 "that enhance your document. Images can make complex information easier to understand, create visual interest, "
                 "or provide evidence for your points."
-            ),
-            "syntax": "![Caption](https://example.com/image.jpg)",
-            "examples": [
-                "![Data visualization showing monthly trends](https://example.com/chart.png)",
-                "![](https://example.com/screenshot.jpg)",
-                '![Company logo](https://company.com/logo.png "Company Inc. logo")',
-            ],
-        }
+            )
+            .with_syntax("![Caption](https://example.com/image.jpg)")
+            .with_examples(
+                [
+                    "![Data visualization showing monthly trends](https://example.com/chart.png)",
+                    "![](https://example.com/screenshot.jpg)",
+                    '![Company logo](https://company.com/logo.png "Company Inc. logo")',
+                ]
+            )
+            .build()
+        )

notionary/elements/mention_element.py

@@ -3,7 +3,10 @@ from typing import Dict, Any, Optional, List
 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,
+)
 
 
 class MentionElement(NotionBlockElement):
@@ -46,16 +49,16 @@ class MentionElement(NotionBlockElement):
         },
     }
 
-    @staticmethod
-    def match_markdown(text: str) -> bool:
+    @classmethod
+    def match_markdown(cls, text: str) -> bool:
         """Check if text contains a markdown mention."""
         for mention_type in MentionElement.MENTION_TYPES.values():
             if re.search(mention_type["pattern"], text):
                 return True
         return False
 
-    @staticmethod
-    def match_notion(block: Dict[str, Any]) -> bool:
+    @classmethod
+    def match_notion(cls, block: Dict[str, Any]) -> bool:
         """Check if block contains a mention."""
         supported_block_types = [
             "paragraph",
@@ -74,8 +77,8 @@ class MentionElement(NotionBlockElement):
 
         return any(text_item.get("type") == "mention" for text_item in rich_text)
 
-    @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 text with mentions to a Notion paragraph block."""
         if not MentionElement.match_markdown(text):
             return None
@@ -87,8 +90,8 @@ class MentionElement(NotionBlockElement):
             "paragraph": {"rich_text": rich_text, "color": "default"},
         }
 
-    @staticmethod
-    def _process_markdown_with_mentions(text: str) -> List[Dict[str, Any]]:
+    @classmethod
+    def _process_markdown_with_mentions(cls, text: str) -> List[Dict[str, Any]]:
         """Convert markdown mentions to Notion rich_text format."""
         mentions = []
 
@@ -136,8 +139,8 @@ class MentionElement(NotionBlockElement):
 
         return rich_text
 
-    @staticmethod
-    def _create_text_item(content: str) -> Dict[str, Any]:
+    @classmethod
+    def _create_text_item(cls, content: str) -> Dict[str, Any]:
         """Create a text item with default annotations."""
         text_item = {
             "type": "text",
@@ -147,8 +150,8 @@ class MentionElement(NotionBlockElement):
         }
         return text_item
 
-    @staticmethod
-    def _default_annotations() -> Dict[str, Any]:
+    @classmethod
+    def _default_annotations(cls) -> Dict[str, Any]:
         """Return default annotations for rich text."""
         return {
             "bold": False,
@@ -159,8 +162,8 @@ class MentionElement(NotionBlockElement):
             "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]:
         """Extract mentions from Notion block and convert to markdown format."""
         block_type = block.get("type")
         if not block_type or block_type not in block:
@@ -176,8 +179,8 @@ class MentionElement(NotionBlockElement):
 
         return None
 
-    @staticmethod
-    def _process_rich_text_with_mentions(rich_text: List[Dict[str, Any]]) -> str:
+    @classmethod
+    def _process_rich_text_with_mentions(cls, rich_text: List[Dict[str, Any]]) -> str:
         """Convert rich text with mentions to markdown string."""
         result = []
 
@@ -197,8 +200,8 @@ class MentionElement(NotionBlockElement):
 
         return "".join(result)
 
-    @staticmethod
-    def is_multiline() -> bool:
+    @classmethod
+    def is_multiline(cls) -> bool:
         return False
 
     @classmethod
@@ -206,13 +209,21 @@ class MentionElement(NotionBlockElement):
         """
         Returns structured LLM prompt metadata for the mention element.
         """
-        return {
-            "description": "References to Notion pages, databases, or dates within text content.",
-            "when_to_use": "When you want to link to other Notion content within your text.",
-            "syntax": "@[page-id]",
-            "examples": [
-                "Check the meeting notes at @[1a6389d5-7bd3-80c5-9a87-e90b034989d0]",
-                "Deadline is @date[2023-12-31]",
-                "Use the structure in @db[1a6389d5-7bd3-80e9-b199-000cfb3fa0b3]",
-            ],
-        }
+        return (
+            ElementPromptBuilder()
+            .with_description(
+                "References to Notion pages, databases, or dates within text content."
+            )
+            .with_usage_guidelines(
+                "When you want to link to other Notion content within your text."
+            )
+            .with_syntax("@[page-id]")
+            .with_examples(
+                [
+                    "Check the meeting notes at @[1a6389d5-7bd3-80c5-9a87-e90b034989d0]",
+                    "Deadline is @date[2023-12-31]",
+                    "Use the structure in @db[1a6389d5-7bd3-80e9-b199-000cfb3fa0b3]",
+                ]
+            )
+            .build()
+        )

notionary/elements/notion_block_element.py

@@ -1,4 +1,3 @@
-import inspect
 from typing import Dict, Any, Optional
 from abc import ABC
 
@@ -8,45 +7,28 @@ from notionary.elements.prompts.element_prompt_content import ElementPromptConte
 class NotionBlockElement(ABC):
     """Base class for elements that can be converted between Markdown and Notion."""
 
-    @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 to Notion block."""
 
-    @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 block to markdown."""
 
-    @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."""
-        return bool(NotionBlockElement.markdown_to_notion(text))
+        return bool(cls.markdown_to_notion(text))  # Now calls the class's version
 
-    @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 bool(NotionBlockElement.notion_to_markdown(block))
-
-    @staticmethod
-    def is_multiline() -> bool:
-        return False
+        return bool(cls.notion_to_markdown(block))  # Now calls the class's version
 
     @classmethod
-    def get_llm_documentation(cls) -> str:
-        """
-        Returns documentation specifically formatted for LLM system prompts.
-        Can be overridden by subclasses to provide custom LLM-friendly documentation.
-
-        By default, returns the class docstring.
-        """
+    def is_multiline(cls) -> bool:
+        return False
 
     @classmethod
     def get_llm_prompt_content(cls) -> ElementPromptContent:
-        """
-        Returns a dictionary with information for LLM prompts about this element.
-        This default implementation extracts information from the class docstring.
-        Subclasses should override this method to provide more structured information.
-
-        Returns:
-            Dictionary with documentation information
-        """
-        return {"description": inspect.cleandoc(cls.__doc__ or ""), "examples": []}
+        """Returns a dictionary with information for LLM prompts about this element."""

notionary/elements/numbered_list_element.py

@@ -1,15 +1,18 @@
 import re
 from typing import Dict, Any, Optional
 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 NumberedListElement(NotionBlockElement):
     """Class for converting between Markdown numbered lists and Notion numbered list items."""
 
-    @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 numbered list item to Notion block."""
         pattern = re.compile(r"^\s*(\d+)\.\s+(.+)$")
         numbered_match = pattern.match(text)
@@ -26,8 +29,8 @@ class NumberedListElement(NotionBlockElement):
             "numbered_list_item": {"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 numbered list item block to markdown."""
         if block.get("type") != "numbered_list_item":
             return None
@@ -37,19 +40,19 @@ class NumberedListElement(NotionBlockElement):
 
         return f"1. {content}"
 
-    @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."""
         pattern = re.compile(r"^\s*\d+\.\s+(.+)$")
         return bool(pattern.match(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") == "numbered_list_item"
 
-    @staticmethod
-    def is_multiline() -> bool:
+    @classmethod
+    def is_multiline(cls) -> bool:
         return False
 
     @classmethod
@@ -57,12 +60,18 @@ class NumberedListElement(NotionBlockElement):
         """
         Returns structured LLM prompt metadata for the numbered list element.
         """
-        return {
-            "description": "Creates numbered list items for ordered sequences.",
-            "when_to_use": "Use for lists where order matters, such as steps, rankings, or sequential items.",
-            "syntax": "1. Item text",
-            "examples": [
-                "1. First step\n2. Second step\n3. Third step",
-                "1. Gather materials\n2. Assemble parts\n3. Test the result",
-            ],
-        }
+        return (
+            ElementPromptBuilder()
+            .with_description("Creates numbered list items for ordered sequences.")
+            .with_usage_guidelines(
+                "Use for lists where order matters, such as steps, rankings, or sequential items."
+            )
+            .with_syntax("1. Item text")
+            .with_examples(
+                [
+                    "1. First step\n2. Second step\n3. Third step",
+                    "1. Gather materials\n2. Assemble parts\n3. Test the result",
+                ]
+            )
+            .build()
+        )