notionary 0.2.16__py3-none-any.whl → 0.2.17__py3-none-any.whl

notionary/file_upload/notion_file_upload.py

@@ -0,0 +1,387 @@
+import asyncio
+import mimetypes
+from typing import Optional
+from pathlib import Path
+from datetime import datetime, timedelta
+from io import BytesIO
+
+
+from notionary.file_upload.models import FileUploadResponse
+from notionary.util import LoggingMixin
+
+
+class NotionFileUpload(LoggingMixin):
+    """
+    High-level service for managing Notion file uploads.
+    Handles both small file (single-part) and large file (multi-part) uploads.
+    """
+
+    # Notion's file size limits
+    SINGLE_PART_MAX_SIZE = 20 * 1024 * 1024  # 20MB
+    MULTI_PART_CHUNK_SIZE = 10 * 1024 * 1024  # 10MB per part
+    MAX_FILENAME_BYTES = 900
+
+    def __init__(self, token: Optional[str] = None):
+        """Initialize the file upload service."""
+        from notionary import NotionFileUploadClient
+
+        self.client = NotionFileUploadClient(token=token)
+
+    async def upload_file(
+        self, file_path: Path, filename: Optional[str] = None
+    ) -> Optional[FileUploadResponse]:
+        """
+        Upload a file to Notion, automatically choosing single-part or multi-part based on size.
+
+        Args:
+            file_path: Path to the file to upload
+            filename: Optional custom filename (defaults to file_path.name)
+
+        Returns:
+            FileUploadResponse if successful, None otherwise
+        """
+        if not file_path.exists():
+            self.logger.error("File does not exist: %s", file_path)
+            return None
+
+        file_size = file_path.stat().st_size
+        filename = filename or file_path.name
+
+        # Validate filename length
+        if len(filename.encode("utf-8")) > self.MAX_FILENAME_BYTES:
+            self.logger.error(
+                "Filename too long: %d bytes (max %d)",
+                len(filename.encode("utf-8")),
+                self.MAX_FILENAME_BYTES,
+            )
+            return None
+
+        # Choose upload method based on file size
+        if file_size <= self.SINGLE_PART_MAX_SIZE:
+            return await self._upload_small_file(file_path, filename, file_size)
+        else:
+            return await self._upload_large_file(file_path, filename, file_size)
+
+    async def upload_from_bytes(
+        self, file_content: bytes, filename: str, content_type: Optional[str] = None
+    ) -> Optional[FileUploadResponse]:
+        """
+        Upload file content from bytes.
+
+        Args:
+            file_content: File content as bytes
+            filename: Name for the file
+            content_type: Optional MIME type
+
+        Returns:
+            FileUploadResponse if successful, None otherwise
+        """
+        file_size = len(file_content)
+
+        # Validate filename length
+        if len(filename.encode("utf-8")) > self.MAX_FILENAME_BYTES:
+            self.logger.error(
+                "Filename too long: %d bytes (max %d)",
+                len(filename.encode("utf-8")),
+                self.MAX_FILENAME_BYTES,
+            )
+            return None
+
+        # Guess content type if not provided
+        if not content_type:
+            content_type, _ = mimetypes.guess_type(filename)
+
+        # Choose upload method based on size
+        if file_size <= self.SINGLE_PART_MAX_SIZE:
+            return await self._upload_small_file_from_bytes(
+                file_content, filename, content_type, file_size
+            )
+        else:
+            return await self._upload_large_file_from_bytes(
+                file_content, filename, content_type, file_size
+            )
+
+    async def get_upload_status(self, file_upload_id: str) -> Optional[str]:
+        """
+        Get the current status of a file upload.
+
+        Args:
+            file_upload_id: ID of the file upload
+
+        Returns:
+            Status string ("pending", "uploaded", etc.) or None if failed
+        """
+        upload_info = await self.client.retrieve_file_upload(file_upload_id)
+        return upload_info.status if upload_info else None
+
+    async def wait_for_upload_completion(
+        self, file_upload_id: str, timeout_seconds: int = 300, poll_interval: int = 2
+    ) -> Optional[FileUploadResponse]:
+        """
+        Wait for a file upload to complete.
+
+        Args:
+            file_upload_id: ID of the file upload
+            timeout_seconds: Maximum time to wait
+            poll_interval: Seconds between status checks
+
+        Returns:
+            FileUploadResponse when complete, None if timeout or failed
+        """
+        start_time = datetime.now()
+        timeout_delta = timedelta(seconds=timeout_seconds)
+
+        while datetime.now() - start_time < timeout_delta:
+            upload_info = await self.client.retrieve_file_upload(file_upload_id)
+
+            if not upload_info:
+                self.logger.error(
+                    "Failed to retrieve upload info for %s", file_upload_id
+                )
+                return None
+
+            if upload_info.status == "uploaded":
+                self.logger.info("Upload completed: %s", file_upload_id)
+                return upload_info
+            elif upload_info.status == "failed":
+                self.logger.error("Upload failed: %s", file_upload_id)
+                return None
+
+            await asyncio.sleep(poll_interval)
+
+        self.logger.warning("Upload timeout: %s", file_upload_id)
+        return None
+
+    async def list_recent_uploads(self, limit: int = 50) -> list[FileUploadResponse]:
+        """
+        List recent file uploads.
+
+        Args:
+            limit: Maximum number of uploads to return
+
+        Returns:
+            List of FileUploadResponse objects
+        """
+        uploads = []
+        start_cursor = None
+        remaining = limit
+
+        while remaining > 0:
+            page_size = min(remaining, 100)  # API max per request
+
+            response = await self.client.list_file_uploads(
+                page_size=page_size, start_cursor=start_cursor
+            )
+
+            if not response or not response.results:
+                break
+
+            uploads.extend(response.results)
+            remaining -= len(response.results)
+
+            if not response.has_more or not response.next_cursor:
+                break
+
+            start_cursor = response.next_cursor
+
+        return uploads[:limit]
+
+    async def _upload_small_file(
+        self, file_path: Path, filename: str, file_size: int
+    ) -> Optional[FileUploadResponse]:
+        """Upload a small file using single-part upload."""
+        content_type, _ = mimetypes.guess_type(str(file_path))
+
+        # Create file upload
+        file_upload = await self.client.create_file_upload(
+            filename=filename,
+            content_type=content_type,
+            content_length=file_size,
+            mode="single_part",
+        )
+
+        if not file_upload:
+            self.logger.error("Failed to create file upload for %s", filename)
+            return None
+
+        # Send file content
+        success = await self.client.send_file_from_path(
+            file_upload_id=file_upload.id, file_path=file_path
+        )
+
+        if not success:
+            self.logger.error("Failed to send file content for %s", filename)
+            return None
+
+        self.logger.info(
+            "Successfully uploaded file: %s (ID: %s)", filename, file_upload.id
+        )
+        return file_upload
+
+    async def _upload_large_file(
+        self, file_path: Path, filename: str, file_size: int
+    ) -> Optional[FileUploadResponse]:
+        """Upload a large file using multi-part upload."""
+        content_type, _ = mimetypes.guess_type(str(file_path))
+
+        # Create file upload with multi-part mode
+        file_upload = await self.client.create_file_upload(
+            filename=filename,
+            content_type=content_type,
+            content_length=file_size,
+            mode="multi_part",
+        )
+
+        if not file_upload:
+            self.logger.error(
+                "Failed to create multi-part file upload for %s", filename
+            )
+            return None
+
+        # Upload file in parts
+        success = await self._upload_file_parts(file_upload.id, file_path, file_size)
+
+        if not success:
+            self.logger.error("Failed to upload file parts for %s", filename)
+            return None
+
+        # Complete the upload
+        completed_upload = await self.client.complete_file_upload(file_upload.id)
+
+        if not completed_upload:
+            self.logger.error("Failed to complete file upload for %s", filename)
+            return None
+
+        self.logger.info(
+            "Successfully uploaded large file: %s (ID: %s)", filename, file_upload.id
+        )
+        return completed_upload
+
+    async def _upload_small_file_from_bytes(
+        self,
+        file_content: bytes,
+        filename: str,
+        content_type: Optional[str],
+        file_size: int,
+    ) -> Optional[FileUploadResponse]:
+        """Upload small file from bytes."""
+        # Create file upload
+        file_upload = await self.client.create_file_upload(
+            filename=filename,
+            content_type=content_type,
+            content_length=file_size,
+            mode="single_part",
+        )
+
+        if not file_upload:
+            return None
+
+        # Send file content
+        from io import BytesIO
+
+        success = await self.client.send_file_upload(
+            file_upload_id=file_upload.id,
+            file_content=BytesIO(file_content),
+            filename=filename,
+        )
+
+        return file_upload if success else None
+
+    async def _upload_large_file_from_bytes(
+        self,
+        file_content: bytes,
+        filename: str,
+        content_type: Optional[str],
+        file_size: int,
+    ) -> Optional[FileUploadResponse]:
+        """Upload large file from bytes using multi-part."""
+        # Create file upload
+        file_upload = await self.client.create_file_upload(
+            filename=filename,
+            content_type=content_type,
+            content_length=file_size,
+            mode="multi_part",
+        )
+
+        if not file_upload:
+            return None
+
+        # Upload in chunks
+        success = await self._upload_bytes_parts(file_upload.id, file_content)
+
+        if not success:
+            return None
+
+        # Complete the upload
+        return await self.client.complete_file_upload(file_upload.id)
+
+    async def _upload_file_parts(
+        self, file_upload_id: str, file_path: Path, file_size: int
+    ) -> bool:
+        """Upload file in parts for multi-part upload."""
+        part_number = 1
+        total_parts = (
+            file_size + self.MULTI_PART_CHUNK_SIZE - 1
+        ) // self.MULTI_PART_CHUNK_SIZE
+
+        try:
+            import aiofiles
+
+            async with aiofiles.open(file_path, "rb") as file:
+                while True:
+                    chunk = await file.read(self.MULTI_PART_CHUNK_SIZE)
+                    if not chunk:
+                        break
+
+                    success = await self.client.send_file_upload(
+                        file_upload_id=file_upload_id,
+                        file_content=BytesIO(chunk),
+                        filename=file_path.name,
+                        part_number=part_number,
+                    )
+
+                    if not success:
+                        self.logger.error(
+                            "Failed to upload part %d/%d", part_number, total_parts
+                        )
+                        return False
+
+                    self.logger.debug("Uploaded part %d/%d", part_number, total_parts)
+                    part_number += 1
+
+            self.logger.info("Successfully uploaded all %d parts", total_parts)
+            return True
+
+        except Exception as e:
+            self.logger.error("Error uploading file parts: %s", e)
+            return False
+
+    async def _upload_bytes_parts(
+        self, file_upload_id: str, file_content: bytes
+    ) -> bool:
+        """Upload bytes in parts for multi-part upload."""
+        part_number = 1
+        total_parts = (
+            len(file_content) + self.MULTI_PART_CHUNK_SIZE - 1
+        ) // self.MULTI_PART_CHUNK_SIZE
+
+        for i in range(0, len(file_content), self.MULTI_PART_CHUNK_SIZE):
+            chunk = file_content[i : i + self.MULTI_PART_CHUNK_SIZE]
+
+            success = await self.client.send_file_upload(
+                file_upload_id=file_upload_id,
+                file_content=BytesIO(chunk),
+                part_number=part_number,
+            )
+
+            if not success:
+                self.logger.error(
+                    "Failed to upload part %d/%d", part_number, total_parts
+                )
+                return False
+
+            self.logger.debug("Uploaded part %d/%d", part_number, total_parts)
+            part_number += 1
+
+        self.logger.info("Successfully uploaded all %d parts", total_parts)
+        return True

