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

notionary/blocks/pdf/pdf_element.py

@@ -5,35 +5,28 @@ from typing import Optional
 
 from notionary.blocks.base_block_element import BaseBlockElement
 from notionary.blocks.file.file_element_models import ExternalFile, FileBlock, FileType
+from notionary.blocks.mixins.captions import CaptionMixin
+from notionary.blocks.syntax_prompt_builder import BlockElementMarkdownInformation
 from notionary.blocks.models import Block, BlockCreateResult, BlockType
-from notionary.blocks.paragraph.paragraph_models import (
-    CreateParagraphBlock,
-    ParagraphBlock,
-)
 from notionary.blocks.pdf.pdf_models import CreatePdfBlock
-from notionary.blocks.rich_text.rich_text_models import RichTextObject
-from notionary.blocks.rich_text.text_inline_formatter import TextInlineFormatter
 
 
-class PdfElement(BaseBlockElement):
+class PdfElement(BaseBlockElement, CaptionMixin):
     """
     Handles conversion between Markdown PDF embeds and Notion PDF blocks.
 
     Markdown PDF syntax:
-    - [pdf](https://example.com/document.pdf "Caption")     # External URL
-    - [pdf](notion://file_id_here "Caption")                # Notion hosted file
-    - [pdf](upload://upload_id_here "Caption")              # File upload
-    - [pdf](https://example.com/document.pdf)               # Without caption
+    - [pdf](https://example.com/document.pdf) - External URL
+    - [pdf](https://example.com/document.pdf)(caption:Annual Report 2024) - URL with caption
+    - (caption:User Manual)[pdf](https://example.com/manual.pdf) - caption before URL
+    - [pdf](notion://file_id_here)(caption:Notion hosted file) - Notion hosted file
+    - [pdf](upload://upload_id_here)(caption:File upload) - File upload
 
     Supports all three PDF types: external, notion-hosted, and file uploads.
     """
 
-    PATTERN = re.compile(
-        r"^\[pdf\]\("  # prefix
-        r'((?:https?://|notion://|upload://)[^\s\)"]+)'  # URL with protocol
-        r'(?:\s+"([^"]*)")?'  # optional caption
-        r"\)$"
-    )
+    # Flexible pattern that can handle caption in any position
+    PDF_PATTERN = re.compile(r"\[pdf\]\(((?:https?://|notion://|upload://)[^\s\"]+)\)")
 
     @classmethod
     def match_notion(cls, block: Block) -> bool:
@@ -41,51 +34,64 @@ class PdfElement(BaseBlockElement):
         return block.type == BlockType.PDF and block.pdf
 
     @classmethod
-    def markdown_to_notion(cls, text: str) -> BlockCreateResult:
-        """Convert markdown PDF link to Notion FileBlock (used for PDF) followed by an empty paragraph."""
-        match = cls.PATTERN.match(text.strip())
-        if not match:
+    async def markdown_to_notion(cls, text: str) -> BlockCreateResult:
+        """Convert markdown PDF link to Notion FileBlock (used for PDF)."""
+        # Use our own regex to find the PDF URL
+        pdf_match = cls.PDF_PATTERN.search(text.strip())
+        if not pdf_match:
             return None
 
-        url, caption_text = match.group(1), match.group(2) or ""
+        url = pdf_match.group(1)
+
+        # Use mixin to extract caption (if present anywhere in text)
+        caption_text = cls.extract_caption(text.strip())
+        caption_rich_text = cls.build_caption_rich_text(caption_text or "")
 
         # Build FileBlock using FileType enum (reused for PDF)
         pdf_block = FileBlock(
-            type=FileType.EXTERNAL, external=ExternalFile(url=url), caption=[]
+            type=FileType.EXTERNAL,
+            external=ExternalFile(url=url),
+            caption=caption_rich_text,
         )
-        if caption_text.strip():
-            rt = RichTextObject.from_plain_text(caption_text)
-            pdf_block.caption = [rt]
-
-        empty_para = ParagraphBlock(rich_text=[])
 
-        return [
-            CreatePdfBlock(pdf=pdf_block),
-            CreateParagraphBlock(paragraph=empty_para),
-        ]
+        return CreatePdfBlock(pdf=pdf_block)
 
     @classmethod
-    def notion_to_markdown(cls, block: Block) -> Optional[str]:
+    async def notion_to_markdown(cls, block: Block) -> Optional[str]:
         if block.type != BlockType.PDF or not block.pdf:
             return None
 
         pb: FileBlock = block.pdf
 
