notionary 0.2.22__tar.gz → 0.2.23__tar.gz

{notionary-0.2.22 → notionary-0.2.23}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: notionary
-Version: 0.2.22
+Version: 0.2.23
 Summary: Python library for programmatic Notion workspace management - databases, pages, and content with advanced Markdown support
 License: MIT
 Author: Mathis Arends
@@ -13,9 +13,7 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
-Requires-Dist: aiofiles (>=24.1.0,<25.0.0)
 Requires-Dist: httpx (>=0.28.0)
-Requires-Dist: isort (>=6.0.1,<7.0.0)
 Requires-Dist: posthog (>=6.3.1,<7.0.0)
 Requires-Dist: pydantic (>=2.11.4)
 Requires-Dist: python-dotenv (>=1.1.0)

{notionary-0.2.22 → notionary-0.2.23}/notionary/blocks/child_database/child_database_element.py

@@ -8,6 +8,7 @@ from notionary.blocks.syntax_prompt_builder import BlockElementMarkdownInformati
 from notionary.blocks.models import Block, BlockType
 from notionary.util import LoggingMixin
 
+
 class ChildDatabaseElement(BaseBlockElement, LoggingMixin):
     """
     Handles conversion between Markdown database references and Notion child database blocks.
@@ -23,14 +24,11 @@ class ChildDatabaseElement(BaseBlockElement, LoggingMixin):
         return block.type == BlockType.CHILD_DATABASE and block.child_database
 
     @classmethod
-    async def markdown_to_notion(
-        cls, text: str
-    ) -> Optional[str]:
+    async def markdown_to_notion(cls, text: str) -> Optional[str]:
         """
         Convert markdown database syntax to actual Notion database.
         Returns the database_id if successful, None otherwise.
         """
-        cls.logger.warning("Creating database from markdown is not supported via the block api. Call the create_child_page method in NotionPage instead.s")
         return None
 
     @classmethod

{notionary-0.2.22 → notionary-0.2.23}/notionary/blocks/rich_text/text_inline_formatter.py

@@ -10,7 +10,7 @@ from notionary.blocks.rich_text.rich_text_models import (
     MentionTemplateMention,
 )
 from notionary.blocks.types import BlockColor
-from notionary.blocks.rich_text.name_to_id_resolver import NameIdResolver
+from notionary.shared import NameIdResolver
 
 
 class TextInlineFormatter:

notionary-0.2.23/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-0.2.23/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-0.2.23/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-0.2.22 → notionary-0.2.23}/notionary/page/client.py

@@ -42,18 +42,13 @@ class NotionPageClient(BaseNotionClient):
         )
 
         properties: dict[str, Any] = {
-            "title": {
-                "title": [
-                    {"type": "text", "text": {"content": title}}
-                ]
-            }
+            "title": {"title": [{"type": "text", "text": {"content": title}}]}
         }
 
         payload = {"parent": parent, "properties": properties}
         response = await self.post("pages", payload)
         return NotionPageResponse.model_validate(response)
 
-
     async def patch_page(
         self, page_id: str, data: Optional[dict[str, Any]] = None
     ) -> NotionPageResponse:

{notionary-0.2.22 → notionary-0.2.23}/notionary/page/notion_page.py

@@ -5,6 +5,7 @@ import random
 from typing import TYPE_CHECKING, Any, Callable, Optional, Union
 
 from notionary.blocks.client import NotionBlockClient
+from notionary.comments import CommentClient, Comment
 from notionary.blocks.syntax_prompt_builder import SyntaxPromptBuilder
 from notionary.blocks.models import DatabaseParent
 from notionary.blocks.registry.block_registry import BlockRegistry
@@ -24,6 +25,7 @@ from notionary.util.fuzzy import find_best_match
 if TYPE_CHECKING:
     from notionary import NotionDatabase
 
+
 class NotionPage(LoggingMixin):
     """
     Managing content and metadata of a Notion page.
@@ -56,8 +58,9 @@ class NotionPage(LoggingMixin):
 
         self._client = NotionPageClient(token=token)
         self._block_client = NotionBlockClient(token=token)
+        self._comment_client = CommentClient(token=token)
         self._page_data = None
