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

notionary/blocks/mixins/captions/caption_mixin.py

@@ -0,0 +1,92 @@
+from typing import Optional
+import re
+from notionary.blocks.rich_text.rich_text_models import RichTextObject
+from notionary.blocks.rich_text.text_inline_formatter import TextInlineFormatter
+
+
+class CaptionMixin:
+    """Mixin to add caption parsing functionality to block elements."""
+
+    # Generic caption pattern - finds caption anywhere in text
+    CAPTION_PATTERN = re.compile(r"\(caption:([^)]*)\)")
+
+    @classmethod
+    def extract_caption(cls, text: str) -> Optional[str]:
+        """
+        Extract caption text from anywhere in the input text.
+        Returns only the caption content, preserving parentheses in content.
+        """
+        # Look for (caption: followed by content followed by )
+        # Handle cases where caption content contains parentheses
+        caption_start = text.find("(caption:")
+        if caption_start == -1:
+            return None
+
+        # Find the matching closing parenthesis
+        # Start after "(caption:"
+        content_start = caption_start + 9  # len("(caption:")
+        paren_count = 1
+        pos = content_start
+
+        while pos < len(text) and paren_count > 0:
+            if text[pos] == "(":
+                paren_count += 1
+            elif text[pos] == ")":
+                paren_count -= 1
+            pos += 1
+
+        if paren_count == 0:
+            # Found matching closing parenthesis
+            return text[content_start : pos - 1]
+
+        return None
+
+    @classmethod
+    def remove_caption(cls, text: str) -> str:
+        """
+        Remove caption from text and return clean text.
+        Uses the same balanced parentheses logic as extract_caption.
+        """
+        caption_start = text.find("(caption:")
+        if caption_start == -1:
+            return text.strip()
+
+        # Find the matching closing parenthesis
+        content_start = caption_start + 9  # len("(caption:")
+        paren_count = 1
+        pos = content_start
+
+        while pos < len(text) and paren_count > 0:
+            if text[pos] == "(":
+                paren_count += 1
+            elif text[pos] == ")":
+                paren_count -= 1
+            pos += 1
+
+        if paren_count == 0:
+            # Remove the entire caption including the outer parentheses
+            return (text[:caption_start] + text[pos:]).strip()
+
+        # Fallback to regex-based removal if balanced parsing fails
+        return cls.CAPTION_PATTERN.sub("", text).strip()
+
+    @classmethod
+    def build_caption_rich_text(cls, caption_text: str) -> list[RichTextObject]:
+        """Return caption as canonical rich text list (with annotations)."""
+        if not caption_text:
+            return []
+        # IMPORTANT: use the same formatter used elsewhere in the app
+        return [RichTextObject.for_caption(caption_text)]
+
+    @classmethod
+    async def format_caption_for_markdown(
+        cls, caption_list: list[RichTextObject]
+    ) -> str:
+        """Convert rich text caption back to markdown format."""
+        if not caption_list:
+            return ""
+        # Preserve markdown formatting (bold, italic, etc.)
+        caption_text = await TextInlineFormatter.extract_text_with_formatting(
+            caption_list
+        )
+        return f"(caption:{caption_text})" if caption_text else ""

notionary/blocks/models.py

