notionary 0.2.15__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,16 +494,14 @@ 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)
         parent_database_id = cls._extract_parent_database_id(page_response)
 
         parent_database = (
-            await NotionDatabase.from_database_id(
-                id=parent_database_id, token=token
-            )
+            await NotionDatabase.from_database_id(id=parent_database_id, token=token)
             if parent_database_id
             else None
         )

notionary/telemetry/__init__.py

@@ -0,0 +1,19 @@
+from .service import ProductTelemetry
+from .views import (
+    BaseTelemetryEvent,
+    DatabaseFactoryUsedEvent,
+    QueryOperationEvent,
+    NotionMarkdownSyntaxPromptEvent,
+    MarkdownToNotionConversionEvent,
+    NotionToMarkdownConversionEvent,
+)
+
+__all__ = [
+    "ProductTelemetry",
+    "BaseTelemetryEvent",
+    "DatabaseFactoryUsedEvent",
+    "QueryOperationEvent",
+    "NotionMarkdownSyntaxPromptEvent",
+    "MarkdownToNotionConversionEvent",
+    "NotionToMarkdownConversionEvent",
+]

notionary/telemetry/service.py

@@ -0,0 +1,136 @@
+import os
+import uuid
+from pathlib import Path
+from typing import Dict, Any, Optional
+from posthog import Posthog
+from dotenv import load_dotenv
+
+from notionary.telemetry.views import BaseTelemetryEvent
+from notionary.util import SingletonMetaClass, LoggingMixin
+
+load_dotenv()
+
+POSTHOG_EVENT_SETTINGS = {
+    "process_person_profile": True,
+}
+
+
+class ProductTelemetry(LoggingMixin, metaclass=SingletonMetaClass):
+    """
+    Anonymous telemetry for Notionary - enabled by default.
+    Disable via: ANONYMIZED_NOTIONARY_TELEMETRY=false
+    """
+
+    USER_ID_PATH = str(Path.home() / ".cache" / "notionary" / "telemetry_user_id")
+    PROJECT_API_KEY = "phc_gItKOx21Tc0l07C1taD0QPpqFnbWgWjVfRjF6z24kke"
+    HOST = "https://eu.i.posthog.com"
+    UNKNOWN_USER_ID = "UNKNOWN"
+
+    _logged_init_message = False
+    _curr_user_id = None
+
+    def __init__(self):
+        # Default: enabled, disable via environment variable
+        telemetry_setting = os.getenv("ANONYMIZED_NOTIONARY_TELEMETRY", "true").lower()
+        telemetry_disabled = telemetry_setting == "false"
+        self.debug_logging = os.getenv("NOTIONARY_DEBUG", "false").lower() == "true"
+
+        if telemetry_disabled:
+            self._posthog_client = None
+        else:
+            if not self._logged_init_message:
+                self.logger.info(
+                    "Anonymous telemetry enabled to improve Notionary. "
+                    "To disable: export ANONYMIZED_NOTIONARY_TELEMETRY=false"
+                )
+                self._logged_init_message = True
+
+            self._posthog_client = Posthog(
+                project_api_key=self.PROJECT_API_KEY,
+                host=self.HOST,
+                disable_geoip=True,
+                enable_exception_autocapture=True,
+            )
+
+            # Silence posthog's logging unless debug mode
+            if not self.debug_logging:
+                import logging
+
+                posthog_logger = logging.getLogger("posthog")
+                posthog_logger.disabled = True
+
+        if self._posthog_client is None:
+            self.logger.debug("Telemetry disabled")
+
+    def capture(self, event: BaseTelemetryEvent) -> None:
+        """
+        Safe event tracking that never affects library functionality
+
+        Args:
+            event: BaseTelemetryEvent instance to capture
+        """
+        if self._posthog_client is None:
+            return
+
+        self._direct_capture(event)
+
+    def _direct_capture(self, event: BaseTelemetryEvent) -> None:
+        """
+        Direct capture method - PostHog handles threading internally
+        Should not be thread blocking because posthog magically handles it
+        """
+        if self._posthog_client is None:
+            return
+
+        try:
+            self._posthog_client.capture(
+                distinct_id=self.user_id,
+                event=event.name,
+                properties={
+                    "library": "notionary",
+                    **event.properties,
+                    **POSTHOG_EVENT_SETTINGS,
+                },
+            )
+
+        except Exception as e:
+            self.logger.error(f"Failed to send telemetry event {event.name}: {e}")
+
+    def flush(self) -> None:
+        """
+        Flush pending events - simplified without threading complexity
+        """
+        if not self._posthog_client:
+            self.logger.debug("PostHog client not available, skipping flush.")
+            return
+
+        try:
+            self._posthog_client.flush()
+            self.logger.debug("PostHog client telemetry queue flushed.")
+        except Exception as e:
+            self.logger.error(f"Failed to flush PostHog client: {e}")
+
+    @property
+    def user_id(self) -> str:
+        """Anonymous, persistent user ID"""
+        if self._curr_user_id:
+            return self._curr_user_id
+
+        # File access may fail due to permissions or other reasons.
+        # We don't want to crash so we catch all exceptions.
+        try:
+            if not os.path.exists(self.USER_ID_PATH):
+                os.makedirs(os.path.dirname(self.USER_ID_PATH), exist_ok=True)
+                with open(self.USER_ID_PATH, "w") as f:
+                    new_user_id = str(uuid.uuid4())
+                    f.write(new_user_id)
+                self._curr_user_id = new_user_id
+            else:
+                with open(self.USER_ID_PATH, "r") as f:
+                    self._curr_user_id = f.read().strip()
+
+            return self._curr_user_id
+        except Exception as e:
+            self.logger.debug(f"Error getting user ID: {e}")
+            self._curr_user_id = self.UNKNOWN_USER_ID
+            return self._curr_user_id

notionary/telemetry/views.py

@@ -0,0 +1,73 @@
+from abc import ABC, abstractmethod
+from dataclasses import asdict, dataclass
+from typing import Any, Optional
+
+
+@dataclass
+class BaseTelemetryEvent(ABC):
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        pass
+
+    @property
+    def properties(self) -> dict[str, Any]:
+        return {k: v for k, v in asdict(self).items() if k != "name"}
+
+
+@dataclass
+class DatabaseFactoryUsedEvent(BaseTelemetryEvent):
+    """Event fired when a database factory method is used"""
+
+    factory_method: str
+
+    @property
+    def name(self) -> str:
+        return "database_factory_used"
+
+
+@dataclass
+class QueryOperationEvent(BaseTelemetryEvent):
+    """Event fired when a query operation is performed"""
+
+    query_type: str
+
+    @property
+    def name(self) -> str:
+        return "query_operation"
+
+
+@dataclass
+class NotionMarkdownSyntaxPromptEvent(BaseTelemetryEvent):
+    """Event fired when Notion Markdown syntax is used"""
+
+    @property
+    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"
+    )
+
+    @property
+    def name(self) -> str:
+        return "markdown_to_notion_conversion"
+
+
+@dataclass
+class NotionToMarkdownConversionEvent(BaseTelemetryEvent):
+    """Event fired when Notion blocks are converted to markdown"""
+
+    handler_element_name: Optional[str] = (
+        None  # e.g. "HeadingElement", "ParagraphElement"
+    )
+
+    @property
+    def name(self) -> str:
+        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",
+]