-        
+
         self.block_element_registry = BlockRegistry.create_registry()
 
         self._page_content_writer = PageContentWriter(
@@ -213,6 +216,41 @@ class NotionPage(LoggingMixin):
         markdown_syntax_builder = SyntaxPromptBuilder()
         return markdown_syntax_builder.build_concise_reference()
 
+    async def get_comments(self) -> list[Comment]:
+        return await self._comment_client.list_all_comments_for_page(page_id=self._page_id)
+    
+    async def post_comment(
+        self,
+        content: str,
+        *,
+        discussion_id: Optional[str] = None,
+        rich_text: Optional[list[dict[str, Any]]] = None,
+    ) -> Optional[Comment]:
+        """
+        Post a comment on this page.
+
+        Args:
+            content: The plain text content of the comment
+            discussion_id: Optional discussion ID to reply to an existing discussion
+            rich_text: Optional rich text formatting for the comment content
+
+        Returns:
+            Comment: The created comment object, or None if creation failed
+        """
+        try:
+            # Use the comment client to create the comment
+            comment = await self._comment_client.create_comment(
+                page_id=self._page_id,
+                content=content,
+                discussion_id=discussion_id,
+                rich_text=rich_text,
+            )
+            self.logger.info(f"Successfully posted comment on page '{self._title}'")
+            return comment
+        except Exception as e:
+            self.logger.error(f"Failed to post comment on page '{self._title}': {str(e)}")
+            return None
+
     async def set_title(self, title: str) -> str:
         """
         Set the title of the page.
@@ -320,27 +358,33 @@ class NotionPage(LoggingMixin):
 
             self.logger.error(f"Error updating page emoji: {str(e)}")
             return None
-        
+
     async def create_child_database(self, title: str) -> NotionDatabase:
         from notionary import NotionDatabase
+
         database_client = NotionDatabaseClient(token=self._client.token)
-        
-        create_database_response =  await database_client.create_database(
+
+        create_database_response = await database_client.create_database(
             title=title,
             parent_page_id=self._page_id,
         )
-        
-        return await NotionDatabase.from_database_id(id=create_database_response.id, token=self._client.token)
-    
+
+        return await NotionDatabase.from_database_id(
+            id=create_database_response.id, token=self._client.token
+        )
+
     async def create_child_page(self, title: str) -> NotionPage:
         from notionary import NotionPage
+
         child_page_response = await self._client.create_page(
             parent_page_id=self._page_id,
             title=title,
         )
-        
-        return await NotionPage.from_page_id(page_id=child_page_response.id, token=self._client.token)
-    
+
+        return await NotionPage.from_page_id(
+            page_id=child_page_response.id, token=self._client.token
+        )
+
     async def set_external_icon(self, url: str) -> Optional[str]:
         """
         Sets the page icon to an external image.
@@ -636,4 +680,4 @@ class NotionPage(LoggingMixin):
         """Extract parent database ID from page response."""
         parent = page_response.parent
         if isinstance(parent, DatabaseParent):
-            return parent.database_id
+            return parent.database_id

{notionary-0.2.22 → notionary-0.2.23}/notionary/page/page_context.py

@@ -1,4 +1,3 @@
-# notionary/blocks/context/page_context.py
 from __future__ import annotations
 
 from typing import TYPE_CHECKING, Optional

notionary-0.2.23/notionary/shared/__init__.py

@@ -0,0 +1,5 @@
+from .name_to_id_resolver import NameIdResolver
+
+__all__ = [
+    "NameIdResolver"
+]

{notionary-0.2.22/notionary/blocks/rich_text → notionary-0.2.23/notionary/shared}/name_to_id_resolver.py

@@ -1,7 +1,5 @@
 from __future__ import annotations
 
-import logging
-from contextlib import contextmanager
 from typing import Optional
 
 from notionary.user.notion_user_manager import NotionUserManager

{notionary-0.2.22 → notionary-0.2.23}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "notionary"
-version = "0.2.22"
+version = "0.2.23"
 description = "Python library for programmatic Notion workspace management - databases, pages, and content with advanced Markdown support"
 readme = "README.md"
 requires-python = ">=3.9"
@@ -13,8 +13,6 @@ dependencies = [
     "python-dotenv>=1.1.0",
     "pydantic>=2.11.4",
     "posthog (>=6.3.1,<7.0.0)",
-    "aiofiles (>=24.1.0,<25.0.0)",
-    "isort (>=6.0.1,<7.0.0)",
 ]
 
 [project.urls]
@@ -32,3 +30,4 @@ pytest = "^8.4.1"
 pytest-asyncio = "^1.1.0"
 pytest-mock = "^3.14.1"
 pytest-cov = "^6.2.1"
+isort = "^6.0.1"