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

notionary/file_upload/__init__.py

@@ -0,0 +1,4 @@
+from .query import FileUploadQuery, FileUploadQueryBuilder
+from .service import NotionFileUpload
+
+__all__ = ["FileUploadQuery", "FileUploadQueryBuilder", "NotionFileUpload"]

notionary/file_upload/client.py

@@ -1,12 +1,9 @@
-import traceback
-from io import BytesIO
-from pathlib import Path
-from typing import BinaryIO
+from collections.abc import AsyncGenerator
 
-import aiofiles
 import httpx
 
-from notionary.file_upload.models import (
+from notionary.file_upload.query.models import FileUploadQuery
+from notionary.file_upload.schemas import (
     FileUploadCompleteRequest,
     FileUploadCreateRequest,
     FileUploadListResponse,
@@ -14,228 +11,145 @@ from notionary.file_upload.models import (
     UploadMode,
 )
 from notionary.http.client import NotionHttpClient
+from notionary.utils.pagination import PaginatedResponse, paginate_notion_api, paginate_notion_api_generator
 
 
 class FileUploadHttpClient(NotionHttpClient):
-    """
-    Client for Notion file upload operations.
-    Inherits base HTTP functionality from NotionHttpClient.
-    """
-
-    async def create_file_upload(
+    async def create_single_part_upload(
         self,
         filename: str,
         content_type: str | None = None,
-        content_length: int | None = None,
-        mode: UploadMode = UploadMode.SINGLE_PART,
-    ) -> FileUploadResponse | None:
-        """
-        Create a new file upload.
-
-        Args:
-            filename: Name of the file (max 900 bytes)
-            content_type: MIME type of the file
-            content_length: Size of the file in bytes
-            mode: Upload mode (UploadMode.SINGLE_PART or UploadMode.MULTI_PART)
-
-        Returns:
-            FileUploadResponse or None if failed
-        """
-        request_data = FileUploadCreateRequest(
+    ) -> FileUploadResponse:
+        return await self._create_upload(
             filename=filename,
             content_type=content_type,
-            content_length=content_length,
-            mode=mode,
+            mode=UploadMode.SINGLE_PART,
+            number_of_parts=None,
         )
 
-        response = await self.post("file_uploads", data=request_data.model_dump())
-        if response is None:
-            return None
-
-        try:
-            return FileUploadResponse.model_validate(response)
-        except Exception as e:
-            self.logger.error("Failed to validate file upload response: %s", e)
-            return None
+    async def create_multi_part_upload(
+        self,
+        filename: str,
+        number_of_parts: int,
+        content_type: str | None = None,
+    ) -> FileUploadResponse:
+        return await self._create_upload(
+            filename=filename,
+            content_type=content_type,
+            mode=UploadMode.MULTI_PART,
+            number_of_parts=number_of_parts,
+        )
 
-    async def send_file_upload(
+    async def send_file_content(
         self,
         file_upload_id: str,
-        file_content: BinaryIO,
-        filename: str | None = None,
+        file_content: bytes,
+        filename: str,
         part_number: int | None = None,
-    ) -> bool:
-        """
-        Send file content to Notion.
-
-        Args:
-            file_upload_id: ID of the file upload
-            file_content: Binary file content
-            filename: Optional filename for the form data
-            part_number: Part number for multi-part uploads
-
-        Returns:
-            True if successful, False otherwise
-        """
-        if not self.client:
-            self.logger.error("HTTP client not initialized")
-            return False
-
-        url = f"{self.BASE_URL}/file_uploads/{file_upload_id}/send"
-
-        try:
-            # Read all content from BinaryIO into bytes
-            if hasattr(file_content, "read"):
-                file_bytes = file_content.read()
-                # Reset position if possible (for BytesIO objects)
-                if hasattr(file_content, "seek"):
-                    file_content.seek(0)
-            else:
-                file_bytes = file_content
-
-            # Prepare files dict for multipart upload
-            files = {"file": (filename or "file", file_bytes)}
-
-            # Prepare form data (only for multi-part uploads)
-            data = {}
-            if part_number is not None:
-                data["part_number"] = str(part_number)
-
-            # Create a new client instance specifically for this upload
-            # This avoids issues with the base client's default JSON headers
-            upload_headers = {
-                "Authorization": f"Bearer {self.token}",
-                "Notion-Version": self.NOTION_VERSION,
-                # Explicitly do NOT set Content-Type - let httpx handle multipart
-            }
-
-            self.logger.debug("Sending file upload to %s with filename %s", url, filename)
-
-            # Use a temporary client for the multipart upload
-            async with httpx.AsyncClient(timeout=self.timeout) as upload_client:
-                response = await upload_client.post(
-                    url,
-                    files=files,
-                    data=data if data else None,
-                    headers=upload_headers,
-                )
-
-                response.raise_for_status()
-                self.logger.debug("File upload sent successfully: %s", file_upload_id)
-                return True
-
-        except httpx.HTTPStatusError as e:
-            try:
-                error_text = e.response.text
-            except Exception:
-                error_text = "Unable to read error response"
-            error_msg = f"HTTP {e.response.status_code}: {error_text}"
-            self.logger.error("Send file upload failed (%s): %s", url, error_msg)
-            return False
-
-        except httpx.RequestError as e:
-            self.logger.error("Request error sending file upload (%s): %s", url, str(e))
-            return False
-
-        except Exception as e:
-            self.logger.error("Unexpected error in send_file_upload: %s", str(e))
-
-            self.logger.debug("Full traceback: %s", traceback.format_exc())
-            return False
-
-    async def complete_file_upload(self, file_upload_id: str) -> FileUploadResponse | None:
-        """
-        Complete a multi-part file upload.
-
-        Args:
-            file_upload_id: ID of the file upload
-
-        Returns:
-            FileUploadResponse or None if failed
-        """
-        request_data = FileUploadCompleteRequest()
-
-        response = await self.post(f"file_uploads/{file_upload_id}/complete", data=request_data.model_dump())
-        if response is None:
-            return None
-
-        try:
-            return FileUploadResponse.model_validate(response)
-        except Exception as e:
-            self.logger.error("Failed to validate complete file upload response: %s", e)
-            return None
-
-    async def retrieve_file_upload(self, file_upload_id: str) -> FileUploadResponse | None:
-        """
-        Retrieve details of a file upload.
-
-        Args:
-            file_upload_id: ID of the file upload
-
-        Returns:
-            FileUploadResponse or None if failed
-        """
-        response = await self.get(f"file_uploads/{file_upload_id}")
-        if response is None:
-            return None
+    ) -> FileUploadResponse:
+        await self._ensure_initialized()
+
+        url = self._build_send_url(file_upload_id)
+        files = {"file": (filename, file_content)}
+        data = self._build_part_number_data(part_number)
 
-        try:
-            return FileUploadResponse.model_validate(response)
-        except Exception as e:
-            self.logger.error("Failed to validate retrieve file upload response: %s", e)
-            return None
+        response = await self._send_multipart_request(url, files=files, data=data)
+        return FileUploadResponse.model_validate(response.json())
+
+    async def complete_upload(self, file_upload_id: str) -> FileUploadResponse:
+        request = FileUploadCompleteRequest()
+        response = await self.post(
+            f"file_uploads/{file_upload_id}/complete",
+            data=request.model_dump(),
+        )
+        return FileUploadResponse.model_validate(response)
+
+    async def get_file_upload(self, file_upload_id: str) -> FileUploadResponse:
+        response = await self.get(f"file_uploads/{file_upload_id}")
+        return FileUploadResponse.model_validate(response)
 
     async def list_file_uploads(
-        self, page_size: int = 100, start_cursor: str | None = None
-    ) -> FileUploadListResponse | None:
-        """
-        List file uploads for the current bot integration.
-
-        Args:
-            page_size: Number of uploads per page (max 100)
-            start_cursor: Cursor for pagination
-
-        Returns:
-            FileUploadListResponse or None if failed
-        """
-        params = {"page_size": min(page_size, 100)}
+        self,
+        query: FileUploadQuery | None = None,
+    ) -> list[FileUploadResponse]:
+        query = query or FileUploadQuery()
+        return await paginate_notion_api(
+            lambda **kwargs: self._fetch_file_uploads_page(query=query, **kwargs),
+            total_results_limit=query.total_results_limit,
+        )
+
+    async def list_file_uploads_stream(
+        self,
+        query: FileUploadQuery | None = None,
+    ) -> AsyncGenerator[FileUploadResponse]:
+        query = query or FileUploadQuery()
+        async for upload in paginate_notion_api_generator(
+            lambda **kwargs: self._fetch_file_uploads_page(query=query, **kwargs),
+            total_results_limit=query.total_results_limit,
+        ):
+            yield upload
+
+    async def _create_upload(
+        self,
+        filename: str,
+        mode: UploadMode,
+        content_type: str | None,
+        number_of_parts: int | None,
+    ) -> FileUploadResponse:
+        request = FileUploadCreateRequest(
+            filename=filename,
+            content_type=content_type,
+            mode=mode,
+            number_of_parts=number_of_parts,
+        )
+        response = await self.post("file_uploads", data=request.model_dump())
+        return FileUploadResponse.model_validate(response)
+
+    async def _send_multipart_request(
+        self,
+        url: str,
+        files: dict,
+        data: dict | None = None,
+    ) -> httpx.Response:
+        headers = self._build_multipart_headers()
+
+        async with httpx.AsyncClient(headers=headers, timeout=self.timeout) as client:
+            response = await client.post(url, files=files, data=data)
+
+        response.raise_for_status()
+        return response
+
+    async def _fetch_file_uploads_page(
+        self,
+        query: FileUploadQuery,
+        start_cursor: str | None = None,
+        **kwargs,
+    ) -> PaginatedResponse:
+        params = query.model_dump(exclude_none=True)
+        params["page_size"] = min(query.page_size_limit or 100, 100)
+
         if start_cursor:
             params["start_cursor"] = start_cursor
 
         response = await self.get("file_uploads", params=params)
-        if response is None:
-            return None
-
-        try:
-            return FileUploadListResponse.model_validate(response)
-        except Exception as e:
-            self.logger.error("Failed to validate list file uploads response: %s", e)
-            return None
-
-    async def send_file_from_path(self, file_upload_id: str, file_path: Path, part_number: int | None = None) -> bool:
-        """
-        Convenience method to send file from file path.
-
-        Args:
-            file_upload_id: ID of the file upload
-            file_path: Path to the file
-            part_number: Part number for multi-part uploads
-
-        Returns:
-            True if successful, False otherwise
-        """
-        try:
-            # Read file content into memory first using aiofiles
-            async with aiofiles.open(file_path, "rb") as f:
-                file_content = await f.read()
-
-            # Use BytesIO for the upload
-            return await self.send_file_upload(
-                file_upload_id=file_upload_id,
-                file_content=BytesIO(file_content),
-                filename=file_path.name,
-                part_number=part_number,
-            )
-        except Exception as e:
-            self.logger.error("Failed to send file from path %s: %s", file_path, e)
-            return False
+        parsed = FileUploadListResponse.model_validate(response)
+
+        return PaginatedResponse(
+            results=parsed.results,
+            has_more=parsed.has_more,
+            next_cursor=parsed.next_cursor,
+        )
+
+    def _build_send_url(self, file_upload_id: str) -> str:
+        return f"{self.BASE_URL}/file_uploads/{file_upload_id}/send"
+
+    def _build_part_number_data(self, part_number: int | None) -> dict | None:
+        if part_number is not None:
+            return {"part_number": str(part_number)}
+        return None
+
+    def _build_multipart_headers(self) -> dict:
+        return {
+            "Authorization": f"Bearer {self.token}",
+            "Notion-Version": self.NOTION_VERSION,
+        }

notionary/file_upload/config/__init__.py

@@ -0,0 +1,17 @@
+from .config import FileUploadConfig
+from .constants import (
+    NOTION_MAX_FILENAME_BYTES,
+    NOTION_MULTI_PART_CHUNK_SIZE_MAX,
+    NOTION_MULTI_PART_CHUNK_SIZE_MIN,
+    NOTION_RECOMMENDED_CHUNK_SIZE,
+    NOTION_SINGLE_PART_MAX_SIZE,
+)
+
+__all__ = [
+    "NOTION_MAX_FILENAME_BYTES",
+    "NOTION_MULTI_PART_CHUNK_SIZE_MAX",
+    "NOTION_MULTI_PART_CHUNK_SIZE_MIN",
+    "NOTION_RECOMMENDED_CHUNK_SIZE",
+    "NOTION_SINGLE_PART_MAX_SIZE",
+    "FileUploadConfig",
+]

notionary/file_upload/config/config.py

@@ -0,0 +1,32 @@
+from pathlib import Path
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from notionary.file_upload.config.constants import (
+    NOTION_MULTI_PART_CHUNK_SIZE_MAX,
+    NOTION_MULTI_PART_CHUNK_SIZE_MIN,
+    NOTION_RECOMMENDED_CHUNK_SIZE,
+)
+
+
+class FileUploadConfig(BaseModel):
+    model_config = ConfigDict(frozen=True)
+
+    multi_part_chunk_size: int = Field(
+        default=NOTION_RECOMMENDED_CHUNK_SIZE,
+        ge=NOTION_MULTI_PART_CHUNK_SIZE_MIN,
+        le=NOTION_MULTI_PART_CHUNK_SIZE_MAX,
+        description=(
+            "The part size (in bytes) for multi-part uploads. Must be within Notion's allowed range (e.g., 5MB-20MB)."
+        ),
+    )
+
+    max_upload_timeout: int = Field(
+        default=300, gt=0, description="Maximum time in seconds to wait for an upload to complete."
+    )
+
+    poll_interval: int = Field(default=2, gt=0, description="Interval in seconds for polling the upload status.")
+
+    base_upload_path: Path | None = Field(
+        default=None, description="Optional default base path for resolving relative file uploads."
+    )

notionary/file_upload/config/constants.py

@@ -0,0 +1,16 @@
+"""
+Fixed API limits and recommendations from Notion.
+These values should not be changed, as they are specified by the API.
+
+Source: https://developers.notion.com/reference/file-uploads
+"""
+
+_MB = 1024 * 1024
+
+NOTION_SINGLE_PART_MAX_SIZE: int = 20 * _MB
+NOTION_MAX_FILENAME_BYTES: int = 900
+
+NOTION_MULTI_PART_CHUNK_SIZE_MIN: int = 5 * _MB
+NOTION_MULTI_PART_CHUNK_SIZE_MAX: int = 20 * _MB
+
+NOTION_RECOMMENDED_CHUNK_SIZE: int = 10 * _MB

notionary/file_upload/file/reader.py

@@ -0,0 +1,28 @@
+from collections.abc import AsyncGenerator
+from pathlib import Path
+
+import aiofiles
+
+from notionary.file_upload.config.config import FileUploadConfig
+
+
+class FileContentReader:
+    def __init__(self, config: FileUploadConfig | None = None):
+        config = config or FileUploadConfig()
+        self._chunk_size = config.multi_part_chunk_size
+
+    async def read_full_file(self, file_path: Path) -> bytes:
+        async with aiofiles.open(file_path, "rb") as f:
+            return await f.read()
+
+    async def read_file_chunks(self, file_path: Path) -> AsyncGenerator[bytes]:
+        async with aiofiles.open(file_path, "rb") as file:
+            while True:
+                chunk = await file.read(self._chunk_size)
+                if not chunk:
+                    break
+                yield chunk
+
+    async def bytes_to_chunks(self, file_content: bytes) -> AsyncGenerator[bytes]:
+        for i in range(0, len(file_content), self._chunk_size):
+            yield file_content[i : i + self._chunk_size]

notionary/file_upload/query/__init__.py

@@ -0,0 +1,7 @@
+from .builder import FileUploadQueryBuilder
+from .models import FileUploadQuery
+
+__all__ = [
+    "FileUploadQuery",
+    "FileUploadQueryBuilder",
+]

notionary/file_upload/query/builder.py

@@ -0,0 +1,54 @@
+from typing import Self
+
+from notionary.file_upload.query.models import FileUploadQuery
+from notionary.file_upload.schemas import FileUploadStatus
+
+
+class FileUploadQueryBuilder:
+    def __init__(self, query: FileUploadQuery | None = None):
+        self._query = query or FileUploadQuery()
+
+    def with_status(self, status: FileUploadStatus) -> Self:
+        self._query.status = status
+        return self
+
+    def with_uploaded_status_only(self) -> Self:
+        self._query.status = FileUploadStatus.UPLOADED
+        return self
+
+    def with_pending_status_only(self) -> Self:
+        self._query.status = FileUploadStatus.PENDING
+        return self
+
+    def with_failed_status_only(self) -> Self:
+        self._query.status = FileUploadStatus.FAILED
+        return self
+
+    def with_expired_status_only(self) -> Self:
+        self._query.status = FileUploadStatus.EXPIRED
+        return self
+
+    def with_archived(self, archived: bool) -> Self:
+        self._query.archived = archived
+        return self
+
+    def with_page_size_limit(self, page_size_limit: int) -> Self:
+        self._query.page_size_limit = self._validate_page_size_limit(page_size_limit)
+        return self
+
+    def _validate_page_size_limit(self, value: int) -> int:
+        if not (1 <= value <= 100):
+            raise ValueError(f"page_size_limit must be between 1 and 100, got {value}")
+        return value
+
+    def with_total_results_limit(self, total_results_limit: int) -> Self:
+        self._query.total_results_limit = self._validate_total_results_limit(total_results_limit)
+        return self
+
+    def _validate_total_results_limit(self, value: int) -> int:
+        if not (1 <= value <= 100):
+            raise ValueError(f"total_results_limit must be between 1 and 100, got {value}")
+        return value
+
+    def build(self) -> FileUploadQuery:
+        return self._query

notionary/file_upload/query/models.py

@@ -0,0 +1,37 @@
+from pydantic import BaseModel, field_validator, model_serializer
+
+from notionary.file_upload.schemas import FileUploadStatus
+
+
+class FileUploadQuery(BaseModel):
+    status: FileUploadStatus | None = None
+    archived: bool | None = None
+
+    page_size_limit: int | None = None
+    total_results_limit: int | None = None
+
+    @field_validator("page_size_limit")
+    @classmethod
+    def validate_page_size(cls, value: int | None) -> int | None:
+        if value is None:
+            return None
+        return max(1, min(value, 100))
+
+    @field_validator("total_results_limit")
+    @classmethod
+    def validate_total_results(cls, value: int | None) -> int:
+        if value is None:
+            return 100
+        return max(1, value)
+
+    @model_serializer
+    def serialize_model(self) -> dict[str, str | bool | None]:
+        result = {}
+
+        if self.status is not None:
+            result["status"] = self.status
+
+        if self.archived is not None:
+            result["archived"] = self.archived
+
+        return result

notionary/file_upload/schemas.py

@@ -0,0 +1,78 @@
+from enum import StrEnum
+
+from pydantic import BaseModel, Field, model_validator
+
+
+class UploadMode(StrEnum):
+    SINGLE_PART = "single_part"
+    MULTI_PART = "multi_part"
+
+
+class FileUploadStatus(StrEnum):
+    PENDING = "pending"
+    UPLOADED = "uploaded"
+    FAILED = "failed"
+    EXPIRED = "expired"
+
+
+class FileUploadResponse(BaseModel):
+    id: str
+    created_time: str
+    last_edited_time: str
+    expiry_time: str | None = None
+    upload_url: str | None = None
+    archived: bool
+    status: FileUploadStatus
+    filename: str | None = None
+    content_type: str | None = None
+    content_length: int | None = None
+    request_id: str | None = None
+
+
+class FileUploadFilter(BaseModel):
+    status: FileUploadStatus | None = None
+    archived: bool | None = None
+
+
+class FileUploadListResponse(BaseModel):
+    results: list[FileUploadResponse]
+    next_cursor: str | None = None
+    has_more: bool
+
+
+class FileUploadCreateRequest(BaseModel):
+    filename: str = Field(..., max_length=900)
+    content_type: str | None = None
+    content_length: int | None = None
+    mode: UploadMode = UploadMode.SINGLE_PART
+    number_of_parts: int | None = Field(None, ge=1)
+
+    @model_validator(mode="after")
+    def validate_multipart_requirements(self):
+        if self.mode == UploadMode.MULTI_PART and self.number_of_parts is None:
+            raise ValueError("number_of_parts is required when mode is 'multi_part'")
+        if self.mode == UploadMode.SINGLE_PART and self.number_of_parts is not None:
+            raise ValueError("number_of_parts should not be provided for 'single_part' mode")
+        return self
+
+    def model_dump(self, **kwargs):
+        data = super().model_dump(**kwargs)
+        return {k: v for k, v in data.items() if v is not None}
+
+
+class FileUploadSendData(BaseModel):
+    file: bytes
+    part_number: int | None = Field(None, ge=1)
+
+
+class FileUploadCompleteRequest(BaseModel):
+    pass
+
+
+class FileUploadAttachment(BaseModel):
+    file_upload: dict[str, str]
+    name: str | None = None
+
+    @classmethod
+    def from_id(cls, file_upload_id: str, name: str | None = None):
+        return cls(type="file_upload", file_upload={"id": file_upload_id}, name=name)