notionary/page/notion_page.py

@@ -14,7 +14,8 @@ from notionary.page.content.page_content_writer import PageContentWriter
 from notionary.page.property_formatter import NotionPropertyFormatter
 from notionary.page.utils import extract_property_value
 
-from notionary.util import LoggingMixin, format_uuid, FuzzyMatcher, factory_only
+from notionary.util import LoggingMixin, format_uuid, factory_only
+from notionary.util.fuzzy import find_best_match
 
 
 if TYPE_CHECKING:
@@ -101,7 +102,7 @@ class NotionPage(LoggingMixin):
                 cls.logger.warning("No pages found for name: %s", page_name)
                 raise ValueError(f"No pages found for name: {page_name}")
 
-            best_match = FuzzyMatcher.find_best_match(
+            best_match = find_best_match(
                 query=page_name,
                 items=search_results,
                 text_extractor=lambda page: page.title,
@@ -493,7 +494,7 @@ class NotionPage(LoggingMixin):
         """
         Create NotionPage instance from API response.
         """
-        from notionary.database.notion_database import NotionDatabase
+        from notionary.database.database import NotionDatabase
 
         title = cls._extract_title(page_response)
         emoji = cls._extract_emoji(page_response)

notionary/telemetry/views.py

@@ -25,6 +25,7 @@ class DatabaseFactoryUsedEvent(BaseTelemetryEvent):
     def name(self) -> str:
         return "database_factory_used"
 
+
 @dataclass
 class QueryOperationEvent(BaseTelemetryEvent):
     """Event fired when a query operation is performed"""
@@ -34,7 +35,8 @@ class QueryOperationEvent(BaseTelemetryEvent):
     @property
     def name(self) -> str:
         return "query_operation"
-    
+
+
 @dataclass
 class NotionMarkdownSyntaxPromptEvent(BaseTelemetryEvent):
     """Event fired when Notion Markdown syntax is used"""
@@ -43,12 +45,16 @@ class NotionMarkdownSyntaxPromptEvent(BaseTelemetryEvent):
     def name(self) -> str:
         return "notion_markdown_syntax_used"
 
+
 # Tracks markdown conversion
 @dataclass
 class MarkdownToNotionConversionEvent(BaseTelemetryEvent):
     """Event fired when markdown is converted to Notion blocks"""
-    handler_element_name: Optional[str] = None  # e.g. "HeadingElement", "ParagraphElement"
-    
+
+    handler_element_name: Optional[str] = (
+        None  # e.g. "HeadingElement", "ParagraphElement"
+    )
+
     @property
     def name(self) -> str:
         return "markdown_to_notion_conversion"
@@ -57,8 +63,11 @@ class MarkdownToNotionConversionEvent(BaseTelemetryEvent):
 @dataclass
 class NotionToMarkdownConversionEvent(BaseTelemetryEvent):
     """Event fired when Notion blocks are converted to markdown"""
-    handler_element_name: Optional[str] = None  # e.g. "HeadingElement", "ParagraphElement"  
-    
+
+    handler_element_name: Optional[str] = (
+        None  # e.g. "HeadingElement", "ParagraphElement"
+    )
+
     @property
     def name(self) -> str:
-        return "notion_to_markdown_conversion"
+        return "notion_to_markdown_conversion"

notionary/user/__init__.py

@@ -0,0 +1,11 @@
+from .notion_user import NotionUser
+from .notion_user_manager import NotionUserManager
+from .client import NotionUserClient
+from .notion_bot_user import NotionBotUser
+
+__all__ = [
+    "NotionUser",
+    "NotionUserManager",
+    "NotionUserClient",
+    "NotionBotUser",
+]

notionary/user/base_notion_user.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+from abc import ABC
+from typing import Optional
+from notionary.user.client import NotionUserClient
+
+from notionary.util import LoggingMixin
+
+
+class BaseNotionUser(LoggingMixin, ABC):
+    """
+    Base class for all Notion user types with common functionality.
+    """
+
+    def __init__(
+        self,
+        user_id: str,
+        name: Optional[str] = None,
+        avatar_url: Optional[str] = None,
+        token: Optional[str] = None,
+    ):
+        """Initialize base user properties."""
+        self._user_id = user_id
+        self._name = name
+        self._avatar_url = avatar_url
+        self.client = NotionUserClient(token=token)
+
+    @property
+    def id(self) -> str:
+        """Get the user ID."""
+        return self._user_id
+
+    @property
+    def name(self) -> Optional[str]:
+        """Get the user name."""
+        return self._name
+
+    @property
+    def avatar_url(self) -> Optional[str]:
+        """Get the avatar URL."""
+        return self._avatar_url
+
+    def get_display_name(self) -> str:
+        """Get a display name for the user."""
+        return self._name or f"User {self._user_id[:8]}"
+
+    def __str__(self) -> str:
+        """String representation of the user."""
+        return f"{self.__class__.__name__}(name='{self.get_display_name()}', id='{self._user_id[:8]}...')"
+
+    def __repr__(self) -> str:
+        """Detailed string representation."""
+        return self.__str__()

notionary/user/client.py

@@ -0,0 +1,129 @@
+from typing import Optional, List
+from notionary.base_notion_client import BaseNotionClient
+from notionary.user.models import (
+    NotionBotUserResponse,
+    NotionUserResponse,
+    NotionUsersListResponse,
+)
+from notionary.util import singleton
+
+
+@singleton
+class NotionUserClient(BaseNotionClient):
+    """
+    Client for Notion user-specific operations.
+    Inherits base HTTP functionality from BaseNotionClient.
+
+    Note: The Notion API only supports individual user queries and bot user info.
+    List users endpoint is available but only returns workspace members (no guests).
+    """
+
+    async def get_user(self, user_id: str) -> Optional[NotionUserResponse]:
+        """
+        Retrieve a user by their ID.
+        """
+        response = await self.get(f"users/{user_id}")
+        if response is None:
+            self.logger.error("Failed to fetch user %s - API returned None", user_id)
+            return None
+
+        try:
+            return NotionUserResponse.model_validate(response)
+        except Exception as e:
+            self.logger.error("Failed to validate user response for %s: %s", user_id, e)
+            return None
+
+    async def get_bot_user(self) -> Optional[NotionBotUserResponse]:
+        """
+        Retrieve your token's bot user information.
+        """
+        response = await self.get("users/me")
+        if response is None:
+            self.logger.error("Failed to fetch bot user - API returned None")
+            return None
+
+        try:
+            return NotionBotUserResponse.model_validate(response)
+        except Exception as e:
+            self.logger.error("Failed to validate bot user response: %s", e)
+            return None
+
+    async def list_users(
+        self, page_size: int = 100, start_cursor: Optional[str] = None
+    ) -> Optional[NotionUsersListResponse]:
+        """
+        List all users in the workspace (paginated).
+
+        Note: Guests are not included in the response.
+        """
+        params = {"page_size": min(page_size, 100)}  # API max is 100
+        if start_cursor:
+            params["start_cursor"] = start_cursor
+
+        response = await self.get("users", params=params)
+        if response is None:
+            self.logger.error("Failed to fetch users list - API returned None")
+            return None
+
+        try:
+            return NotionUsersListResponse.model_validate(response)
+        except Exception as e:
+            self.logger.error("Failed to validate users list response: %s", e)
+            return None
+
+    async def get_all_users(self) -> List[NotionUserResponse]:
+        """
+        Get all users in the workspace by handling pagination automatically.
+        """
+        all_users = []
+        start_cursor = None
+
+        while True:
+            try:
+                response = await self.list_users(
+                    page_size=100, start_cursor=start_cursor
+                )
+
+                if not response or not response.results:
+                    break
+
+                all_users.extend(response.results)
+
+                # Check if there are more pages
+                if not response.has_more or not response.next_cursor:
+                    break
+
+                start_cursor = response.next_cursor
+
+            except Exception as e:
+                self.logger.error("Error fetching all users: %s", str(e))
+                break
+
+        self.logger.info("Retrieved %d total users from workspace", len(all_users))
+        return all_users
+
+    async def get_workspace_name(self) -> Optional[str]:
+        """
+        Get the workspace name from the bot user.
+        """
+        try:
+            bot_user = await self.get_bot_user()
+            if bot_user and bot_user.bot and bot_user.bot.workspace_name:
+                return bot_user.bot.workspace_name
+            return None
+        except Exception as e:
+            self.logger.error("Error fetching workspace name: %s", str(e))
+            return None
+
+    async def get_workspace_limits(self) -> Optional[dict]:
+        """
+        Get workspace limits from the bot user.
+        """
+        try:
+            bot_user = await self.get_bot_user()
+            if bot_user and bot_user.bot and bot_user.bot.workspace_limits:
+                return bot_user.bot.workspace_limits.model_dump()
+            return None
+        except Exception as e:
+            self.logger.error("Error fetching workspace limits: %s", str(e))
+            return None