@@ -0,0 +1,174 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Literal, Optional, Union
+
+from pydantic import BaseModel
+
+from notionary.blocks.types import BlockType
+
+if TYPE_CHECKING:
+    from notionary.blocks.bookmark import BookmarkBlock, CreateBookmarkBlock
+    from notionary.blocks.breadcrumbs import BreadcrumbBlock, CreateBreadcrumbBlock
+    from notionary.blocks.bulleted_list import (
+        BulletedListItemBlock,
+        CreateBulletedListItemBlock,
+    )
+    from notionary.blocks.callout import CalloutBlock, CreateCalloutBlock
+    from notionary.blocks.child_page import ChildPageBlock, CreateChildPageBlock
+    from notionary.blocks.code import CodeBlock, CreateCodeBlock
+    from notionary.blocks.column import (
+        ColumnBlock,
+        ColumnListBlock,
+        CreateColumnBlock,
+        CreateColumnListBlock,
+    )
+    from notionary.blocks.divider import CreateDividerBlock, DividerBlock
+    from notionary.blocks.embed import CreateEmbedBlock, EmbedBlock
+    from notionary.blocks.equation import CreateEquationBlock, EquationBlock
+    from notionary.blocks.file import CreateFileBlock, FileBlock
+    from notionary.blocks.heading import (
+        CreateHeading1Block,
+        CreateHeading2Block,
+        CreateHeading3Block,
+        HeadingBlock,
+    )
+    from notionary.blocks.image_block import CreateImageBlock
+    from notionary.blocks.numbered_list import (
+        CreateNumberedListItemBlock,
+        NumberedListItemBlock,
+    )
+    from notionary.blocks.paragraph import CreateParagraphBlock, ParagraphBlock
+    from notionary.blocks.pdf import CreatePdfBlock
+    from notionary.blocks.quote import CreateQuoteBlock, QuoteBlock
+    from notionary.blocks.table import CreateTableBlock, TableBlock, TableRowBlock
+    from notionary.blocks.table_of_contents import (
+        CreateTableOfContentsBlock,
+        TableOfContentsBlock,
+    )
+    from notionary.blocks.todo import CreateToDoBlock, ToDoBlock
+    from notionary.blocks.toggle import CreateToggleBlock, ToggleBlock
+    from notionary.blocks.video import CreateVideoBlock
+    from notionary.blocks.child_database import ChildDatabaseBlock
+
+
+class BlockChildrenResponse(BaseModel):
+    object: Literal["list"]
+    results: list["Block"]
+    next_cursor: Optional[str] = None
+    has_more: bool
+    type: Literal["block"]
+    block: dict = {}
+    request_id: str
+
+
+class PageParent(BaseModel):
+    type: Literal["page_id"]
+    page_id: str
+
+
+class DatabaseParent(BaseModel):
+    type: Literal["database_id"]
+    database_id: str
+
+
+class BlockParent(BaseModel):
+    type: Literal["block_id"]
+    block_id: str
+
+
+class WorkspaceParent(BaseModel):
+    type: Literal["workspace"]
+    workspace: bool = True
+
+
+ParentObject = Union[PageParent, DatabaseParent, BlockParent, WorkspaceParent]
+
+
+class PartialUser(BaseModel):
+    object: Literal["user"]
+    id: str
+
+
+class Block(BaseModel):
+    object: Literal["block"]
+    id: str
+    parent: Optional[ParentObject] = None
+    type: BlockType
+    created_time: str
+    last_edited_time: str
+    created_by: PartialUser
+    last_edited_by: PartialUser
+    archived: bool = False
+    in_trash: bool = False
+    has_children: bool = False
+
+    children: Optional[list[Block]] = None
+
+    # Block type-specific content (only one will be populated based on type)
+    audio: Optional[FileBlock] = None
+    bookmark: Optional[BookmarkBlock] = None
+    breadcrumb: Optional[BreadcrumbBlock] = None
+    bulleted_list_item: Optional[BulletedListItemBlock] = None
+    callout: Optional[CalloutBlock] = None
+    child_page: Optional[ChildPageBlock] = None
+    code: Optional[CodeBlock] = None
+    column_list: Optional[ColumnListBlock] = None
+    column: Optional[ColumnBlock] = None
+    divider: Optional[DividerBlock] = None
+    embed: Optional[EmbedBlock] = None
+    equation: Optional[EquationBlock] = None
+    file: Optional[FileBlock] = None
+    heading_1: Optional[HeadingBlock] = None
+    heading_2: Optional[HeadingBlock] = None
+    heading_3: Optional[HeadingBlock] = None
+    image: Optional[FileBlock] = None
+    numbered_list_item: Optional[NumberedListItemBlock] = None
+    paragraph: Optional[ParagraphBlock] = None
+    quote: Optional[QuoteBlock] = None
+    table: Optional[TableBlock] = None
+    table_row: Optional[TableRowBlock] = None
+    to_do: Optional[ToDoBlock] = None
+    toggle: Optional[ToggleBlock] = None
+    video: Optional[FileBlock] = None
+    pdf: Optional[FileBlock] = None
+    table_of_contents: Optional[TableOfContentsBlock] = None
+    child_database: Optional[ChildDatabaseBlock] = None
+
+    def get_block_content(self) -> Optional[Any]:
+        """Get the content object for this block based on its type."""
+        return getattr(self, self.type, None)
+
+
+if TYPE_CHECKING:
+    BlockCreateRequest = Union[
+        CreateBookmarkBlock,
+        CreateBreadcrumbBlock,
+        CreateBulletedListItemBlock,
+        CreateCalloutBlock,
+        CreateChildPageBlock,
+        CreateCodeBlock,
+        CreateColumnListBlock,
+        CreateColumnBlock,
+        CreateDividerBlock,
+        CreateEmbedBlock,
+        CreateEquationBlock,
+        CreateFileBlock,
+        CreateHeading1Block,
+        CreateHeading2Block,
+        CreateHeading3Block,
+        CreateImageBlock,
+        CreateNumberedListItemBlock,
+        CreateParagraphBlock,
+        CreateQuoteBlock,
+        CreateToDoBlock,
+        CreateToggleBlock,
+        CreateVideoBlock,
+        CreateTableOfContentsBlock,
+        CreatePdfBlock,
+        CreateTableBlock,
+    ]
+    BlockCreateResult = Union[BlockCreateRequest]
+else:
+    # at runtime there are no typings anyway
+    BlockCreateRequest = Any
+    BlockCreateResult = Any