-        # Determine URL (only external and file types are valid for Markdown)
         if pb.type == FileType.EXTERNAL and pb.external:
             url = pb.external.url
         elif pb.type == FileType.FILE and pb.file:
             url = pb.file.url
         elif pb.type == FileType.FILE_UPLOAD:
-            # Uploaded PDF has no stable URL for Markdown
             return None
         else:
             return None
 
-        if not pb.caption:
-            return f"[pdf]({url})"
+        result = f"[pdf]({url})"
+
+        # Add caption if present
+        caption_markdown = await cls.format_caption_for_markdown(pb.caption or [])
+        if caption_markdown:
+            result += caption_markdown
 
-        caption_md = TextInlineFormatter.extract_text_with_formatting(pb.caption)
-        if caption_md:
-            return f'[pdf]({url} "{caption_md}")'
-        return f"[pdf]({url})"
+        return result
+
+    @classmethod
+    def get_system_prompt_information(cls) -> Optional[BlockElementMarkdownInformation]:
+        """Get system prompt information for PDF blocks."""
+        return BlockElementMarkdownInformation(
+            block_type=cls.__name__,
+            description="PDF blocks embed and display PDF documents from external URLs with optional captions",
+            syntax_examples=[
+                "[pdf](https://example.com/document.pdf)",
+                "[pdf](https://example.com/report.pdf)(caption:Annual Report 2024)",
+                "(caption:User Manual)[pdf](https://example.com/manual.pdf)",
+                "[pdf](https://example.com/guide.pdf)(caption:**Important** documentation)",
+            ],
+            usage_guidelines="Use for embedding PDF documents that can be viewed inline. Supports external URLs and Notion-hosted files. Caption supports rich text formatting and should describe the PDF content.",
+        )

notionary/blocks/pdf/pdf_markdown_node.py

@@ -5,6 +5,7 @@ from typing import Optional
 from pydantic import BaseModel
 
 from notionary.markdown.markdown_node import MarkdownNode
+from notionary.blocks.mixins.captions import CaptionMarkdownNodeMixin
 
 
 class PdfMarkdownNodeParams(BaseModel):
@@ -12,10 +13,9 @@ class PdfMarkdownNodeParams(BaseModel):
     caption: Optional[str] = None
 
 
-class PdfMarkdownNode(MarkdownNode):
+class PdfMarkdownNode(MarkdownNode, CaptionMarkdownNodeMixin):
     """
     Programmatic interface for creating Notion-style Markdown PDF embeds.
-    Example: [pdf](https://example.com/document.pdf "My Caption")
     """
 
     def __init__(self, url: str, caption: Optional[str] = None):
@@ -27,9 +27,11 @@ class PdfMarkdownNode(MarkdownNode):
         return cls(url=params.url, caption=params.caption)
 
     def to_markdown(self) -> str:
+        """Return the Markdown representation.
+
+        Examples:
+        - [pdf](https://example.com/document.pdf)
+        - [pdf](https://example.com/document.pdf)(caption:Critical safety information)
         """
-        Convert to markdown as [pdf](url "caption") or [pdf](url) if caption is empty.
-        """
-        if self.caption:
-            return f'[pdf]({self.url} "{self.caption}")'
-        return f"[pdf]({self.url})"
+        base_markdown = f"[pdf]({self.url})"
+        return self.append_caption_to_markdown(base_markdown, self.caption)

notionary/blocks/quote/quote_element.py

@@ -4,6 +4,7 @@ import re
 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.quote.quote_models import CreateQuoteBlock, QuoteBlock
 from notionary.blocks.rich_text.text_inline_formatter import TextInlineFormatter
@@ -15,19 +16,19 @@ class QuoteElement(BaseBlockElement):
     Handles conversion between Markdown quotes and Notion quote blocks.
 
     Markdown quote syntax:
-    - [quote](Simple quote text)
+    - > Simple quote text
 
     Only single-line quotes without author metadata.
     """
 
-    PATTERN = re.compile(r"^\[quote\]\(([^\n\r]+)\)$")
+    PATTERN = re.compile(r"^>\s*(.+)$")
 
     @classmethod
     def match_notion(cls, block: Block) -> bool:
         return block.type == BlockType.QUOTE and block.quote
 
     @classmethod
-    def markdown_to_notion(cls, text: str) -> BlockCreateResult:
+    async def markdown_to_notion(cls, text: str) -> BlockCreateResult:
         """Convert markdown quote to Notion QuoteBlock."""
         match = cls.PATTERN.match(text.strip())
         if not match:
@@ -37,22 +38,38 @@ class QuoteElement(BaseBlockElement):
         if not content:
             return None
 
-        # Parse inline formatting into rich text objects
-        rich_text = TextInlineFormatter.parse_inline_formatting(content)
+        # Reject multiline quotes
+        if "\n" in content or "\r" in content:
+            return None
+
+        rich_text = await TextInlineFormatter.parse_inline_formatting(content)
 
-        # Return a typed QuoteBlock
         quote_content = QuoteBlock(rich_text=rich_text, color=BlockColor.DEFAULT)
         return CreateQuoteBlock(quote=quote_content)
 
     @classmethod
-    def notion_to_markdown(cls, block: Block) -> Optional[str]:
+    async def notion_to_markdown(cls, block: Block) -> Optional[str]:
         if block.type != BlockType.QUOTE or not block.quote:
             return None
 
         rich = block.quote.rich_text
-        text = TextInlineFormatter.extract_text_with_formatting(rich)
+        text = await TextInlineFormatter.extract_text_with_formatting(rich)
 
         if not text.strip():
             return None
 
-        return f"[quote]({text.strip()})"
+        return f"> {text.strip()}"
+
+    @classmethod
+    def get_system_prompt_information(cls) -> Optional[BlockElementMarkdownInformation]:
+        """Get system prompt information for quote blocks."""
+        return BlockElementMarkdownInformation(
+            block_type=cls.__name__,
+            description="Quote blocks display highlighted quotations or emphasized text",
+            syntax_examples=[
+                "> This is an important quote",
+                "> The only way to do great work is to love what you do",
+                "> Innovation distinguishes between a leader and a follower",
+            ],
+            usage_guidelines="Use for quotations, important statements, or text that should be visually emphasized. Content should be meaningful and stand out from regular paragraphs.",
+        )

notionary/blocks/quote/quote_markdown_node.py

@@ -12,7 +12,7 @@ class QuoteMarkdownBlockParams(BaseModel):
 class QuoteMarkdownNode(MarkdownNode):
     """
     Programmatic interface for creating Notion-style quote blocks.
-    Example: [quote](This is a quote)
+    Example: > This is a quote
     """
 
     def __init__(self, text: str):
@@ -23,4 +23,4 @@ class QuoteMarkdownNode(MarkdownNode):
         return cls(text=params.text)
 
     def to_markdown(self) -> str:
-        return f"[quote]({self.text})"
+        return f"> {self.text}"

notionary/blocks/registry/block_registry.py

@@ -3,11 +3,8 @@ from __future__ import annotations
 from typing import Optional, Type
 
 from notionary.blocks.base_block_element import BaseBlockElement
-from notionary.blocks.models import Block, BlockCreateResult
 from notionary.blocks.registry.block_registry_builder import BlockRegistryBuilder
 from notionary.telemetry import (
-    MarkdownToNotionConversionEvent,
-    NotionToMarkdownConversionEvent,
     ProductTelemetry,
 )
 
@@ -61,6 +58,7 @@ class BlockRegistry:
             .with_equation()
             .with_table_of_contents()
             .with_breadcrumbs()
+            .with_child_database()
             .with_paragraphs()  # position here is important - its a fallback!
         )
 
