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

notionary/blocks/video/video_element.py

@@ -5,34 +5,27 @@ 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
-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
 from notionary.blocks.types import BlockType
 from notionary.blocks.video.video_element_models import CreateVideoBlock
 
 
-class VideoElement(BaseBlockElement):
+class VideoElement(BaseBlockElement, CaptionMixin):
     """
     Handles conversion between Markdown video embeds and Notion video blocks.
 
     Markdown video syntax:
     - [video](https://example.com/video.mp4) - URL only
-    - [video](https://example.com/video.mp4 "Caption") - URL + caption
+    - [video](https://example.com/video.mp4)(caption:Demo Video) - URL with caption
+    - (caption:Tutorial video)[video](https://youtube.com/watch?v=abc123) - caption before URL
 
     Supports YouTube, Vimeo, and direct file URLs.
     """
 
-    PATTERN = re.compile(
-        r"^\[video\]\("  # prefix
-        r"(https?://[^\s\"]+)"  # URL
-        r"(?:\s+\"([^\"]+)\")?"  # optional caption
-        r"\)$"
-    )
+    # Flexible pattern that can handle caption in any position
+    VIDEO_PATTERN = re.compile(r"\[video\]\((https?://[^\s\"]+)\)")
 
     YOUTUBE_PATTERNS = [
         re.compile(r"(?:https?://)?(?:www\.)?youtube\.com/watch\?v=([\w-]{11})"),
@@ -44,34 +37,33 @@ class VideoElement(BaseBlockElement):
         return block.type == BlockType.VIDEO and block.video
 
     @classmethod
-    def markdown_to_notion(cls, text: str) -> BlockCreateResult:
-        """Convert markdown video syntax to a Notion VideoBlock plus an empty paragraph."""
-        match = cls.PATTERN.match(text.strip())
-        if not match:
+    async def markdown_to_notion(cls, text: str) -> BlockCreateResult:
+        """Convert markdown video syntax to a Notion VideoBlock."""
+        # Use our own regex to find the video URL
+        video_match = cls.VIDEO_PATTERN.search(text.strip())
+        if not video_match:
             return None
 
-        url, caption_text = match.group(1), match.group(2) or ""
+        url = video_match.group(1)
 
         vid_id = cls._get_youtube_id(url)
         if vid_id:
             url = f"https://www.youtube.com/watch?v={vid_id}"
 
+        # 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 "")
+
         video_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.strip())
-            video_block.caption = [rt]
-
-        empty_para = ParagraphBlock(rich_text=[])
 
