notionary 0.2.27__py3-none-any.whl → 0.2.28__py3-none-any.whl

notionary/comments/client.py

@@ -1,211 +1,76 @@
-from __future__ import annotations
+from collections.abc import AsyncGenerator
 
-from typing import Any, AsyncGenerator, Optional
+from notionary.blocks.rich_text.models import RichText
+from notionary.comments.schemas import (
+    CommentCreateRequest,
+    CommentDto,
+    CommentListRequest,
+    CommentListResponse,
+)
+from notionary.http.client import NotionHttpClient
+from notionary.utils.pagination import paginate_notion_api, paginate_notion_api_generator
 
-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(NotionHttpClient):
+    def __init__(self) -> None:
+        super().__init__()
 
-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(
+    async def iter_comments(
         self,
-        *,
         block_id: str,
-        start_cursor: Optional[str] = None,
-        page_size: Optional[int] = None,
-    ) -> CommentListResponse:
+        *,
+        page_size: int = 100,
+    ) -> AsyncGenerator[CommentDto]:
         """
-        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.
+        Iterates through all comments for a block, yielding each comment individually.
+        Uses pagination to handle large result sets efficiently without loading everything into memory.
         """
-        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
+        async for comment in paginate_notion_api_generator(
+            self._list_comments_page, block_id=block_id, page_size=page_size
+        ):
+            yield comment
 
-        resp = await self.get("comments", params=params)
-        if resp is None:
-            raise RuntimeError("Failed to list comments.")
-        return CommentListResponse.model_validate(resp)
+    async def get_all_comments(self, block_id: str, *, page_size: int = 100) -> list[CommentDto]:
+        all_comments = await paginate_notion_api(self._list_comments_page, block_id=block_id, page_size=page_size)
 
