notionary 0.3.0__py3-none-any.whl → 0.4.0__py3-none-any.whl

notionary/__init__.py

@@ -1,7 +1,19 @@
 from .data_source.service import NotionDataSource
 from .database.service import NotionDatabase
+from .file_upload import FileUploadQuery, FileUploadQueryBuilder, NotionFileUpload
 from .page.content.markdown.builder import MarkdownBuilder
 from .page.service import NotionPage
-from .workspace import NotionWorkspace
+from .workspace import NotionWorkspace, NotionWorkspaceQueryConfigBuilder, WorkspaceQueryConfig
 
-__all__ = ["MarkdownBuilder", "NotionDataSource", "NotionDatabase", "NotionPage", "NotionWorkspace", "NotionWorkspace"]
+__all__ = [
+    "FileUploadQuery",
+    "FileUploadQueryBuilder",
+    "MarkdownBuilder",
+    "NotionDataSource",
+    "NotionDatabase",
+    "NotionFileUpload",
+    "NotionPage",
+    "NotionWorkspace",
+    "NotionWorkspaceQueryConfigBuilder",
+    "WorkspaceQueryConfig",
+]

notionary/blocks/enums.py

@@ -62,12 +62,6 @@ class BlockType(StrEnum):
     VIDEO = "video"
 
 
-class FileType(StrEnum):
-    EXTERNAL = "external"
-    FILE = "file"
-    FILE_UPLOAD = "file_upload"
-
-
 class CodingLanguage(StrEnum):
     ABAP = "abap"
     ARDUINO = "arduino"
@@ -165,3 +159,30 @@ class CodingLanguage(StrEnum):
                 return member
 
         return default if default is not None else cls.PLAIN_TEXT
+
+
+class VideoFileType(StrEnum):
+    AMV = ".amv"
+    ASF = ".asf"
+    AVI = ".avi"
+    F4V = ".f4v"
+    FLV = ".flv"
+    GIFV = ".gifv"
+    MKV = ".mkv"
+    MOV = ".mov"
+    MPG = ".mpg"
+    MPEG = ".mpeg"
+    MPV = ".mpv"
+    MP4 = ".mp4"
+    M4V = ".m4v"
+    QT = ".qt"
+    WMV = ".wmv"
+
+    @classmethod
+    def get_all_extensions(cls) -> set[str]:
+        return {ext.value for ext in cls}
+
+    @classmethod
+    def is_valid_extension(cls, filename: str) -> bool:
+        lower_filename = filename.lower()
+        return any(lower_filename.endswith(ext.value) for ext in cls)

notionary/blocks/schemas.py

@@ -4,41 +4,38 @@ from typing import Annotated, Literal
 
 from pydantic import BaseModel, ConfigDict, Field
 
-from notionary.blocks.enums import BlockColor, BlockType, CodingLanguage, FileType
+from notionary.blocks.enums import BlockColor, BlockType, CodingLanguage
 from notionary.blocks.rich_text.models import RichText
+from notionary.shared.models.file import ExternalFile, FileUploadFile, NotionHostedFile
 from notionary.shared.models.icon import Icon
 from notionary.shared.models.parent import Parent
 from notionary.user.schemas import PartialUserDto
 
 # ============================================================================
-# File-related models
+# File Data wrapper with caption
 # ============================================================================
 
 
-class ExternalFile(BaseModel):
-    model_config = ConfigDict(from_attributes=True)
-    url: str
+class CaptionMixin(BaseModel):
+    caption: list[RichText] = Field(default_factory=list)
+    name: str | None = None
 
 
-class NotionHostedFile(BaseModel):
-    model_config = ConfigDict(from_attributes=True)
-    url: str
-    expiry_time: str
+class ExternalFileWithCaption(CaptionMixin, ExternalFile):
+    pass
 
 
-class FileUploadFile(BaseModel):
-    model_config = ConfigDict(from_attributes=True)
-    id: str
+class NotionHostedFileWithCaption(CaptionMixin, NotionHostedFile):
+    pass
 
 
-class FileData(BaseModel):
-    model_config = ConfigDict(from_attributes=True)
-    caption: list[RichText] = Field(default_factory=list)
-    type: FileType
-    external: ExternalFile | None = None
-    file: NotionHostedFile | None = None
-    file_upload: FileUploadFile | None = None
-    name: str | None = None
+class FileUploadFileWithCaption(CaptionMixin, FileUploadFile):
+    pass
+
+
+type FileWithCaption = Annotated[
+    ExternalFileWithCaption | NotionHostedFileWithCaption | FileUploadFileWithCaption, Field(discriminator="type")
+]
 
 
 # ============================================================================