notionary/blocks/numbered_list/__init__.py

@@ -1,7 +1,17 @@
-from .numbered_list_element import NumberedListElement
-from .numbered_list_markdown_node import NumberedListMarkdownNode
+from notionary.blocks.numbered_list.numbered_list_element import NumberedListElement
+from notionary.blocks.numbered_list.numbered_list_markdown_node import (
+    NumberedListMarkdownBlockParams,
+    NumberedListMarkdownNode,
+)
+from notionary.blocks.numbered_list.numbered_list_models import (
+    CreateNumberedListItemBlock,
+    NumberedListItemBlock,
+)
 
 __all__ = [
     "NumberedListElement",
+    "NumberedListItemBlock",
+    "CreateNumberedListItemBlock",
     "NumberedListMarkdownNode",
+    "NumberedListMarkdownBlockParams",
 ]

notionary/blocks/numbered_list/numbered_list_element.py

@@ -1,73 +1,65 @@
+from __future__ import annotations
+
 import re
-from typing import Any, Optional
-from notionary.blocks import NotionBlockElement
-from notionary.blocks import (
-    ElementPromptContent,
-    ElementPromptBuilder,
-    NotionBlockResult,
+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.numbered_list.numbered_list_models import (
+    CreateNumberedListItemBlock,
+    NumberedListItemBlock,
 )
-from notionary.blocks.shared.text_inline_formatter import TextInlineFormatter
+from notionary.blocks.rich_text.text_inline_formatter import TextInlineFormatter
+from notionary.blocks.types import BlockColor
 
 
-class NumberedListElement(NotionBlockElement):
-    """Class for converting between Markdown numbered lists and Notion numbered list items."""
+class NumberedListElement(BaseBlockElement):
+    """Converts between Markdown numbered lists and Notion numbered list items."""
 
-    @classmethod
-    def markdown_to_notion(cls, text: str) -> NotionBlockResult:
-        """Convert markdown numbered list item to Notion block."""
-        pattern = re.compile(r"^\s*(\d+)\.\s+(.+)$")
-        numbered_match = pattern.match(text)
-        if not numbered_match:
-            return None
+    PATTERN = re.compile(r"^\s*(\d+)\.\s+(.+)$")
 
-        content = numbered_match.group(2)
-
-        # Use parse_inline_formatting to handle rich text
-        rich_text = TextInlineFormatter.parse_inline_formatting(content)
-
-        return {
-            "type": "numbered_list_item",
-            "numbered_list_item": {"rich_text": rich_text, "color": "default"},
-        }
+    @classmethod
+    def match_notion(cls, block: Block) -> bool:
+        return block.type == BlockType.NUMBERED_LIST_ITEM and block.numbered_list_item
 
     @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":
+    async def markdown_to_notion(cls, text: str) -> BlockCreateResult:
+        """Convert markdown numbered list item to Notion NumberedListItemBlock."""
+        match = cls.PATTERN.match(text.strip())
+        if not match:
             return None
 
-        rich_text = block.get("numbered_list_item", {}).get("rich_text", [])
-        content = TextInlineFormatter.extract_text_with_formatting(rich_text)
+        content = match.group(2)
+        rich_text = await TextInlineFormatter.parse_inline_formatting(content)
 
-        return f"1. {content}"
-
-    @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))
+        numbered_list_content = NumberedListItemBlock(
+            rich_text=rich_text, color=BlockColor.DEFAULT
+        )
+        return CreateNumberedListItemBlock(numbered_list_item=numbered_list_content)
 