-    async def iter_comments(
+        self.logger.debug("Retrieved %d total comments for block %s", len(all_comments), block_id)
+        return all_comments
+
+    async def _list_comments_page(
         self,
-        *,
         block_id: str,
+        *,
+        start_cursor: str | None = None,
         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
+    ) -> CommentListResponse:
+        request = CommentListRequest(
+            block_id=block_id,
+            start_cursor=start_cursor,
+            page_size=page_size,
+        )
+        resp = await self.get("comments", params=request.model_dump())
+        return CommentListResponse.model_validate(resp)
 
-    async def create_comment_on_page(
+    async def create_comment_for_page(
         self,
-        *,
+        rich_text: list[RichText],
         page_id: str,
-        text: str,
-        display_name: Optional[dict] = None,
-        attachments: Optional[list[dict]] = None,
-    ) -> Comment:
-        """
-        Create a top-level comment on a page.
+    ) -> CommentDto:
+        request = CommentCreateRequest.for_page(page_id=page_id, rich_text=rich_text)
 
-        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
+        body = request.model_dump(exclude_unset=True, exclude_none=True)
 
         resp = await self.post("comments", data=body)
-        if resp is None:
-            raise RuntimeError("Failed to create page comment.")
-        return Comment.model_validate(resp)
+        return CommentDto.model_validate(resp)
 
-    async def create_comment(
+    async def create_comment_for_discussion(
         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
+        rich_text: list[RichText],
+        discussion_id: str,
+    ) -> CommentDto:
+        request = CommentCreateRequest.for_discussion(discussion_id=discussion_id, rich_text=rich_text)
 
-        if display_name:
-            body["display_name"] = display_name
-        if attachments:
-            body["attachments"] = attachments
+        body = request.model_dump(exclude_unset=True, exclude_none=True)
 
         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,
-        )
+        return CommentDto.model_validate(resp)

notionary/comments/factory.py

@@ -0,0 +1,40 @@
+import asyncio
+
+from notionary.blocks.rich_text.rich_text_markdown_converter import RichTextToMarkdownConverter
+from notionary.comments.models import Comment
+from notionary.comments.schemas import CommentDto
+from notionary.user.client import UserHttpClient
+from notionary.user.person import PersonUser
+from notionary.utils.mixins.logging import LoggingMixin
+
+
+class CommentFactory(LoggingMixin):
+    UNKNOWN_AUTHOR = "Unknown Author"
+
+    def __init__(
+        self,
+        http_client: UserHttpClient | None = None,
+        markdown_converter: RichTextToMarkdownConverter | None = None,
+    ) -> None:
+        self.http_client = http_client
+        self.markdown_converter = markdown_converter or RichTextToMarkdownConverter()
+
+    async def create_from_dto(self, dto: CommentDto) -> Comment:
+        author_name, content = await asyncio.gather(self._resolve_user_name(dto), self._resolve_content(dto))
+
+        return Comment(author_name=author_name, content=content)
+
+    async def _resolve_user_name(self, dto: CommentDto) -> str:
+        user_id = dto.created_by.id
+
+        try:
+            person = await PersonUser.from_id(user_id, self.http_client)
+            if person and person.name:
+                return person.name
+        except Exception:
+            self.logger.warning(f"Failed to resolve user name for user_id: {user_id}", exc_info=True)
+
+        return self.UNKNOWN_AUTHOR
+
+    async def _resolve_content(self, dto: CommentDto) -> str:
+        return await self.markdown_converter.to_markdown(dto.rich_text)

notionary/comments/models.py

@@ -1,129 +1,7 @@
-# notionary/comments/models.py
-from __future__ import annotations
+from dataclasses import dataclass
 
-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
+@dataclass
+class Comment:
+    author_name: str
+    content: str

notionary/comments/schemas.py

@@ -0,0 +1,240 @@
+from __future__ import annotations
+
+from datetime import datetime
+from enum import StrEnum
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+from notionary.blocks.rich_text.models import RichText
+
+# ---------------------------
+# Comment Parent
+# ---------------------------
+
+
+class CommentParentType(StrEnum):
+    PAGE_ID = "page_id"
+    BLOCK_ID = "block_id"
+
+
+class PageCommentParent(BaseModel):
+    type: Literal[CommentParentType.PAGE_ID] = CommentParentType.PAGE_ID
+    page_id: str
+
+
+class BlockCommentParent(BaseModel):
+    type: Literal[CommentParentType.BLOCK_ID] = CommentParentType.BLOCK_ID
+    block_id: str
+
+
+CommentParent = PageCommentParent | BlockCommentParent
+
+
+# ---------------------------
+# Comment Attachment (Response/DTO)
+# ---------------------------
+
+
+class CommentAttachmentCategory(StrEnum):
+    AUDIO = "audio"
+    IMAGE = "image"
+    PDF = "pdf"
+    PRODUCTIVITY = "productivity"
+    VIDEO = "video"
+
+
+class FileWithExpiry(BaseModel):
+    url: str
+    expiry_time: datetime
+
+
+class CommentAttachmentDto(BaseModel):
+    category: CommentAttachmentCategory
+    file: FileWithExpiry
+
+
+# ---------------------------
+# Comment Attachment (Request/Input)
+# ---------------------------
+
+
+class CommentAttachmentFileUploadType(StrEnum):
+    FILE_UPLOAD = "file_upload"
+
+
+class CommentAttachmentInput(BaseModel):
+    file_upload_id: str
+    type: Literal[CommentAttachmentFileUploadType.FILE_UPLOAD] = CommentAttachmentFileUploadType.FILE_UPLOAD
+
+
+# ---------------------------
+# Comment Display Name
+# ---------------------------
+
+
+class CommentDisplayNameType(StrEnum):
+    INTEGRATION = "integration"
+    USER = "user"
+    CUSTOM = "custom"
+
+
+class CustomDisplayName(BaseModel):
+    name: str
+
+
+class IntegrationDisplayName(BaseModel):
+    type: Literal[CommentDisplayNameType.INTEGRATION] = CommentDisplayNameType.INTEGRATION
+
+
+class UserDisplayName(BaseModel):
+    type: Literal[CommentDisplayNameType.USER] = CommentDisplayNameType.USER
+
+
+class CustomCommentDisplayName(BaseModel):
+    type: Literal[CommentDisplayNameType.CUSTOM] = CommentDisplayNameType.CUSTOM
+    custom: CustomDisplayName
+
+
+CommentDisplayNameInput = IntegrationDisplayName | UserDisplayName | CustomCommentDisplayName
+
+
+class CommentDisplayNameDto(BaseModel):
+    type: CommentDisplayNameType
+    resolved_name: str
+
+
+# ---------------------------
+# Comment Create Request
+# ---------------------------
+
+
+class CommentCreateRequest(BaseModel):
+    rich_text: list[RichText]
+    parent: CommentParent | None = None
+    discussion_id: str | None = None
+    display_name: CommentDisplayNameInput | None = None
+    attachments: list[CommentAttachmentInput] | None = None
+
+    @classmethod
+    def for_page(
+        cls,
+        page_id: str,
+        rich_text: list[RichText],
+        display_name: CommentDisplayNameInput | None = None,
+        attachments: list[CommentAttachmentInput] | None = None,
+    ) -> CommentCreateRequest:
+        return cls(
+            rich_text=rich_text,
+            parent=PageCommentParent(page_id=page_id),
+            display_name=display_name,
+            attachments=attachments,
+        )
+
+    @classmethod
+    def for_block(
+        cls,
+        block_id: str,
+        rich_text: list[RichText],
+        display_name: CommentDisplayNameInput | None = None,
+        attachments: list[CommentAttachmentInput] | None = None,
+    ) -> CommentCreateRequest:
+        return cls(
+            rich_text=rich_text,
+            parent=BlockCommentParent(block_id=block_id),
+            display_name=display_name,
+            attachments=attachments,
+        )
+
+    @classmethod
+    def for_discussion(
+        cls,
+        discussion_id: str,
+        rich_text: list[RichText],
+        display_name: CommentDisplayNameInput | None = None,
+        attachments: list[CommentAttachmentInput] | None = None,
+    ) -> CommentCreateRequest:
+        return cls(
+            rich_text=rich_text,
+            discussion_id=discussion_id,
+            display_name=display_name,
+            attachments=attachments,
+        )
+
+
+# ---------------------------
+# Comment List Request
+# ---------------------------
+
+
+class CommentListRequest(BaseModel):
+    block_id: str
+    start_cursor: str | None = None
+    page_size: int | None = None
+
+
+# ---------------------------
+# User Reference
+# ---------------------------
+
+
+class UserRef(BaseModel):
+    object: Literal["user"] = "user"
+    id: str
+
+
+# ---------------------------
+# Comment DTO (Response)
+# ---------------------------
+
+
+class CommentDto(BaseModel):
+    """Comment object as returned by the API"""
+
+    object: Literal["comment"] = "comment"
+    id: str
+
+    parent: CommentParent
+    discussion_id: str
+
+    created_time: datetime
+    last_edited_time: datetime
+
+    created_by: UserRef
+
+    rich_text: list[RichText] = Field(default_factory=list)
+    attachments: list[CommentAttachmentDto] = Field(default_factory=list)
+    display_name: CommentDisplayNameDto | None = None
+
+
+# ---------------------------
+# List Response
+# ---------------------------
+
+
+class CommentListResponse(BaseModel):
+    object: Literal["list"] = "list"
+    results: list[CommentDto] = Field(default_factory=list)
+    next_cursor: str | None = None
+    has_more: bool = False
+
+
+# ---------------------------
+# Convenience Builders
+# ---------------------------
+
+
+class CommentDisplayNameBuilder:
+    """Helper class to build display names easily"""
+
+    @staticmethod
+    def integration() -> IntegrationDisplayName:
+        return IntegrationDisplayName()
+
+    @staticmethod
+    def user() -> UserDisplayName:
+        return UserDisplayName()
+
+    @staticmethod
+    def custom(name: str) -> CustomCommentDisplayName:
+        return CustomCommentDisplayName(custom=CustomDisplayName(name=name))