@@ -65,24 +62,14 @@ class BaseBlock(BaseModel):
 # ============================================================================
 
 
-class AudioData(BaseModel):
-    model_config = ConfigDict(from_attributes=True)
-    caption: list[RichText] = Field(default_factory=list)
-    type: FileType
-    external: ExternalFile | None = None
-    file: NotionHostedFile | None = None
-    file_upload: FileUploadFile | None = None
-    name: str | None = None
-
-
 class AudioBlock(BaseBlock):
     type: Literal[BlockType.AUDIO] = BlockType.AUDIO
-    audio: AudioData
+    audio: FileWithCaption
 
 
 class CreateAudioBlock(BaseModel):
     type: Literal[BlockType.AUDIO] = BlockType.AUDIO
-    audio: AudioData
+    audio: FileWithCaption
 
 
 # ============================================================================
@@ -90,8 +77,7 @@ class CreateAudioBlock(BaseModel):
 # ============================================================================
 
 
-class BookmarkData(BaseModel):
-    caption: list[RichText] = Field(default_factory=list)
+class BookmarkData(CaptionMixin):
     url: str
 
 
@@ -224,8 +210,7 @@ class CreateChildDatabaseBlock(BaseModel):
 # ============================================================================
 
 
-class CodeData(BaseModel):
-    caption: list[RichText] = Field(default_factory=list)
+class CodeData(CaptionMixin):
     rich_text: list[RichText]
     language: CodingLanguage = CodingLanguage.PLAIN_TEXT
 
@@ -311,9 +296,8 @@ class CreateDividerBlock(BaseModel):
 # ============================================================================
 
 
-class EmbedData(BaseModel):
+class EmbedData(CaptionMixin):
     url: str
-    caption: list[RichText] = Field(default_factory=list)
 
 
 class EmbedBlock(BaseBlock):
@@ -352,12 +336,12 @@ class CreateEquationBlock(BaseModel):
 
 class FileBlock(BaseBlock):
     type: Literal[BlockType.FILE] = BlockType.FILE
-    file: FileData
+    file: FileWithCaption
 
 
 class CreateFileBlock(BaseModel):
     type: Literal[BlockType.FILE] = BlockType.FILE
-    file: FileData
+    file: FileWithCaption
 
 
 # ============================================================================
@@ -416,24 +400,14 @@ CreateHeadingBlock = CreateHeading1Block | CreateHeading2Block | CreateHeading3B
 # ============================================================================
 
 
-class ImageData(BaseModel):
-    model_config = ConfigDict(from_attributes=True)
-    caption: list[RichText] = Field(default_factory=list)
-    type: FileType
-    external: ExternalFile | None = None
-    file: NotionHostedFile | None = None
-    file_upload: FileUploadFile | None = None
-    name: str | None = None
-
-
 class ImageBlock(BaseBlock):
     type: Literal[BlockType.IMAGE] = BlockType.IMAGE
-    image: ImageData
+    image: FileWithCaption
 
 
 class CreateImageBlock(BaseModel):
     type: Literal[BlockType.IMAGE] = BlockType.IMAGE
-    image: ImageData
+    image: FileWithCaption
 
 
 # ============================================================================
@@ -497,24 +471,14 @@ class CreateParagraphBlock(BaseModel):
 # ============================================================================
 
 
-class PdfData(BaseModel):
-    model_config = ConfigDict(from_attributes=True)
-    caption: list[RichText] = Field(default_factory=list)
-    type: FileType
-    external: ExternalFile | None = None
-    file: NotionHostedFile | None = None
-    file_upload: FileUploadFile | None = None
-    name: str | None = None
-
-
 class PdfBlock(BaseBlock):
     type: Literal[BlockType.PDF] = BlockType.PDF
-    pdf: PdfData
+    pdf: FileWithCaption
 
 
 class CreatePdfBlock(BaseModel):
     type: Literal[BlockType.PDF] = BlockType.PDF
-    pdf: PdfData
+    pdf: FileWithCaption
 
 
 # ============================================================================
@@ -669,31 +633,21 @@ class CreateToggleBlock(BaseModel):
 # ============================================================================
 
 
-class VideoData(BaseModel):
-    model_config = ConfigDict(from_attributes=True)
-    caption: list[RichText] = Field(default_factory=list)
-    type: FileType
-    external: ExternalFile | None = None
-    file: NotionHostedFile | None = None
-    file_upload: FileUploadFile | None = None
-    name: str | None = None
-
-
 class VideoBlock(BaseBlock):
     type: Literal[BlockType.VIDEO] = BlockType.VIDEO