+    # FIX: Roundtrip conversions will never work this way here
     @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"
+    async def notion_to_markdown(cls, block: Block) -> Optional[str]:
+        if block.type != BlockType.NUMBERED_LIST_ITEM or not block.numbered_list_item:
+            return None
 
-    @classmethod
-    def is_multiline(cls) -> bool:
-        return False
+        rich = block.numbered_list_item.rich_text
+        content = await TextInlineFormatter.extract_text_with_formatting(rich)
+        return f"1. {content}"
 
     @classmethod
-    def get_llm_prompt_content(cls) -> ElementPromptContent:
-        """
-        Returns structured LLM prompt metadata for the numbered list element.
-        """
-        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_standard_markdown()
-            .build()
+    def get_system_prompt_information(cls) -> Optional[BlockElementMarkdownInformation]:
+        """Get system prompt information for numbered list blocks."""
+        return BlockElementMarkdownInformation(
+            block_type=cls.__name__,
+            description="Numbered list items create ordered lists with sequential numbering",
+            syntax_examples=[
+                "1. First item",
+                "2. Second item",
+                "3. Third item",
+                "1. Item with **bold text**",
+                "1. Item with *italic text*",
+            ],
+            usage_guidelines="Use numbers followed by periods to create ordered lists. Supports inline formatting like bold, italic, and links. Numbering is automatically handled by Notion.",
         )

notionary/blocks/numbered_list/numbered_list_markdown_node.py

@@ -1,6 +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 NumberedListMarkdownBlockParams(BaseModel):

notionary/blocks/numbered_list/numbered_list_models.py

@@ -0,0 +1,17 @@
+from pydantic import BaseModel, Field
+from typing_extensions import Literal
+
+from notionary.blocks.models import Block
+from notionary.blocks.rich_text.rich_text_models import RichTextObject
+from notionary.blocks.types import BlockColor
+
+
+class NumberedListItemBlock(BaseModel):
+    rich_text: list[RichTextObject]
+    color: BlockColor = BlockColor.DEFAULT
+    children: list[Block] = Field(default_factory=list)
+
+
+class CreateNumberedListItemBlock(BaseModel):
+    type: Literal["numbered_list_item"] = "numbered_list_item"
+    numbered_list_item: NumberedListItemBlock

notionary/blocks/paragraph/__init__.py

@@ -1,7 +1,17 @@
-from .paragraph_element import ParagraphElement
-from .paragraph_markdown_node import ParagraphMarkdownNode
+from notionary.blocks.paragraph.paragraph_element import ParagraphElement
+from notionary.blocks.paragraph.paragraph_markdown_node import (
+    ParagraphMarkdownBlockParams,
+    ParagraphMarkdownNode,
+)
+from notionary.blocks.paragraph.paragraph_models import (
+    CreateParagraphBlock,
+    ParagraphBlock,
+)
 
 __all__ = [
     "ParagraphElement",
+    "ParagraphBlock",
+    "CreateParagraphBlock",
     "ParagraphMarkdownNode",
+    "ParagraphMarkdownBlockParams",
 ]

notionary/blocks/paragraph/paragraph_element.py

@@ -1,84 +1,58 @@
-from typing import Dict, Any, Optional
+from __future__ import annotations
 
-from notionary.blocks import NotionBlockElement
-from notionary.blocks import (
-    ElementPromptContent,
-    ElementPromptBuilder,
-    NotionBlockResult,
-)
-from notionary.blocks.shared.text_inline_formatter import TextInlineFormatter
+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.paragraph.paragraph_models import (
+    CreateParagraphBlock,
+    ParagraphBlock,
+)
+from notionary.blocks.rich_text.text_inline_formatter import TextInlineFormatter
+from notionary.blocks.types import BlockColor, BlockType
 
-class ParagraphElement(NotionBlockElement):
-    """Handles conversion between Markdown paragraphs and Notion paragraph blocks."""
 
