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

notionary/blocks/divider/__init__.py

@@ -1,7 +1,14 @@
-from .divider_element import DividerElement
-from .divider_markdown_node import DividerMarkdownNode
+from notionary.blocks.divider.divider_element import DividerElement
+from notionary.blocks.divider.divider_markdown_node import (
+    DividerMarkdownBlockParams,
+    DividerMarkdownNode,
+)
+from notionary.blocks.divider.divider_models import CreateDividerBlock, DividerBlock
 
 __all__ = [
     "DividerElement",
+    "DividerBlock",
+    "CreateDividerBlock",
     "DividerMarkdownNode",
+    "DividerMarkdownBlockParams",
 ]

notionary/blocks/divider/divider_element.py

@@ -1,15 +1,15 @@
+from __future__ import annotations
+
 import re
-from typing import Dict, Any, Optional
+from typing import Optional
 
-from notionary.blocks import NotionBlockElement
-from notionary.blocks import (
-    ElementPromptContent,
-    ElementPromptBuilder,
-    NotionBlockResult,
-)
+from notionary.blocks.base_block_element import BaseBlockElement
+from notionary.blocks.divider.divider_models import CreateDividerBlock, DividerBlock
+from notionary.blocks.models import Block, BlockCreateResult
+from notionary.blocks.types import BlockType
 
 
-class DividerElement(NotionBlockElement):
+class DividerElement(BaseBlockElement):
     """
     Handles conversion between Markdown horizontal dividers and Notion divider blocks.
 
@@ -20,53 +20,22 @@ class DividerElement(NotionBlockElement):
     PATTERN = re.compile(r"^\s*-{3,}\s*$")
 
     @classmethod
-    def match_markdown(cls, text: str) -> bool:
-        """Check if text is a markdown divider."""
-        return bool(DividerElement.PATTERN.match(text))
-
-    @classmethod
-    def match_notion(cls, block: Dict[str, Any]) -> bool:
-        """Check if block is a Notion divider."""
-        return block.get("type") == "divider"
+    def match_notion(cls, block: Block) -> bool:
+        """Check if this element can handle the given Notion block."""
+        return block.type == BlockType.DIVIDER and block.divider
 
     @classmethod
-    def markdown_to_notion(cls, text: str) -> NotionBlockResult:
-        """Convert markdown divider to Notion divider block."""
-        if not DividerElement.match_markdown(text):
+    async def markdown_to_notion(cls, text: str) -> BlockCreateResult:
+        """Convert markdown horizontal rule to Notion divider, with preceding empty paragraph."""
+        if not cls.PATTERN.match(text.strip()):
             return None
 
-        empty_paragraph = {"type": "paragraph", "paragraph": {"rich_text": []}}
+        divider = DividerBlock()
 
-        divider_block = {"type": "divider", "divider": {}}
-
-        return [empty_paragraph, divider_block]
+        return CreateDividerBlock(divider=divider)
 
     @classmethod
-    def notion_to_markdown(cls, block: Dict[str, Any]) -> Optional[str]:
-        """Convert Notion divider block to markdown divider."""
-        if block.get("type") != "divider":
+    async def notion_to_markdown(cls, block: Block) -> Optional[str]:
+        if block.type != BlockType.DIVIDER or not block.divider:
             return None
-
         return "---"
-
-    @classmethod
-    def is_multiline(cls) -> bool:
-        return False
-
-    @classmethod
-    def get_llm_prompt_content(cls) -> ElementPromptContent:
-        """Returns structured LLM prompt metadata for the divider element."""
-        return (
-            ElementPromptBuilder()
-            .with_description(
-                "Creates a horizontal divider line to visually separate sections of content."
-            )
-            .with_usage_guidelines(
-                "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(
-                ["## Section 1\nContent\n\n---\n\n## Section 2\nMore content"]
-            )
-            .build()
-        )

notionary/blocks/divider/divider_markdown_node.py

@@ -1,7 +1,8 @@
 from __future__ import annotations
 
 from pydantic import BaseModel
-from notionary.blocks.markdown_node import MarkdownNode
+
+from notionary.markdown.markdown_node import MarkdownNode
 
 
 class DividerMarkdownBlockParams(BaseModel):

notionary/blocks/divider/divider_models.py

@@ -0,0 +1,12 @@
+from typing import Literal
+
+from pydantic import BaseModel
+
+
+class DividerBlock(BaseModel):
+    pass
+
+
+class CreateDividerBlock(BaseModel):
+    type: Literal["divider"] = "divider"
+    divider: DividerBlock

notionary/blocks/embed/__init__.py

@@ -1,7 +1,14 @@
-from .embed_element import EmbedElement
-from .embed_markdown_node import EmbedMarkdownNode
+from notionary.blocks.embed.embed_element import EmbedElement
+from notionary.blocks.embed.embed_markdown_node import (
+    EmbedMarkdownBlockParams,
+    EmbedMarkdownNode,
+)
+from notionary.blocks.embed.embed_models import CreateEmbedBlock, EmbedBlock
 
 __all__ = [
     "EmbedElement",
+    "EmbedBlock",
+    "CreateEmbedBlock",
     "EmbedMarkdownNode",
+    "EmbedMarkdownBlockParams",
 ]

notionary/blocks/embed/embed_element.py

@@ -1,144 +1,98 @@
-import re
-from typing import Dict, Any, Optional, List
+from __future__ import annotations
 
-from notionary.blocks import NotionBlockElement
-from notionary.blocks import (
-    ElementPromptContent,
-    ElementPromptBuilder,
-    NotionBlockResult,
+import re
+from typing import Optional
+
+from notionary.blocks.base_block_element import BaseBlockElement
+from notionary.blocks.embed.embed_models import CreateEmbedBlock, EmbedBlock
+from notionary.blocks.file.file_element_models import (
+    ExternalFile,
+    FileUploadFile,
+    NotionHostedFile,
 )
+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
 
 
-class EmbedElement(NotionBlockElement):
+class EmbedElement(BaseBlockElement):
     """
     Handles conversion between Markdown embeds and Notion embed blocks.
 
     Markdown embed syntax:
-    - [embed](https://example.com) - Simple embed with URL only
-    - [embed](https://example.com "Caption") - Embed with URL and caption
-
-    Where:
-    - URL is the required embed URL
-    - Caption is an optional descriptive text (enclosed in quotes)
-
-    Supports various URL types including websites, PDFs, Google Maps, Google Drive,
-    Twitter/X posts, and other sources that Notion can embed.
+    - [embed](https://example.com) - URL only
+    - [embed](https://example.com "Caption") - URL + caption
     """
 
-    # Regex pattern for embed syntax with optional caption
     PATTERN = re.compile(
-        r"^\[embed\]\("  # [embed]( prefix
-        + r'(https?://[^\s"]+)'  # URL (required)
-        + r'(?:\s+"([^"]+)")?'  # Optional caption in quotes
-        + r"\)$"  # closing parenthesis
+        r"^\[embed\]\("  # prefix
+        r"(https?://[^\s\"]+)"  # URL
+        r"(?:\s+\"([^\"]+)\")?"  # optional caption
+        r"\)$"
     )
 
     @classmethod
-    def match_markdown(cls, text: str) -> bool:
-        """Check if text is a markdown embed."""
-        return text.strip().startswith("[embed]") and bool(
-            EmbedElement.PATTERN.match(text.strip())
-        )
+    def match_notion(cls, block: Block) -> bool:
+        return block.type == BlockType.EMBED and block.embed
 
     @classmethod
-    def match_notion(cls, block: Dict[str, Any]) -> bool:
-        """Check if block is a Notion embed."""
-        return block.get("type") == "embed"
-
-    @classmethod
-    def markdown_to_notion(cls, text: str) -> NotionBlockResult:
-        """Convert markdown embed to Notion embed block."""
-        embed_match = EmbedElement.PATTERN.match(text.strip())
-        if not embed_match:
+    async def markdown_to_notion(cls, text: str) -> BlockCreateResult:
+        """Convert markdown embed syntax to Notion EmbedBlock."""
+        match = cls.PATTERN.match(text.strip())
+        if not match:
             return None
 
-        url = embed_match.group(1)
-        caption = embed_match.group(2)
-
-        if not url:
-            return None
+        url, rich_text = match.group(1), match.group(2) or ""
 
-        embed_data = {"url": url}
-
-        # Add caption if provided
-        if caption:
-            embed_data["caption"] = [{"type": "text", "text": {"content": caption}}]
-        else:
-            embed_data["caption"] = []
+        # Build EmbedBlock
+        embed_block = EmbedBlock(url=url, caption=[])
+        if rich_text.strip():
+            rich_text_obj = RichTextObject.from_plain_text(rich_text.strip())
+            embed_block.caption = [rich_text_obj]
 
-        # Prepare the embed block
-        embed_block = {"type": "embed", "embed": embed_data}
-
-        # Add empty paragraph after embed
-        empty_paragraph = {"type": "paragraph", "paragraph": {"rich_text": []}}
-
-        return [embed_block, empty_paragraph]
+        return CreateEmbedBlock(embed=embed_block)
 
     @classmethod
-    def notion_to_markdown(cls, block: Dict[str, Any]) -> Optional[str]:
-        """Convert Notion embed block to markdown embed."""
-        if block.get("type") != "embed":
+    async def notion_to_markdown(cls, block: Block) -> Optional[str]:
+        if block.type != BlockType.EMBED or not block.embed:
             return None
 
-        embed_data = block.get("embed", {})
-        url = embed_data.get("url", "")
+        fo = block.embed
 
-        if not url:
+        if isinstance(fo, (ExternalFile, NotionHostedFile)):
+            url = fo.url
+        elif isinstance(fo, FileUploadFile):
+            return None
+        else:
             return None
 
-        caption_rich_text = embed_data.get("caption", [])
-
-        if not caption_rich_text:
-            # Simple embed with URL only
+        if not fo.caption:
             return f"[embed]({url})"
 
-        # Extract caption text
-        caption = EmbedElement._extract_text_content(caption_rich_text)
+        text_parts = []
+        for rt in fo.caption:
+            if rt.plain_text:
+                text_parts.append(rt.plain_text)
+            else:
+                formatted_text = await TextInlineFormatter.extract_text_with_formatting(
+                    [rt]
+                )
+                text_parts.append(formatted_text)
+        text = "".join(text_parts)
 
-        if caption:
-            return f'[embed]({url} "{caption}")'
-
-        return f"[embed]({url})"
-
-    @classmethod
-    def is_multiline(cls) -> bool:
-        """Embeds are single-line elements."""
-        return False
-
-    @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:
-            if text_obj.get("type") == "text":
-                result += text_obj.get("text", {}).get("content", "")
-            elif "plain_text" in text_obj:
-                result += text_obj.get("plain_text", "")
-        return result
+        return f'[embed]({url} "{text}")'
 
     @classmethod
-    def get_llm_prompt_content(cls) -> ElementPromptContent:
-        """
-        Returns structured LLM prompt metadata for the embed element.
-        """
-        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."
-            )
-            .with_syntax('[embed](https://example.com "Optional caption")')
-            .with_examples(
-                [
-                    "[embed](https://drive.google.com/file/d/123456/view)",
-                    '[embed](https://www.google.com/maps?q=San+Francisco "Our office location")',
-                    '[embed](https://twitter.com/NotionHQ/status/1234567890 "Latest announcement")',
-                    '[embed](https://github.com/username/repo "Project documentation")',
-                    '[embed](https://example.com/important-reference.pdf "Course materials")',
-                ]
-            )
-            .build()
+    def get_system_prompt_information(cls) -> Optional[BlockElementMarkdownInformation]:
+        """Get system prompt information for embed blocks."""
+        return BlockElementMarkdownInformation(
+            block_type=cls.__name__,
+            description="Embed blocks display interactive content from external URLs like videos, maps, or widgets",
+            syntax_examples=[
+                "[embed](https://youtube.com/watch?v=123)",
+                '[embed](https://maps.google.com/location "Map Location")',
+                '[embed](https://codepen.io/pen/123 "Interactive Demo")',
+            ],
+            usage_guidelines="Use for embedding interactive content that supports iframe embedding. URL must be from a supported platform. Caption describes the embedded content.",
         )

notionary/blocks/embed/embed_markdown_node.py

@@ -1,8 +1,10 @@
 from __future__ import annotations
 
 from typing import Optional
+
 from pydantic import BaseModel
-from notionary.blocks.markdown_node import MarkdownNode
+
+from notionary.markdown.markdown_node import MarkdownNode
 
 
 class EmbedMarkdownBlockParams(BaseModel):

notionary/blocks/embed/embed_models.py

@@ -0,0 +1,14 @@
+from pydantic import BaseModel, Field
+from typing_extensions import Literal
+
+from notionary.blocks.rich_text.rich_text_models import RichTextObject
+
+
+class EmbedBlock(BaseModel):
+    url: str
+    caption: list[RichTextObject] = Field(default_factory=list)
+
+
+class CreateEmbedBlock(BaseModel):
+    type: Literal["embed"] = "embed"
+    embed: EmbedBlock

notionary/blocks/equation/__init__.py

@@ -0,0 +1,14 @@
+from notionary.blocks.equation.equation_element import EquationElement
+from notionary.blocks.equation.equation_element_markdown_node import (
+    EquationMarkdownBlockParams,
+    EquationMarkdownNode,
+)
+from notionary.blocks.equation.equation_models import CreateEquationBlock, EquationBlock
+
+__all__ = [
+    "EquationElement",
+    "EquationBlock",
+    "CreateEquationBlock",
+    "EquationMarkdownNode",
+    "EquationMarkdownBlockParams",
+]

notionary/blocks/equation/equation_element.py

@@ -0,0 +1,133 @@
+from __future__ import annotations
+
+import re
+import textwrap
+from typing import Optional
+
+from notionary.blocks.base_block_element import BaseBlockElement
+from notionary.blocks.equation.equation_models import CreateEquationBlock, EquationBlock
+from notionary.blocks.syntax_prompt_builder import BlockElementMarkdownInformation
+from notionary.blocks.models import Block, BlockCreateResult
+from notionary.blocks.types import BlockType
+
+
+class EquationElement(BaseBlockElement):
+    """
+    Supports standard Markdown equation syntax:
+
+      - $$E = mc^2$$                           # simple equations
+      - $$E = mc^2 + \\frac{a}{b}$$           # complex equations with LaTeX
+
+    Uses $$...$$ parsing for block equations.
+    """
+
+    _EQUATION_PATTERN = re.compile(
+        r"^\$\$\s*(?P<expression>.*?)\s*\$\$$",
+        re.DOTALL,
+    )
+
+    @classmethod
+    def match_notion(cls, block: Block) -> bool:
+        return block.type == BlockType.EQUATION and block.equation
+
+    @classmethod
+    async def markdown_to_notion(cls, text: str) -> BlockCreateResult:
+        input_text = text.strip()
+
+        equation_match = cls._EQUATION_PATTERN.match(input_text)
+        if not equation_match:
+            return None
+
+        expression = equation_match.group("expression").strip()
+        if not expression:
+            return None
+
+        return CreateEquationBlock(equation=EquationBlock(expression=expression))
+
+    @classmethod
+    def create_from_markdown_block(
+        cls, opening_line: str, equation_lines: list[str]
+    ) -> BlockCreateResult:
+        """
+        Create a complete equation block from markdown components.
+        Handles multiline equations like:
+        $$
+        some
+        inline formula here
+        $$
+
+        Automatically handles:
+        - Indentation removal from multiline strings
+        - Single backslash conversion to double backslash for LaTeX line breaks
+        """
+        # Check if opening line is just $$
+        if opening_line.strip() != "$$":
+            return None
+
+        # Process equation lines if any exist
+        if equation_lines:
+            # Remove common indentation from all lines
+            raw_content = "\n".join(equation_lines)
+            dedented_content = textwrap.dedent(raw_content)
+
+            # Fix single backslashes at line ends for LaTeX line breaks
+            fixed_lines = cls._fix_latex_line_breaks(dedented_content.splitlines())
+            expression = "\n".join(fixed_lines).strip()
+
+            if expression:
+                return CreateEquationBlock(
+                    equation=EquationBlock(expression=expression)
+                )
+
+        return None
+
+    @classmethod
+    def _fix_latex_line_breaks(cls, lines: list[str]) -> list[str]:
+        """
+        Fix lines that end with single backslashes by converting them to double backslashes.
+        This makes LaTeX line breaks work correctly when users write single backslashes.
+
+        Examples:
+        - "a = b + c \" -> "a = b + c \\"
+        - "a = b + c \\\\" -> "a = b + c \\\\" (unchanged)
+        """
+        fixed_lines = []
+
+        for line in lines:
+            # Check if line ends with backslashes
+            backslash_match = re.search(r"(\\+)$", line)
+            if backslash_match:
+                backslashes = backslash_match.group(1)
+                # If odd number of backslashes, the last one needs to be doubled
+                if len(backslashes) % 2 == 1:
+                    line = line + "\\"
+
+            fixed_lines.append(line)
+
+        return fixed_lines
+
+    @classmethod
+    async def notion_to_markdown(cls, block: Block) -> Optional[str]:
+        if block.type != BlockType.EQUATION or not block.equation:
+            return None
+
+        expression = (block.equation.expression or "").strip()
+        if not expression:
+            return None
+
+        return f"$${expression}$$"
+
+    @classmethod
+    def get_system_prompt_information(cls) -> Optional[BlockElementMarkdownInformation]:
+        """Get system prompt information for equation blocks."""
+        return BlockElementMarkdownInformation(
+            block_type=cls.__name__,
+            description="Mathematical equations using standard Markdown LaTeX syntax",
+            syntax_examples=[
+                "$$E = mc^2$$",
+                "$$\\frac{a}{b} + \\sqrt{c}$$",
+                "$$\\int_0^\\infty e^{-x} dx = 1$$",
+                "$$\\sum_{i=1}^n i = \\frac{n(n+1)}{2}$$",
+            ],
+            usage_guidelines="Use for mathematical expressions and formulas. Supports LaTeX syntax. Wrap equations in double dollar signs ($$).",
+        )

notionary/blocks/equation/equation_element_markdown_node.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+from notionary.markdown.markdown_node import MarkdownNode
+
+
+class EquationMarkdownBlockParams(BaseModel):
+    expression: str
+
+
+class EquationMarkdownNode(MarkdownNode):
+    """
+    Programmatic interface for creating Markdown equation blocks.
+    Uses standard Markdown equation syntax with double dollar signs.
+
+    Examples:
+    $$E = mc^2$$
+    $$\\frac{a}{b} + \\sqrt{c}$$
+    $$\\int_0^\\infty e^{-x} dx = 1$$
+    """
+
+    def __init__(self, expression: str):
+        self.expression = expression
+
+    @classmethod
+    def from_params(cls, params: EquationMarkdownBlockParams) -> EquationMarkdownNode:
+        return cls(expression=params.expression)
+
+    def to_markdown(self) -> str:
+        expr = self.expression.strip()
+        if not expr:
+            return "$$$$"
+
+        return f"$${expr}$$"

notionary/blocks/equation/equation_models.py

@@ -0,0 +1,11 @@
+from pydantic import BaseModel
+from typing_extensions import Literal
+
+
+class EquationBlock(BaseModel):
+    expression: str
+
+
+class CreateEquationBlock(BaseModel):
+    type: Literal["equation"] = "equation"
+    equation: EquationBlock

notionary/blocks/file/__init__.py

@@ -0,0 +1,25 @@
+from notionary.blocks.file.file_element import FileElement
+from notionary.blocks.file.file_element_markdown_node import (
+    FileMarkdownNode,
+    FileMarkdownNodeParams,
+)
+from notionary.blocks.file.file_element_models import (
+    CreateFileBlock,
+    ExternalFile,
+    FileBlock,
+    FileType,
+    FileUploadFile,
+    NotionHostedFile,
+)
+
+__all__ = [
+    "FileElement",
+    "FileType",
+    "ExternalFile",
+    "NotionHostedFile",
+    "FileUploadFile",
+    "FileBlock",
+    "CreateFileBlock",
+    "FileMarkdownNode",
+    "FileMarkdownNodeParams",
+]