-    video: VideoData
+    video: FileWithCaption
 
 
 class CreateVideoBlock(BaseModel):
     type: Literal[BlockType.VIDEO] = BlockType.VIDEO
-    video: VideoData
+    video: FileWithCaption
 
 
 # ============================================================================
 # Block Union Type
 # ============================================================================
 
-Block = Annotated[
+type Block = Annotated[
     (
         AudioBlock
         | BookmarkBlock
@@ -743,7 +697,7 @@ class BlockChildrenResponse(BaseModel):
     request_id: str
 
 
-BlockCreatePayload = Annotated[
+type BlockCreatePayload = Annotated[
     (
         CreateAudioBlock
         | CreateBookmarkBlock

notionary/comments/client.py

@@ -18,20 +18,17 @@ class CommentClient(NotionHttpClient):
     async def iter_comments(
         self,
         block_id: str,
-        *,
-        page_size: int = 100,
+        total_results_limit: int | None = None,
     ) -> AsyncGenerator[CommentDto]:
-        """
-        Iterates through all comments for a block, yielding each comment individually.
-        Uses pagination to handle large result sets efficiently without loading everything into memory.
-        """
         async for comment in paginate_notion_api_generator(
-            self._list_comments_page, block_id=block_id, page_size=page_size
+            self._list_comments_page, block_id=block_id, total_results_limit=total_results_limit
         ):
             yield comment
 
-    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 get_all_comments(self, block_id: str, *, total_results_limit: int | None = None) -> list[CommentDto]:
+        all_comments = await paginate_notion_api(
+            self._list_comments_page, block_id=block_id, total_results_limit=total_results_limit
+        )
 
         self.logger.debug("Retrieved %d total comments for block %s", len(all_comments), block_id)
         return all_comments

notionary/comments/schemas.py

@@ -8,10 +8,6 @@ from pydantic import BaseModel, Field
 
 from notionary.blocks.rich_text.models import RichText
 
-# ---------------------------
-# Comment Parent
-# ---------------------------
-
 
 class CommentParentType(StrEnum):
     PAGE_ID = "page_id"
@@ -28,7 +24,7 @@ class BlockCommentParent(BaseModel):
     block_id: str
 
 
-CommentParent = PageCommentParent | BlockCommentParent
+type CommentParent = PageCommentParent | BlockCommentParent
 
 
 # ---------------------------
@@ -96,7 +92,7 @@ class CustomCommentDisplayName(BaseModel):
     custom: CustomDisplayName
 
 
-CommentDisplayNameInput = IntegrationDisplayName | UserDisplayName | CustomCommentDisplayName
+type CommentDisplayNameInput = IntegrationDisplayName | UserDisplayName | CustomCommentDisplayName
 
 
 class CommentDisplayNameDto(BaseModel):
@@ -189,8 +185,6 @@ class UserRef(BaseModel):
 
 
 class CommentDto(BaseModel):
-    """Comment object as returned by the API"""
-
     object: Literal["comment"] = "comment"
     id: str
 
@@ -217,24 +211,3 @@ class CommentListResponse(BaseModel):
     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))

notionary/data_source/http/data_source_instance_client.py

@@ -58,10 +58,10 @@ class DataSourceInstanceClient(NotionHttpClient, EntityMetadataUpdateClient):
 
     async def query(self, query_params: DataSourceQueryParams | None = None) -> QueryDataSourceResponse:
         query_params_dict = query_params.to_api_params() if query_params else {}
-        page_size = query_params.page_size if query_params else None
+        total_result_limit = query_params.total_results_limit if query_params else None
 
         all_results = await paginate_notion_api(
-            self._make_query_request, query_data=query_params_dict or {}, page_size=page_size
+            self._make_query_request, query_data=query_params_dict or {}, total_result_limit=total_result_limit
         )
 
         return QueryDataSourceResponse(
@@ -72,10 +72,10 @@ class DataSourceInstanceClient(NotionHttpClient, EntityMetadataUpdateClient):
 
     async def query_stream(self, query_params: DataSourceQueryParams | None = None) -> AsyncIterator[Any]:
         query_params_dict = query_params.model_dump() if query_params else {}
-        page_size = query_params.page_size if query_params else None
+        total_result_limit = query_params.total_results_limit if query_params else None
 
         async for result in paginate_notion_api_generator(
-            self._make_query_request, query_data=query_params_dict or {}, page_size=page_size
+            self._make_query_request, query_data=query_params_dict or {}, total_results_limit=total_result_limit
         ):
             yield result