-    @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.
-        Since paragraphs are the fallback element, this always returns True.
-        """
-        return True
+class ParagraphElement(BaseBlockElement):
+    """
+    Handles conversion between Markdown paragraphs and Notion paragraph blocks.
+    """
 
     @classmethod
-    def match_notion(cls, block: Dict[str, Any]) -> bool:
-        """Check if block is a Notion paragraph."""
-        return block.get("type") == "paragraph"
+    def match_notion(cls, block: Block) -> bool:
+        return block.type == "paragraph" and block.paragraph
 
     @classmethod
-    def markdown_to_notion(cls, text: str) -> NotionBlockResult:
-        """Convert markdown paragraph to Notion paragraph block."""
+    async def markdown_to_notion(cls, text: str) -> BlockCreateResult:
+        """Convert markdown text to a Notion ParagraphBlock."""
         if not text.strip():
             return None
 
-        return {
-            "type": "paragraph",
-            "paragraph": {
-                "rich_text": TextInlineFormatter.parse_inline_formatting(text)
-            },
-        }
+        rich = await TextInlineFormatter.parse_inline_formatting(text)
+
+        paragraph_content = ParagraphBlock(rich_text=rich, color=BlockColor.DEFAULT)
+        return CreateParagraphBlock(paragraph=paragraph_content)
 
     @classmethod
-    def notion_to_markdown(cls, block: Dict[str, Any]) -> Optional[str]:
-        """Convert Notion paragraph block to markdown paragraph."""
-        if block.get("type") != "paragraph":
+    async def notion_to_markdown(cls, block: Block) -> Optional[str]:
+        if block.type != BlockType.PARAGRAPH or not block.paragraph:
             return None
 
-        paragraph_data = block.get("paragraph", {})
-        rich_text = paragraph_data.get("rich_text", [])
-
-        text = TextInlineFormatter.extract_text_with_formatting(rich_text)
-        return text if text else None
-
-    @classmethod
-    def is_multiline(cls) -> bool:
-        return False
+        rich_list = block.paragraph.rich_text
+        markdown = await TextInlineFormatter.extract_text_with_formatting(rich_list)
+        return markdown or None
 
     @classmethod
-    def get_llm_prompt_content(cls) -> ElementPromptContent:
-        """
-        Returns structured LLM prompt metadata for the paragraph element,
-        including information about supported inline formatting.
-        """
-        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()
+    def get_system_prompt_information(cls) -> Optional[BlockElementMarkdownInformation]:
+        """Get system prompt information for paragraph blocks."""
+        return BlockElementMarkdownInformation(
+            block_type=cls.__name__,
+            description="Paragraph blocks contain regular text content with optional inline formatting",
+            syntax_examples=[
+                "This is a simple paragraph.",
+                "Paragraph with **bold text** and *italic text*.",
+                "Paragraph with [link](https://example.com) and `code`.",
+                "Multiple sentences in one paragraph. Each sentence flows naturally.",
+            ],
+            usage_guidelines="Use for regular text content. Supports inline formatting: **bold**, *italic*, `code`, [links](url). Default block type for plain text.",
         )

notionary/blocks/paragraph/paragraph_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 ParagraphMarkdownBlockParams(BaseModel):

notionary/blocks/paragraph/paragraph_models.py

@@ -0,0 +1,16 @@
+from typing import Literal
+
+from pydantic import BaseModel
+
+from notionary.blocks.rich_text.rich_text_models import RichTextObject
+from notionary.blocks.types import BlockColor
+
+
+class ParagraphBlock(BaseModel):
+    rich_text: list[RichTextObject]
+    color: BlockColor = BlockColor.DEFAULT.value
+
+
+class CreateParagraphBlock(BaseModel):
+    type: Literal["paragraph"] = "paragraph"
+    paragraph: ParagraphBlock

notionary/blocks/pdf/__init__.py

@@ -0,0 +1,13 @@
+from notionary.blocks.pdf.pdf_element import PdfElement
+from notionary.blocks.pdf.pdf_markdown_node import (
+    PdfMarkdownNode,
+    PdfMarkdownNodeParams,
+)
+from notionary.blocks.pdf.pdf_models import CreatePdfBlock
+
+__all__ = [
+    "PdfElement",
+    "CreatePdfBlock",
+    "PdfMarkdownNode",
+    "PdfMarkdownNodeParams",
+]