@@ -92,49 +90,6 @@ class BlockRegistry:
         """
         return element_class.__name__ in self._builder._elements
 
-    def find_markdown_handler(self, text: str) -> Optional[Type[BaseBlockElement]]:
-        """Find an element that can handle the given markdown text."""
-        for element in self._builder._elements.values():
-            if element.match_markdown(text):
-                return element
-        return None
-
-    def markdown_to_notion(self, text: str) -> "BlockCreateResult":
-        """Convert markdown to Notion block using registered elements."""
-        handler = self.find_markdown_handler(text)
-
-        if handler:
-            self.telemetry.capture(
-                MarkdownToNotionConversionEvent(
-                    handler_element_name=handler.__name__,
-                )
-            )
-
-            return handler.markdown_to_notion(text)
-        return None
-
-    def notion_to_markdown(self, block: "Block") -> Optional[str]:
-        """Convert Notion block to markdown using registered elements."""
-        handler = self._find_notion_handler(block)
-
-        if not handler:
-            return None
-
-        self.telemetry.capture(
-            NotionToMarkdownConversionEvent(
-                handler_element_name=handler.__name__,
-            )
-        )
-
-        return handler.notion_to_markdown(block)
-
     def get_elements(self) -> list[Type[BaseBlockElement]]:
         """Get all registered elements."""
         return list(self._builder._elements.values())
-
-    def _find_notion_handler(self, block: Block) -> Optional[Type[BaseBlockElement]]:
-        """Find an element that can handle the given Notion block."""
-        for element in self._builder._elements.values():
-            if element.match_notion(block):
-                return element
-        return None

notionary/blocks/registry/block_registry_builder.py

@@ -9,6 +9,7 @@ from notionary.blocks.bookmark import BookmarkElement
 from notionary.blocks.breadcrumbs import BreadcrumbElement
 from notionary.blocks.bulleted_list import BulletedListElement
 from notionary.blocks.callout import CalloutElement
+from notionary.blocks.child_database import ChildDatabaseElement
 from notionary.blocks.code import CodeElement
 from notionary.blocks.column import ColumnElement, ColumnListElement
 from notionary.blocks.divider import DividerElement
@@ -70,6 +71,7 @@ class BlockRegistryBuilder:
             .with_equation()
             .with_table_of_contents()
             .with_breadcrumbs()
+            .with_child_database()
         ).build()
 
     def remove_element(self, element_class: Type[BaseBlockElement]) -> Self:
@@ -151,6 +153,9 @@ class BlockRegistryBuilder:
     def with_breadcrumbs(self) -> Self:
         return self._add_element(BreadcrumbElement)
 
+    def with_child_database(self) -> Self:
+        return self._add_element(ChildDatabaseElement)
+
     def without_headings(self) -> Self:
         return self.remove_element(HeadingElement)
 
@@ -213,6 +218,9 @@ class BlockRegistryBuilder:
     def without_breadcrumbs(self) -> Self:
         return self.remove_element(BreadcrumbElement)
 
+    def without_child_database(self) -> Self:
+        return self.remove_element(ChildDatabaseElement)
+
     def build(self) -> BlockRegistry:
         """
         Build and return the configured BlockRegistry instance.

notionary/blocks/rich_text/rich_text_models.py

@@ -1,9 +1,35 @@
 from __future__ import annotations
 
+from enum import Enum
 from typing import Optional
 
 from pydantic import BaseModel
-from typing_extensions import Literal
+
+
+class RichTextType(str, Enum):
+    """Types of rich text objects."""
+
+    TEXT = "text"
+    MENTION = "mention"
+    EQUATION = "equation"
+
+
+class MentionType(str, Enum):
+    """Types of mention objects."""
+
+    USER = "user"
+    PAGE = "page"
+    DATABASE = "database"
+    DATE = "date"
+    LINK_PREVIEW = "link_preview"
+    TEMPLATE_MENTION = "template_mention"
+
+
+class TemplateMentionType(str, Enum):
+    """Types of template mentions."""
+
+    USER = "template_mention_user"
+    DATE = "template_mention_date"
 
 
 class TextAnnotations(BaseModel):
@@ -53,13 +79,11 @@ class MentionDate(BaseModel):
 
 class MentionTemplateMention(BaseModel):
     # Notion hat zwei Template-Mention-Typen
-    type: Literal["template_mention_user", "template_mention_date"]
+    type: TemplateMentionType
 
 
 class MentionObject(BaseModel):
-    type: Literal[
-        "user", "page", "database", "date", "link_preview", "template_mention"
-    ]
+    type: MentionType
     user: Optional[MentionUserRef] = None
     page: Optional[MentionPageRef] = None
     database: Optional[MentionDatabaseRef] = None
@@ -69,7 +93,7 @@ class MentionObject(BaseModel):
 
 
 class RichTextObject(BaseModel):
-    type: Literal["text", "mention", "equation"] = "text"
+    type: RichTextType = RichTextType.TEXT
 
     text: Optional[TextContent] = None
     annotations: Optional[TextAnnotations] = None
@@ -83,26 +107,30 @@ class RichTextObject(BaseModel):
     @classmethod
     def from_plain_text(cls, content: str, **ann) -> RichTextObject:
         return cls(
-            type="text",
+            type=RichTextType.TEXT,
             text=TextContent(content=content),
             annotations=TextAnnotations(**ann) if ann else TextAnnotations(),
             plain_text=content,
         )
 
     @classmethod
-    def for_code_block(cls, content: str) -> RichTextObject:
-        # keine annotations setzen → Notion Code-Highlight bleibt an
+    def for_caption(cls, content: str) -> RichTextObject:
         return cls(
-            type="text",
+            type=RichTextType.TEXT,
             text=TextContent(content=content),
             annotations=None,
             plain_text=content,
         )
 
