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

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,77 @@
-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.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())
-        )
-
-    @classmethod
-    def match_notion(cls, block: Dict[str, Any]) -> bool:
-        """Check if block is a Notion embed."""
-        return block.get("type") == "embed"
+    def match_notion(cls, block: Block) -> bool:
+        return block.type == BlockType.EMBED and block.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:
+    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
-
-        embed_data = {"url": url}
-
-        # Add caption if provided
-        if caption:
-            embed_data["caption"] = [{"type": "text", "text": {"content": caption}}]
-        else:
-            embed_data["caption"] = []
-
-        # Prepare the embed block
-        embed_block = {"type": "embed", "embed": embed_data}
+        url, rich_text = match.group(1), match.group(2) or ""
 
-        # Add empty paragraph after embed
-        empty_paragraph = {"type": "paragraph", "paragraph": {"rich_text": []}}
+        # 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]
 
-        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":
+    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)
-
-        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
-
-    @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()
+        text = "".join(
+            rt.plain_text or TextInlineFormatter.extract_text_with_formatting([rt])
+            for rt in fo.caption
         )
+
+        return f'[embed]({url} "{text}")'

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,80 @@
+from __future__ import annotations
+
+import re
+from typing import Optional
+
+from notionary.blocks.base_block_element import BaseBlockElement
+from notionary.blocks.equation.equation_models import CreateEquationBlock, EquationBlock
+from notionary.blocks.models import Block, BlockCreateResult
+from notionary.blocks.types import BlockType
+
+
+class EquationElement(BaseBlockElement):
+    """
+    Only supports bracket style (analog zu [video]):
+
+      - [equation](E = mc^2)                    # unquoted: keine ')' oder Newlines
+      - [equation]("E = mc^2 + \\frac{a}{b}")   # quoted: erlaubt ')' & Newlines & \"
+
+    No $$...$$ parsing.
+    """
+
+    _QUOTED_PATTERN = re.compile(
+        r'^\[equation\]\(\s*"(?P<quoted_expr>(?:[^"\\]|\\.)*)"\s*\)$',
+        re.DOTALL,
+    )
+
+    _UNQUOTED_PATTERN = re.compile(
+        r"^\[equation\]\(\s*(?P<unquoted_expr>[^)\r\n]+?)\s*\)$"
+    )
+
+    @classmethod
+    def match_notion(cls, block: Block) -> bool:
+        return block.type == BlockType.EQUATION and block.equation
+
+    @classmethod
+    def markdown_to_notion(cls, text: str) -> BlockCreateResult:
+        input_text = text.strip()
+
+        # Try quoted form first: [equation]("...")
+        if quoted_match := cls._QUOTED_PATTERN.match(input_text):
+            raw_expression = quoted_match.group("quoted_expr")
+            # Unescape \" and \\ for Notion
+            unescaped_expression = raw_expression.encode("utf-8").decode(
+                "unicode_escape"
+            )
+            unescaped_expression = unescaped_expression.replace('\\"', '"')
+            final_expression = unescaped_expression.strip()
+
+            return (
+                CreateEquationBlock(equation=EquationBlock(expression=final_expression))
+                if final_expression
+                else None
+            )
+
+        # Try unquoted form: [equation](...)
+        if unquoted_match := cls._UNQUOTED_PATTERN.match(input_text):
+            raw_expression = unquoted_match.group("unquoted_expr").strip()
+            return (
+                CreateEquationBlock(equation=EquationBlock(expression=raw_expression))
+                if raw_expression
+                else None
+            )
+
+        return None
+
+    @classmethod
+    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
+
+        # Use quoted form if expression contains risky characters
+        if ("\n" in expression) or (")" in expression) or ('"' in expression):
+            escaped_expression = expression.replace("\\", "\\\\").replace('"', r"\"")
+            return f'[equation]("{escaped_expression}")'
+
+        return f"[equation]({expression})"

notionary/blocks/equation/equation_element_markdown_node.py

