notionary 0.2.21__py3-none-any.whl → 0.2.22__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/name_to_id_resolver.py

@@ -0,0 +1,205 @@
+from __future__ import annotations
+
+import logging
+from contextlib import contextmanager
+from typing import Optional
+
+from notionary.user.notion_user_manager import NotionUserManager
+from notionary.util import format_uuid
+from notionary.util.fuzzy import find_best_match
+
+
+class NameIdResolver:
+    """
+    Bidirectional resolver for Notion page and database names and IDs.
+    """
+
+    def __init__(
+        self,
+        *,
+        token: Optional[str] = None,
+        search_limit: int = 10,
+    ):
+        """
+        Initialize the resolver with a Notion workspace.
+        """
+        from notionary import NotionWorkspace
+
+        self.workspace = NotionWorkspace(token=token)
+        self.notion_user_manager = NotionUserManager(token=token)
+        self.search_limit = search_limit
+
+    async def resolve_page_id(self, name: str) -> Optional[str]:
+        """
+        Convert a page name to its Notion page ID.
+        Specifically searches only pages, not databases.
+        """
+        if not name:
+            return None
+
+        cleaned_name = name.strip()
+
+        # Return if already a valid Notion ID
+        formatted_uuid = format_uuid(cleaned_name)
+        if formatted_uuid:
+            return formatted_uuid
+
+        # Search for page by name
+        return await self._resolve_page_id(cleaned_name)
+
+    async def resolve_database_id(self, name: str) -> Optional[str]:
+        """
+        Convert a database name to its Notion database ID.
+        Specifically searches only databases, not pages.
+        """
+        if not name:
+            return None
+
+        cleaned_name = name.strip()
+
+        formatted_uuid = format_uuid(cleaned_name)
+        if formatted_uuid:
+            return formatted_uuid
+
+        return await self._resolve_database_id(cleaned_name)
+
+    async def resolve_page_name(self, page_id: str) -> Optional[str]:
+        """
+        Convert a Notion page ID to its human-readable title.
+        """
+        if not page_id:
+            return None
+
+        formatted_id = format_uuid(page_id)
+        if not formatted_id:
+            return None
+
+        try:
+            from notionary import NotionPage
+
+            page = await NotionPage.from_page_id(formatted_id)
+            return page.title if page else None
+        except Exception:
+            return None
+
+    async def resolve_database_name(self, database_id: str) -> Optional[str]:
+        """
+        Convert a Notion database ID to its human-readable title.
+        """
+        if not database_id:
+            return None
+
+        # Validate and format UUID
+        formatted_id = format_uuid(database_id)
+        if not formatted_id:
+            return None
+
+        try:
+            from notionary.database import NotionDatabase
+
+            database = await NotionDatabase.from_database_id(formatted_id)
+            return database.title if database else None
+        except Exception:
+            return None
+
+    async def resolve_user_id(self, name: str) -> Optional[str]:
+        """
+        Convert a user name to its Notion user ID.
+        Specifically searches only users.
+        """
+        if not name:
+            return None
+
+        cleaned_name = name.strip()
+
+        # Return if already a valid Notion ID
+        formatted_uuid = format_uuid(cleaned_name)
+        if formatted_uuid:
+            return formatted_uuid
+
+        # Search for user by name
+        return await self._resolve_user_id(cleaned_name)
+
+    async def resolve_user_name(self, user_id: str) -> Optional[str]:
+        """
+        Convert a Notion user ID to its human-readable name.
+
+        Args:
+            user_id: Notion user ID to resolve
+
+        Returns:
+            User name if found, None if not found or inaccessible
+        """
+        if not user_id:
+            return None
+
+        # Validate and format UUID
+        formatted_id = format_uuid(user_id)
+        if not formatted_id:
+            return None
+
+        try:
+            user = await self.notion_user_manager.get_user_by_id(formatted_id)
+            return user.name if user else None
+        except Exception:
+            return None
+
+    async def _resolve_user_id(self, name: str) -> Optional[str]:
+        """Search for users matching the name."""
+        try:
+            users = await self.notion_user_manager.find_users_by_name(name)
+
+            if not users:
+                return None
+
+            # Use fuzzy matching to find best match
+            best_match = find_best_match(
+                query=name,
+                items=users,
+                text_extractor=lambda user: user.name or "",
+            )
+
+            return best_match.item.id if best_match else None
+        except Exception:
+            return None
+
+    async def _resolve_page_id(self, name: str) -> Optional[str]:
+        """Search for pages matching the name."""
+        search_results = await self.workspace.search_pages(
+            query=name, limit=self.search_limit
+        )
+
+        return self._find_best_fuzzy_match(query=name, candidate_objects=search_results)
+
+    async def _resolve_database_id(self, name: str) -> Optional[str]:
+        """Search for databases matching the name."""
+        search_results = await self.workspace.search_databases(
+            query=name, limit=self.search_limit
+        )
+
+        return self._find_best_fuzzy_match(query=name, candidate_objects=search_results)
+
+    def _find_best_fuzzy_match(
+        self, query: str, candidate_objects: list
+    ) -> Optional[str]:
+        """
+        Find the best fuzzy match among candidate objects using existing fuzzy matching logic.
+
+        Args:
+            query: The search query to match against
+            candidate_objects: Objects (pages or databases) with .id and .title attributes
+
+        Returns:
+            ID of best match, or None if no match meets threshold
+        """
+        if not candidate_objects:
+            return None
+
+        # Use existing fuzzy matching logic
+        best_match = find_best_match(
+            query=query,
+            items=candidate_objects,
+            text_extractor=lambda obj: obj.title,
+        )
+
+        return best_match.item.id if best_match else None