+    @classmethod
+    def for_code_block(cls, content: str) -> RichTextObject:
+        # keine annotations setzen → Notion Code-Highlight bleibt an
+        return cls.for_caption(content)
+
     @classmethod
     def for_link(cls, content: str, url: str, **ann) -> RichTextObject:
         return cls(
-            type="text",
+            type=RichTextType.TEXT,
             text=TextContent(content=content, link=LinkObject(url=url)),
             annotations=TextAnnotations(**ann) if ann else TextAnnotations(),
             plain_text=content,
@@ -111,25 +139,29 @@ class RichTextObject(BaseModel):
     @classmethod
     def mention_user(cls, user_id: str) -> RichTextObject:
         return cls(
-            type="mention",
-            mention=MentionObject(type="user", user=MentionUserRef(id=user_id)),
+            type=RichTextType.MENTION,
+            mention=MentionObject(
+                type=MentionType.USER, user=MentionUserRef(id=user_id)
+            ),
             annotations=TextAnnotations(),
         )
 
     @classmethod
     def mention_page(cls, page_id: str) -> RichTextObject:
         return cls(
-            type="mention",
-            mention=MentionObject(type="page", page=MentionPageRef(id=page_id)),
+            type=RichTextType.MENTION,
+            mention=MentionObject(
+                type=MentionType.PAGE, page=MentionPageRef(id=page_id)
+            ),
             annotations=TextAnnotations(),
         )
 
     @classmethod
     def mention_database(cls, database_id: str) -> RichTextObject:
         return cls(
-            type="mention",
+            type=RichTextType.MENTION,
             mention=MentionObject(
-                type="database", database=MentionDatabaseRef(id=database_id)
+                type=MentionType.DATABASE, database=MentionDatabaseRef(id=database_id)
             ),
             annotations=TextAnnotations(),
         )
@@ -137,9 +169,9 @@ class RichTextObject(BaseModel):
     @classmethod
     def mention_link_preview(cls, url: str) -> RichTextObject:
         return cls(
-            type="mention",
+            type=RichTextType.MENTION,
             mention=MentionObject(
-                type="link_preview", link_preview=MentionLinkPreview(url=url)
+                type=MentionType.LINK_PREVIEW, link_preview=MentionLinkPreview(url=url)
             ),
             annotations=TextAnnotations(),
         )
@@ -149,9 +181,10 @@ class RichTextObject(BaseModel):
         cls, start: str, end: str | None = None, time_zone: str | None = None
     ) -> RichTextObject:
         return cls(
-            type="mention",
+            type=RichTextType.MENTION,
             mention=MentionObject(
-                type="date", date=MentionDate(start=start, end=end, time_zone=time_zone)
+                type=MentionType.DATE,
+                date=MentionDate(start=start, end=end, time_zone=time_zone),
             ),
             annotations=TextAnnotations(),
         )
@@ -159,10 +192,10 @@ class RichTextObject(BaseModel):
     @classmethod
     def mention_template_user(cls) -> RichTextObject:
         return cls(
-            type="mention",
+            type=RichTextType.MENTION,
             mention=MentionObject(
-                type="template_mention",
-                template_mention=MentionTemplateMention(type="template_mention_user"),
+                type=MentionType.TEMPLATE_MENTION,
+                template_mention=MentionTemplateMention(type=TemplateMentionType.USER),
             ),
             annotations=TextAnnotations(),
         )
@@ -170,10 +203,10 @@ class RichTextObject(BaseModel):
     @classmethod
     def mention_template_date(cls) -> RichTextObject:
         return cls(
-            type="mention",
+            type=RichTextType.MENTION,
             mention=MentionObject(
-                type="template_mention",
-                template_mention=MentionTemplateMention(type="template_mention_date"),
+                type=MentionType.TEMPLATE_MENTION,
+                template_mention=MentionTemplateMention(type=TemplateMentionType.DATE),
             ),
             annotations=TextAnnotations(),
         )
@@ -181,8 +214,8 @@ class RichTextObject(BaseModel):
     @classmethod
     def equation_inline(cls, expression: str) -> RichTextObject:
         return cls(
-            type="equation",
+            type=RichTextType.EQUATION,
             equation=EquationObject(expression=expression),
             annotations=TextAnnotations(),
-            plain_text=expression,  # Notion liefert plain_text serverseitig; für Roundtrip hilfreich
+            plain_text=expression,
         )