@@ -0,0 +1,36 @@
+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.
+    Example:
+    [equation](E = mc^2)
+    [equation]("f(x) = \\sin(x) + \\cos(x)")
+    """
+
+    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 "[equation]()"
+
+        if ("\n" in expr) or (")" in expr) or ('"' in expr):
+            escaped = expr.replace("\\", "\\\\").replace('"', r"\"")
+            return f'[equation]("{escaped}")'
+
+        return f"[equation]({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",
+]

notionary/blocks/file/file_element.py

@@ -0,0 +1,93 @@
+from __future__ import annotations
+
+import re
+from typing import Optional
+
+from notionary.blocks.base_block_element import BaseBlockElement
+from notionary.blocks.file.file_element_models import (
+    CreateFileBlock,
+    ExternalFile,
+    FileBlock,
+    FileType,
+)
+from notionary.blocks.models import Block, BlockCreateResult, BlockType
+from notionary.blocks.paragraph.paragraph_models import (
+    CreateParagraphBlock,
+    ParagraphBlock,
+)
+from notionary.blocks.rich_text.rich_text_models import RichTextObject
+from notionary.blocks.rich_text.text_inline_formatter import TextInlineFormatter
+
+
+class FileElement(BaseBlockElement):
+    """
+    Handles conversion between Markdown file embeds and Notion file blocks.
+
+    Markdown file syntax:
+    - [file](https://example.com/document.pdf "Caption")
+    - [file](https://example.com/document.pdf)
+
+    Supports external file URLs with optional captions.
+    """
+
+    PATTERN = re.compile(
+        r"^\[file\]\("  # prefix
+        r'(https?://[^\s\)"]+)'  # URL
+        r'(?:\s+"([^"]*)")?'  # optional caption
+        r"\)$"
+    )
+
+    @classmethod
+    def match_notion(cls, block: Block) -> bool:
+        # Notion file block covers files
+        return block.type == BlockType.FILE and block.file
+
+    @classmethod
+    def markdown_to_notion(cls, text: str) -> BlockCreateResult:
+        """Convert markdown file link to Notion FileBlock followed by an empty paragraph."""
+        match = cls.PATTERN.match(text.strip())
+        if not match:
+            return None
+
+        url, caption_text = match.group(1), match.group(2) or ""
+
+        # Build FileBlock using FileType enum
+        file_block = FileBlock(
+            type=FileType.EXTERNAL, external=ExternalFile(url=url), caption=[]
+        )
+        if caption_text.strip():
+            rt = RichTextObject.from_plain_text(caption_text)
+            file_block.caption = [rt]
+
+        empty_para = ParagraphBlock(rich_text=[])
+
+        return [
+            CreateFileBlock(file=file_block),
+            CreateParagraphBlock(paragraph=empty_para),
+        ]
+
+    @classmethod
+    def notion_to_markdown(cls, block: Block) -> Optional[str]:
+        if block.type != BlockType.FILE or not block.file:
+            return None
+
+        fb: FileBlock = block.file
+
+        # Determine URL (only external and file types are valid for Markdown)
+        if fb.type == FileType.EXTERNAL and fb.external:
+            url = fb.external.url
+        elif fb.type == FileType.FILE and fb.file:
+            url = fb.file.url
+        elif fb.type == FileType.FILE_UPLOAD:
+            # Uploaded file has no stable URL for Markdown
+            return None
+        else:
+            return None
+
+        if not fb.caption:
+            return f"[file]({url})"
+
+        caption_md = TextInlineFormatter.extract_text_with_formatting(fb.caption)
+        if caption_md:
+            return f'[file]({url} "{caption_md}")'
+        return f"[file]({url})"

notionary/blocks/file/file_element_markdown_node.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from typing import Optional
+
+from pydantic import BaseModel
+
+from notionary.markdown.markdown_node import MarkdownNode
+
+
+class FileMarkdownNodeParams(BaseModel):
+    url: str
+    caption: Optional[str] = None
+
+
+class FileMarkdownNode(MarkdownNode):
+    """
+    Programmatic interface for creating Notion-style Markdown file embeds.
+    Example: [file](https://example.com/file.pdf "My Caption")
+    """
+
+    def __init__(self, url: str, caption: Optional[str] = None):
+        self.url = url
+        self.caption = caption or ""
+
+    @classmethod
+    def from_params(cls, params: FileMarkdownNodeParams) -> FileMarkdownNode:
+        return cls(url=params.url, caption=params.caption)
+
+    def to_markdown(self) -> str:
+        """
+        Convert to markdown as [file](url "caption") or [file](url) if caption is empty.
+        """
+        if self.caption:
+            return f'[file]({self.url} "{self.caption}")'
+        return f"[file]({self.url})"

notionary/blocks/file/file_element_models.py

@@ -0,0 +1,39 @@
+from enum import Enum
+from typing import Literal, Optional
+
+from pydantic import BaseModel, Field
+
+from notionary.blocks.rich_text.rich_text_models import RichTextObject
+
+
+class FileType(str, Enum):
+    EXTERNAL = "external"
+    FILE = "file"
+    FILE_UPLOAD = "file_upload"
+
+
+class ExternalFile(BaseModel):
+    url: str
+
+
+class NotionHostedFile(BaseModel):
+    url: str
+    expiry_time: str
+
+
+class FileUploadFile(BaseModel):
+    id: str
+
+
+class FileBlock(BaseModel):
+    caption: list[RichTextObject] = Field(default_factory=list)
+    type: FileType
+    external: Optional[ExternalFile] = None
+    file: Optional[NotionHostedFile] = None
+    file_upload: Optional[FileUploadFile] = None
+    name: Optional[str] = None
+
+
+class CreateFileBlock(BaseModel):
+    type: Literal["file"] = "file"
+    file: FileBlock

notionary/blocks/heading/__init__.py

@@ -1,7 +1,21 @@
-from .heading_element import HeadingElement
-from .heading_markdown_node import HeadingMarkdownNode
+from notionary.blocks.heading.heading_element import HeadingElement
+from notionary.blocks.heading.heading_markdown_node import (
+    HeadingMarkdownBlockParams,
+    HeadingMarkdownNode,
+)
+from notionary.blocks.heading.heading_models import (
+    CreateHeading1Block,
+    CreateHeading2Block,
+    CreateHeading3Block,
+    HeadingBlock,
+)
 
 __all__ = [
     "HeadingElement",
+    "HeadingBlock",
+    "CreateHeading1Block",
+    "CreateHeading2Block",
+    "CreateHeading3Block",
     "HeadingMarkdownNode",
+    "HeadingMarkdownBlockParams",
 ]