-        return [
-            CreateVideoBlock(video=video_block),
-            CreateParagraphBlock(paragraph=empty_para),
-        ]
+        return CreateVideoBlock(video=video_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.VIDEO or not block.video:
             return None
 
@@ -85,17 +77,14 @@ class VideoElement(BaseBlockElement):
         else:
             return None  # (file_upload o.ä. hier nicht supported)
 
-        # Captions
-        captions = fo.caption or []
-        if not captions:
-            return f"[video]({url})"
+        result = f"[video]({url})"
 
-        caption_text = "".join(
-            (rt.plain_text or TextInlineFormatter.extract_text_with_formatting([rt]))
-            for rt in captions
-        )
+        # Add caption if present
+        caption_markdown = await cls.format_caption_for_markdown(fo.caption or [])
+        if caption_markdown:
+            result += caption_markdown
 
-        return f'[video]({url} "{caption_text}")'
+        return result
 
     @classmethod
     def _get_youtube_id(cls, url: str) -> Optional[str]:
@@ -104,3 +93,19 @@ class VideoElement(BaseBlockElement):
             if m:
                 return m.group(1)
         return None
+
+    @classmethod
+    def get_system_prompt_information(cls) -> Optional[BlockElementMarkdownInformation]:
+        """Get system prompt information for video blocks."""
+        return BlockElementMarkdownInformation(
+            block_type=cls.__name__,
+            description="Video blocks embed videos from external URLs like YouTube, Vimeo, or direct video files",
+            syntax_examples=[
+                "[video](https://youtube.com/watch?v=abc123)",
+                "[video](https://vimeo.com/123456789)",
+                "[video](https://example.com/video.mp4)(caption:Demo Video)",
+                "(caption:Tutorial)[video](https://youtu.be/abc123)",
+                "[video](https://youtube.com/watch?v=xyz)(caption:**Important** tutorial)",
+            ],
+            usage_guidelines="Use for embedding videos from supported platforms or direct video file URLs. Supports YouTube, Vimeo, and direct video files. Caption supports rich text formatting and describes the video content.",
+        )

notionary/blocks/video/video_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 VideoMarkdownBlockParams(BaseModel):
@@ -12,10 +13,9 @@ class VideoMarkdownBlockParams(BaseModel):
     caption: Optional[str] = None
 
 
-class VideoMarkdownNode(MarkdownNode):
+class VideoMarkdownNode(MarkdownNode, CaptionMarkdownNodeMixin):
     """
     Programmatic interface for creating Notion-style video blocks.
-    Example: [video](https://example.com/video.mp4 "Optional caption")
     """
 
     def __init__(self, url: str, caption: Optional[str] = None):
@@ -27,6 +27,11 @@ class VideoMarkdownNode(MarkdownNode):
         return cls(url=params.url, caption=params.caption)
 
     def to_markdown(self) -> str:
-        if self.caption:
-            return f'[video]({self.url} "{self.caption}")'
-        return f"[video]({self.url})"
+        """Return the Markdown representation.
+
+        Examples:
+        - [video](https://example.com/movie.mp4)
+        - [video](https://www.youtube.com/watch?v=dQw4w9WgXcQ)(caption:Music Video)
+        """
+        base_markdown = f"[video]({self.url})"
+        return self.append_caption_to_markdown(base_markdown, self.caption)

notionary/comments/__init__.py

@@ -0,0 +1,26 @@
+from .client import CommentClient
+from .models import (
+    Comment,
+    CommentAttachment,
+    CommentAttachmentExternal,
+    CommentAttachmentFile,
+    CommentDisplayName,
+    CommentListResponse,
+    CommentParent,
+    FileWithExpiry,
+    UserRef,
+)
+
+
+__all__ = [
+    "CommentClient",
+    "Comment",
+    "CommentAttachment",
+    "CommentAttachmentExternal",
+    "CommentAttachmentFile",
+    "CommentDisplayName",
+    "CommentListResponse",
+    "CommentParent",
+    "FileWithExpiry",
+    "UserRef",
+]

notionary/comments/client.py

@@ -0,0 +1,211 @@
+from __future__ import annotations
+
+from typing import Any, AsyncGenerator, Optional
+
+from notionary.base_notion_client import BaseNotionClient
+from notionary.blocks.rich_text.rich_text_models import RichTextObject
+from notionary.comments.models import Comment, CommentListResponse
+
+
+class CommentClient(BaseNotionClient):
+    """
+    Client for Notion comment operations.
+    Uses Pydantic models for typed responses.
+
+    Notes / API constraints:
+    - Listing returns only *unresolved* comments. Resolved comments are not returned.
+    - You can create:
+        1) a top-level comment on a page
+        2) a reply in an existing discussion (requires discussion_id)
+      You cannot start a brand-new inline thread via API.
+    - Read/Insert comment capabilities must be enabled for the integration.
+    """
+
+    async def retrieve_comment(self, comment_id: str) -> Comment:
+        """
+        Retrieve a single Comment object by its ID.
+
+        Requires the integration to have "Read comment" capability enabled.
+        Raises 403 (restricted_resource) without it.
+        """
+        resp = await self.get(f"comments/{comment_id}")
+        if resp is None:
+            raise RuntimeError("Failed to retrieve comment.")
+        return Comment.model_validate(resp)
+
+    async def list_all_comments_for_page(
+        self, *, page_id: str, page_size: int = 100
+    ) -> list[Comment]:
+        """Returns all unresolved comments for a page (handles pagination)."""
+        results: list[Comment] = []
+        cursor: str | None = None
+        while True:
+            page = await self.list_comments(
+                block_id=page_id, start_cursor=cursor, page_size=page_size
+            )
+            results.extend(page.results)
+            if not page.has_more:
+                break
+            cursor = page.next_cursor
+        return results
+
+    async def list_comments(
+        self,
+        *,
+        block_id: str,
+        start_cursor: Optional[str] = None,
+        page_size: Optional[int] = None,
+    ) -> CommentListResponse:
+        """
+        List unresolved comments for a page or block.
+
+        Args:
+            block_id: Page ID or block ID to list comments for.
+            start_cursor: Pagination cursor.
+            page_size: Max items per page (<= 100).
+
+        Returns:
+            CommentListResponse with results, next_cursor, has_more, etc.
+        """
+        params: dict[str, str | int] = {"block_id": block_id}
+        if start_cursor:
+            params["start_cursor"] = start_cursor
+        if page_size:
+            params["page_size"] = page_size
+
+        resp = await self.get("comments", params=params)
+        if resp is None:
+            raise RuntimeError("Failed to list comments.")
+        return CommentListResponse.model_validate(resp)
+
+    async def iter_comments(
+        self,
+        *,
+        block_id: str,
+        page_size: int = 100,
+    ) -> AsyncGenerator[Comment, None]:
+        """
+        Async generator over all unresolved comments for a given page/block.
+        Handles pagination under the hood.
+        """
+        cursor: Optional[str] = None
+        while True:
+            page = await self.list_comments(
+                block_id=block_id, start_cursor=cursor, page_size=page_size
+            )
+            for item in page.results:
+                yield item
+            if not page.has_more:
+                break
+            cursor = page.next_cursor
+
+    async def create_comment_on_page(
+        self,
+        *,
+        page_id: str,
+        text: str,
+        display_name: Optional[dict] = None,
+        attachments: Optional[list[dict]] = None,
+    ) -> Comment:
+        """
+        Create a top-level comment on a page.
+
+        Args:
+            page_id: Target page ID.
+            text: Plain text content for the comment (rich_text will be constructed).
+            display_name: Optional "Comment Display Name" object to override author label.
+            attachments: Optional list of "Comment Attachment" objects (max 3).
+
+        Returns:
+            The created Comment object.
+        """
+        body: dict = {
+            "parent": {"page_id": page_id},
+            "rich_text": [{"type": "text", "text": {"content": text}}],
+        }
+        if display_name:
+            body["display_name"] = display_name
+        if attachments:
+            body["attachments"] = attachments
+
+        resp = await self.post("comments", data=body)
+        if resp is None:
+            raise RuntimeError("Failed to create page comment.")
+        return Comment.model_validate(resp)
+
+    async def create_comment(
+        self,
+        *,
+        page_id: Optional[str] = None,
+        discussion_id: Optional[str] = None,
+        content: Optional[str] = None,
+        rich_text: Optional[list[RichTextObject]] = None,
+        display_name: Optional[dict[str, Any]] = None,
+        attachments: Optional[list[dict[str, Any]]] = None,
+    ) -> Comment:
+        """
+        Create a comment on a page OR reply to an existing discussion.
+
+        Rules:
+        - Exactly one of page_id or discussion_id must be provided.
+        - Provide either rich_text OR content (plain text). If both given, rich_text wins.
+        - Up to 3 attachments allowed by Notion.
+        """
+        # validate parent
+        if (page_id is None) == (discussion_id is None):
+            raise ValueError("Specify exactly one parent: page_id OR discussion_id")
+
+        # build rich_text if only content is provided
+        rt = rich_text if rich_text else None
+        if rt is None:
+            if not content:
+                raise ValueError("Provide either 'rich_text' or 'content'.")
+            rt = [{"type": "text", "text": {"content": content}}]
+
+        body: dict[str, Any] = {"rich_text": rt}
+        if page_id:
+            body["parent"] = {"page_id": page_id}
+        else:
+            body["discussion_id"] = discussion_id
+
+        if display_name:
+            body["display_name"] = display_name
+        if attachments:
+            body["attachments"] = attachments
+
+        resp = await self.post("comments", data=body)
+        if resp is None:
+            raise RuntimeError("Failed to create comment.")
+        return Comment.model_validate(resp)
+
+    # ---------- Convenience wrappers ----------
+
+    async def create_comment_on_page(
+        self,
+        *,
+        page_id: str,
+        text: str,
+        display_name: Optional[dict] = None,
+        attachments: Optional[list[dict]] = None,
+    ) -> Comment:
+        return await self.create_comment(
+            page_id=page_id,
+            content=text,
+            display_name=display_name,
+            attachments=attachments,
+        )
+
+    async def reply_to_discussion(
+        self,
+        *,
+        discussion_id: str,
+        text: str,
+        display_name: Optional[dict] = None,
+        attachments: Optional[list[dict]] = None,
+    ) -> Comment:
+        return await self.create_comment(
+            discussion_id=discussion_id,
+            content=text,
+            display_name=display_name,
+            attachments=attachments,
+        )

notionary/comments/models.py

@@ -0,0 +1,129 @@
+# notionary/comments/models.py
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Literal, Optional, Union
+
+from pydantic import BaseModel, Field, ConfigDict
+
+from notionary.blocks.rich_text import RichTextObject
+
+
+class UserRef(BaseModel):
+    """Minimal Notion user reference."""
+
+    model_config = ConfigDict(extra="ignore")
+    object: Literal["user"] = "user"
+    id: str
+
+
+class CommentParent(BaseModel):
+    """
+    Parent of a comment. Can be page_id or block_id.
+    Notion responds with the active one; the other remains None.
+    """
+
+    model_config = ConfigDict(extra="ignore")
+    type: Literal["page_id", "block_id"]
+    page_id: Optional[str] = None
+    block_id: Optional[str] = None
+
+
+class FileWithExpiry(BaseModel):
+    """File object with temporary URL (common Notion pattern)."""
+
+    model_config = ConfigDict(extra="ignore")
+    url: str
+    expiry_time: Optional[datetime] = None
+
+
+class CommentAttachmentFile(BaseModel):
+    """Attachment stored by Notion with expiring download URL."""
+
+    model_config = ConfigDict(extra="ignore")
+    type: Literal["file"] = "file"
+    name: Optional[str] = None
+    file: FileWithExpiry
+
+
+class CommentAttachmentExternal(BaseModel):
+    """External attachment referenced by URL."""
+
+    model_config = ConfigDict(extra="ignore")
+    type: Literal["external"] = "external"
+    name: Optional[str] = None
+    external: dict  # {"url": "..."} – kept generic
+
+
+CommentAttachment = Union[CommentAttachmentFile, CommentAttachmentExternal]
+
+
+# ---------------------------
+# Display name override (optional)
+# ---------------------------
+
+
+class CommentDisplayName(BaseModel):
+    """
+    Optional display name override for comments created by an integration.
+    Example: {"type": "integration", "resolved_name": "int"}.
+    """
+
+    model_config = ConfigDict(extra="ignore")
+    type: str
+    resolved_name: Optional[str] = None
+
+
+# ---------------------------
+# Core Comment object
+# ---------------------------
+
+
+class Comment(BaseModel):
+    """
+    Notion Comment object as returned by:
+      - GET /v1/comments/{comment_id} (retrieve)
+      - GET /v1/comments?block_id=... (list -> in results[])
+      - POST /v1/comments (create)
+    """
+
+    model_config = ConfigDict(extra="ignore")
+
+    object: Literal["comment"] = "comment"
+    id: str
+
+    parent: CommentParent
+    discussion_id: str
+
+    created_time: datetime
+    last_edited_time: datetime
+
+    created_by: UserRef
+
+    rich_text: list[RichTextObject] = Field(default_factory=list)
+
+    # Optional fields that may appear depending on capabilities/payload
+    display_name: Optional[CommentDisplayName] = None
+    attachments: Optional[list[CommentAttachment]] = None
+
+
+# ---------------------------
+# List envelope (for list-comments)
+# ---------------------------
+
+
+class CommentListResponse(BaseModel):
+    """
+    Envelope for GET /v1/comments?block_id=...
+    """
+
+    model_config = ConfigDict(extra="ignore")
+
+    object: Literal["list"] = "list"
+    results: list[Comment] = Field(default_factory=list)
+    next_cursor: Optional[str] = None
+    has_more: bool = False
+
+    # Notion includes these two fields on the list envelope.
+    type: Optional[Literal["comment"]] = None
+    comment: Optional[dict] = None

notionary/database/client.py

@@ -1,5 +1,7 @@
 from typing import Any, Dict, Optional
 
+from urllib3.util import response
+
 from notionary.base_notion_client import BaseNotionClient
 from notionary.database.models import (
     NotionDatabaseResponse,
@@ -18,6 +20,27 @@ class NotionDatabaseClient(BaseNotionClient):
     def __init__(self, token: Optional[str] = None, timeout: int = 30):
         super().__init__(token, timeout)
 
+    async def create_database(
+        self,
+        title: str,
+        parent_page_id: Optional[str],
+        properties: Optional[Dict[str, Any]] = None,
+    ) -> NotionDatabaseResponse:
+        """
+        Creates a new database as child of the specified page.
+        """
+        if properties is None:
+            properties = {"Name": {"title": {}}}
+
+        database_data = {
+            "parent": {"page_id": parent_page_id},
+            "title": [{"type": "text", "text": {"content": title}}],
+            "properties": properties,
+        }
+
+        response = await self.post("databases", database_data)
+        return NotionDatabaseResponse.model_validate(response)
+
     async def get_database(self, database_id: str) -> NotionDatabaseResponse:
         """
         Gets metadata for a Notion database by its ID.

notionary/file_upload/models.py

@@ -1,4 +1,4 @@
-from typing import List, Literal, Optional
+from typing import Literal, Optional
 
 from pydantic import BaseModel
 
@@ -28,7 +28,7 @@ class FileUploadListResponse(BaseModel):
     """
 
     object: Literal["list"]
-    results: List[FileUploadResponse]
+    results: list[FileUploadResponse]
     next_cursor: Optional[str] = None
     has_more: bool
     type: Literal["file_upload"]

notionary/markdown/markdown_builder.py

@@ -51,6 +51,7 @@ from notionary.blocks.toggleable_heading import (
     ToggleableHeadingMarkdownBlockParams,
     ToggleableHeadingMarkdownNode,
 )
+from notionary.blocks.types import BlockType, MarkdownBlockType
 from notionary.blocks.video import VideoMarkdownBlockParams, VideoMarkdownNode
 from notionary.markdown.markdown_document_model import (
     MarkdownBlock,
@@ -67,32 +68,38 @@ class MarkdownBuilder:
     def __init__(self) -> None:
         self.children: list[MarkdownNode] = []
 
-        # Explicit mapping instead of dynamic getattr - type-safe and clear
         self._block_processors: dict[str, Callable[[Any], None]] = {
-            "heading": self._add_heading,
-            "paragraph": self._add_paragraph,
-            "quote": self._add_quote,
-            "bulleted_list": self._add_bulleted_list,
-            "numbered_list": self._add_numbered_list,
-            "todo": self._add_todo,
-            "callout": self._add_callout,
-            "code": self._add_code,
-            "image": self._add_image,
-            "video": self._add_video,
-            "audio": self._add_audio,
-            "file": self._add_file,
-            "pdf": self._add_pdf,
-            "bookmark": self._add_bookmark,
-            "embed": self._add_embed,
-            "table": self._add_table,
-            "divider": self._add_divider,
-            "equation": self._add_equation,
-            "table_of_contents": self._add_table_of_contents,
-            "toggle": self._add_toggle,
-            "toggleable_heading": self._add_toggleable_heading,
-            "columns": self._add_columns,
-            "breadcrumb": self._add_breadcrumb,
-            "space": self._add_space,
+            MarkdownBlockType.HEADING_1: self._add_heading,
+            MarkdownBlockType.HEADING_2: self._add_heading,
+            MarkdownBlockType.HEADING_3: self._add_heading,
+            MarkdownBlockType.PARAGRAPH: self._add_paragraph,
+            MarkdownBlockType.QUOTE: self._add_quote,
+            MarkdownBlockType.BULLETED_LIST_ITEM: self._add_bulleted_list,
+            MarkdownBlockType.NUMBERED_LIST_ITEM: self._add_numbered_list,
+            MarkdownBlockType.TO_DO: self._add_todo,
+            MarkdownBlockType.CALLOUT: self._add_callout,
+            MarkdownBlockType.CODE: self._add_code,
+            MarkdownBlockType.IMAGE: self._add_image,
+            MarkdownBlockType.VIDEO: self._add_video,
+            MarkdownBlockType.AUDIO: self._add_audio,
+            MarkdownBlockType.FILE: self._add_file,
+            MarkdownBlockType.PDF: self._add_pdf,
+            MarkdownBlockType.BOOKMARK: self._add_bookmark,
+            MarkdownBlockType.EMBED: self._add_embed,
+            MarkdownBlockType.TABLE: self._add_table,
+            MarkdownBlockType.DIVIDER: self._add_divider,
+            MarkdownBlockType.EQUATION: self._add_equation,
+            MarkdownBlockType.TABLE_OF_CONTENTS: self._add_table_of_contents,
+            MarkdownBlockType.TOGGLE: self._add_toggle,
+            MarkdownBlockType.COLUMN_LIST: self._add_columns,
+            MarkdownBlockType.BREADCRUMB: self._add_breadcrumb,
+            MarkdownBlockType.HEADING: self._add_heading,
+            MarkdownBlockType.BULLETED_LIST: self._add_bulleted_list,
+            MarkdownBlockType.NUMBERED_LIST: self._add_numbered_list,
+            MarkdownBlockType.TODO: self._add_todo,
+            MarkdownBlockType.TOGGLEABLE_HEADING: self._add_toggleable_heading,
+            MarkdownBlockType.COLUMNS: self._add_columns,
+            MarkdownBlockType.SPACE: self._add_space,
         }
 
     @classmethod
@@ -353,7 +360,7 @@ class MarkdownBuilder:
         return self
 
     def bookmark(
-        self, url: str, title: Optional[str] = None, description: Optional[str] = None
+        self, url: str, title: Optional[str] = None, caption: Optional[str] = None
     ) -> Self:
         """
         Add a bookmark.
@@ -364,7 +371,7 @@ class MarkdownBuilder:
             description: Optional bookmark description text
         """
         self.children.append(
-            BookmarkMarkdownNode(url=url, title=title, description=description)
+            BookmarkMarkdownNode(url=url, title=title, caption=caption)
         )
         return self