notionary 0.1.2__py3-none-any.whl → 0.1.3__py3-none-any.whl

notionary/core/database/notion_database_manager.py

@@ -0,0 +1,332 @@
+from typing import Any, AsyncGenerator, Dict, List, Optional, Union
+
+from notionary.core.database.database_info_service import DatabaseInfoService
+from notionary.core.database.database_query_service import DatabaseQueryService
+from notionary.core.database.database_schema_service import DatabaseSchemaService
+from notionary.core.database.models.page_result import PageResult
+from notionary.core.database.page_service import DatabasePageService
+from notionary.core.notion_client import NotionClient
+from notionary.core.database.notion_database_schema import NotionDatabaseSchema
+from notionary.core.database.notion_database_writer import DatabaseWritter
+from notionary.core.page.notion_page_manager import NotionPageManager
+from notionary.exceptions.database_exceptions import (
+    DatabaseInitializationError,
+    PropertyError,
+)
+from notionary.util.logging_mixin import LoggingMixin
+from notionary.util.uuid_utils import format_uuid
+
+
+class NotionDatabaseManager(LoggingMixin):
+    """
+    High-level facade for working with Notion databases.
+    Provides simplified operations for creating, reading, updating and deleting pages.
+
+    Note:
+        It is recommended to create instances of this class using the NotionDatabaseFactory
+        instead of directly calling the constructor.
+    """
+
+    def __init__(self, database_id: str, token: Optional[str] = None):
+        """
+        Initialize the database facade with a database ID.
+
+        Note:
+            It's recommended to use NotionDatabaseFactory to create instances of this class
+            rather than using this constructor directly.
+
+        Args:
+            database_id: The ID of the Notion database
+            token: Optional Notion API token (uses environment variable if not provided)
+        """
+        self.database_id = format_uuid(database_id) or database_id
+        self._client = NotionClient(token=token)
+        self._schema = NotionDatabaseSchema(self.database_id, self._client)
+        self._writer = DatabaseWritter(self._client, self._schema)
+        self._initialized = False
+
+        self._info_service = DatabaseInfoService(self._client, self.database_id)
+        self._page_service = DatabasePageService(
+            self._client, self._schema, self._writer
+        )
+        self._query_service = DatabaseQueryService(self._schema)
+        self._schema_service = DatabaseSchemaService(self._schema)
+
+    @property
+    def title(self) -> Optional[str]:
+        """Get the database title."""
+        return self._info_service.title
+
+    async def initialize(self) -> bool:
+        """
+        Initialize the database facade by loading the schema.
+
+        This method needs to be called after creating a new instance via the constructor.
+        When using NotionDatabaseFactory, this is called automatically.
+        """
+        try:
+            success = await self._schema.load()
+            if not success:
+                self.logger.error(
+                    "Failed to load schema for database %s", self.database_id
+                )
+                return False
+
+            await self._info_service.load_title()
+            self.logger.debug("Loaded database title: %s", self.title)
+
+            self._initialized = True
+            return True
+        except Exception as e:
+            self.logger.error("Error initializing database: %s", str(e))
+            return False
+
+    async def _ensure_initialized(self) -> None:
+        """
+        Ensure the database manager is initialized before use.
+
+        Raises:
+            DatabaseInitializationError: If the database isn't initialized
+        """
+        if not self._initialized:
+            raise DatabaseInitializationError(
+                self.database_id,
+                "Database manager not initialized. Call initialize() first.",
+            )
+
+    async def get_database_name(self) -> Optional[str]:
+        """
+        Get the name of the current database.
+
+        Returns:
+            The database name or None if it couldn't be retrieved
+        """
+        await self._ensure_initialized()
+
+        if self.title:
+            return self.title
+
+        try:
+            return await self._info_service.load_title()
+        except PropertyError as e:
+            self.logger.error("Error getting database name: %s", str(e))
+            return None
+
+    async def get_property_types(self) -> Dict[str, str]:
+        """
+        Get all property types for the database.
+
+        Returns:
+            Dictionary mapping property names to their types
+        """
+        await self._ensure_initialized()
+        return await self._schema_service.get_property_types()
+
+    async def get_select_options(self, property_name: str) -> List[Dict[str, str]]:
+        """
+        Get options for a select, multi-select, or status property.
+
+        Args:
+            property_name: Name of the property
+
+        Returns:
+            List of select options with name, id, and color (if available)
+        """
+        await self._ensure_initialized()
+        return await self._schema_service.get_select_options(property_name)
+
+    async def get_relation_options(
+        self, property_name: str, limit: int = 100
+    ) -> List[Dict[str, str]]:
+        """
+        Get available options for a relation property.
+
+        Args:
+            property_name: Name of the relation property
+            limit: Maximum number of options to retrieve
+
+        Returns:
+            List of relation options with id and title
+        """
+        await self._ensure_initialized()
+        return await self._schema_service.get_relation_options(property_name, limit)
+
+    async def create_page(
+        self,
+        properties: Dict[str, Any],
+        relations: Optional[Dict[str, Union[str, List[str]]]] = None,
+    ) -> PageResult:
+        """
+        Create a new page in the database.
+
+        Args:
+            properties: Dictionary of property names and values
+            relations: Optional dictionary of relation property names and titles
+
+        Returns:
+            Result object with success status and page information
+        """
+        await self._ensure_initialized()
+
+        result = await self._page_service.create_page(
+            self.database_id, properties, relations
+        )
+
+        if result["success"]:
+            self.logger.info(
+                "Created page %s in database %s",
+                result.get("page_id", ""),
+                self.database_id,
+            )
+        else:
+            self.logger.warning("Page creation failed: %s", result.get("message", ""))
+
+        return result
+
+    async def update_page(
+        self,
+        page_id: str,
+        properties: Optional[Dict[str, Any]] = None,
+        relations: Optional[Dict[str, Union[str, List[str]]]] = None,
+    ) -> PageResult:
+        """
+        Update an existing page.
+
+        Args:
+            page_id: The ID of the page to update
+            properties: Dictionary of property names and values to update
+            relations: Optional dictionary of relation property names and titles
+
+        Returns:
+            Result object with success status and message
+        """
+        await self._ensure_initialized()
+
+        self.logger.debug("Updating page %s", page_id)
+
+        result = await self._page_service.update_page(page_id, properties, relations)
+
+        if result["success"]:
+            self.logger.info("Successfully updated page %s", result.get("page_id", ""))
+        else:
+            self.logger.error(
+                "Error updating page %s: %s", page_id, result.get("message", "")
+            )
+
+        return result
+
+    async def delete_page(self, page_id: str) -> PageResult:
+        """
+        Delete (archive) a page.
+
+        Args:
+            page_id: The ID of the page to delete
+
+        Returns:
+            Result object with success status and message
+        """
+        await self._ensure_initialized()
+
+        self.logger.debug("Deleting page %s", page_id)
+
+        result = await self._page_service.delete_page(page_id)
+
+        if result["success"]:
+            self.logger.info("Successfully deleted page %s", result.get("page_id", ""))
+        else:
+            self.logger.error(
+                "Error deleting page %s: %s", page_id, result.get("message", "")
+            )
+
+        return result
+
+    async def get_pages(
+        self,
+        limit: int = 100,
+        filter_conditions: Optional[Dict[str, Any]] = None,
+        sorts: Optional[List[Dict[str, Any]]] = None,
+    ) -> List[NotionPageManager]:
+        """
+        Get all pages from the database.
+
+        Args:
+            limit: Maximum number of pages to retrieve
+            filter_conditions: Optional filter to apply to the database query
+            sorts: Optional sort instructions for the database query
+
+        Returns:
+            List of NotionPageManager instances for each page
+        """
+        await self._ensure_initialized()
+
+        self.logger.debug(
+            "Getting up to %d pages with filter: %s, sorts: %s",
+            limit,
+            filter_conditions,
+            sorts,
+        )
+
+        pages = await self._query_service.get_pages(
+            self.database_id, limit, filter_conditions, sorts
+        )
+
+        self.logger.debug(
+            "Retrieved %d pages from database %s", len(pages), self.database_id
+        )
+        return pages
+
+    async def iter_pages(
+        self,
+        page_size: int = 100,
+        filter_conditions: Optional[Dict[str, Any]] = None,
+        sorts: Optional[List[Dict[str, Any]]] = None,
+    ) -> AsyncGenerator[NotionPageManager, None]:
+        """
+        Asynchronous generator that yields pages from the database.
+
+        Args:
+            page_size: Number of pages to fetch per request
+            filter_conditions: Optional filter to apply to the database query
+            sorts: Optional sort instructions for the database query
+
+        Yields:
+            NotionPageManager instances for each page
+        """
+        await self._ensure_initialized()
+
+        self.logger.debug(
+            "Iterating pages with page_size: %d, filter: %s, sorts: %s",
+            page_size,
+            filter_conditions,
+            sorts,
+        )
+
+        async for page_manager in self._query_service.iter_pages(
+            self.database_id, page_size, filter_conditions, sorts
+        ):
+            yield page_manager
+
+    async def get_page_manager(self, page_id: str) -> Optional[NotionPageManager]:
+        """
+        Get a NotionPageManager for a specific page.
+
+        Args:
+            page_id: The ID of the page
+
+        Returns:
+            NotionPageManager instance or None if the page wasn't found
+        """
+        await self._ensure_initialized()
+
+        self.logger.debug("Getting page manager for page %s", page_id)
+
+        page_manager = await self._page_service.get_page_manager(page_id)
+
+        if not page_manager:
+            self.logger.error("Page %s not found", page_id)
+
+        return page_manager
+
+    async def close(self) -> None:
+        """Close the client connection."""
+        await self._client.close()

notionary/core/database/notion_database_manager_factory.py

@@ -0,0 +1,233 @@
+import logging
+from typing import List, Optional, Dict, Any
+from difflib import SequenceMatcher
+
+from notionary.core.notion_client import NotionClient
+from notionary.core.database.notion_database_manager import NotionDatabaseManager
+from notionary.exceptions.database_exceptions import (
+    DatabaseConnectionError,
+    DatabaseInitializationError,
+    DatabaseNotFoundException,
+    DatabaseParsingError,
+    NotionDatabaseException,
+)
+from notionary.util.logging_mixin import LoggingMixin
+from notionary.util.uuid_utils import format_uuid
+
+
+class NotionDatabaseFactory(LoggingMixin):
+    """
+    Factory class for creating NotionDatabaseManager instances.
+    Provides methods for creating managers by database ID or name.
+    """
+
+    @classmethod
+    def class_logger(cls):
+        """Class logger - for class methods"""
+        return logging.getLogger(cls.__name__)
+
+    @classmethod
+    async def from_database_id(
+        cls, database_id: str, token: Optional[str] = None
+    ) -> NotionDatabaseManager:
+        """
+        Create a NotionDatabaseManager from a database ID.
+
+        Args:
+            database_id: The ID of the Notion database
+            token: Optional Notion API token (uses environment variable if not provided)
+
+        Returns:
+            An initialized NotionDatabaseManager instance
+        """
+        logger = cls.class_logger()
+
+        try:
+            formatted_id = format_uuid(database_id) or database_id
+
+            manager = NotionDatabaseManager(formatted_id, token)
+
+            success = await manager.initialize()
+
+            if not success:
+                error_msg = (
+                    f"Failed to initialize database manager for ID: {formatted_id}"
+                )
+                logger.error(error_msg)
+                raise DatabaseInitializationError(formatted_id, error_msg)
+
+            logger.info(
+                lambda: f"Successfully created database manager for ID: {formatted_id}"
+            )
+            return manager
+
+        except DatabaseInitializationError:
+            # Re-raise the already typed exception
+            raise
+        except NotionDatabaseException:
+            # Re-raise other custom exceptions
+            raise
+        except Exception as e:
+            error_msg = f"Error connecting to database {database_id}: {str(e)}"
+            logger.error(error_msg)
+            raise DatabaseConnectionError(error_msg) from e
+
+    @classmethod
+    async def from_database_name(
+        cls, database_name: str, token: Optional[str] = None
+    ) -> NotionDatabaseManager:
+        """
+        Create a NotionDatabaseManager by finding a database with a matching name.
+        Uses fuzzy matching to find the closest match to the given name.
+
+        Args:
+            database_name: The name of the Notion database to search for
+            token: Optional Notion API token (uses environment variable if not provided)
+
+        Returns:
+            An initialized NotionDatabaseManager instance
+        """
+        logger = cls.class_logger()
+        logger.debug(lambda: f"Searching for database with name: {database_name}")
+
+        client = NotionClient(token=token)
+
+        try:
+            logger.debug("Using search endpoint to find databases")
+
+            # Create search query for databases
+            search_payload = {
+                "filter": {"property": "object", "value": "database"},
+                "page_size": 100,
+            }
+
+            # Perform search
+            response = await client.post("search", search_payload)
+
+            if not response or "results" not in response:
+                error_msg = "Failed to fetch databases using search endpoint"
+                logger.error(error_msg)
+                raise DatabaseConnectionError(error_msg)
+
+            databases = response.get("results", [])
+
+            if not databases:
+                error_msg = "No databases found"
+                logger.warning(error_msg)
+                raise DatabaseNotFoundException(database_name, error_msg)
+
+            logger.debug(
+                lambda: f"Found {len(databases)} databases, searching for best match"
+            )
+
+            # Find best match using fuzzy matching
+            best_match = None
+            best_score = 0
+
+            for db in databases:
+                title = cls._extract_title_from_database(db)
+
+                score = SequenceMatcher(
+                    None, database_name.lower(), title.lower()
+                ).ratio()
+
+                if score > best_score:
+                    best_score = score
+                    best_match = db
+
+            # Use a minimum threshold for match quality (0.6 = 60% similarity)
+            if best_score < 0.6 or not best_match:
+                error_msg = f"No good database name match found for '{database_name}'. Best match had score {best_score:.2f}"
+                logger.warning(error_msg)
+                raise DatabaseNotFoundException(database_name, error_msg)
+
+            database_id = best_match.get("id")
+
+            if not database_id:
+                error_msg = "Best match database has no ID"
+                logger.error(error_msg)
+                raise DatabaseParsingError(error_msg)
+
+            matched_name = cls._extract_title_from_database(best_match)
+
+            logger.info(
+                lambda: f"Found matching database: '{matched_name}' (ID: {database_id}) with score: {best_score:.2f}"
+            )
+
+            manager = NotionDatabaseManager(database_id, token)
+            success = await manager.initialize()
+
+            if not success:
+                error_msg = (
+                    f"Failed to initialize database manager for database {database_id}"
+                )
+                logger.error(error_msg)
+                raise DatabaseInitializationError(database_id, error_msg)
+
+            logger.info(
+                lambda: f"Successfully created database manager for '{matched_name}'"
+            )
+            await client.close()
+            return manager
+
+        except NotionDatabaseException:
+            await client.close()
+            raise
+        except Exception as e:
+            error_msg = f"Error finding database by name: {str(e)}"
+            logger.error(error_msg)
+            await client.close()
+            raise DatabaseConnectionError(error_msg) from e
+
+    @classmethod
+    def _extract_title_from_database(cls, database: Dict[str, Any]) -> str:
+        """
+        Extract the title from a database object.
+
+        Args:
+            database: A database object from the Notion API
+
+        Returns:
+            The extracted title or "Untitled" if no title is found
+
+        Raises:
+            DatabaseParsingError: If there's an error parsing the database title
+        """
+        try:
+            # Check for title in the root object
+            if "title" in database:
+                return cls._extract_text_from_rich_text(database["title"])
+
+            # Check for title in properties
+            if "properties" in database and "title" in database["properties"]:
+                title_prop = database["properties"]["title"]
+                if "title" in title_prop:
+                    return cls._extract_text_from_rich_text(title_prop["title"])
+
+            return "Untitled"
+
+        except Exception as e:
+            error_msg = f"Error extracting database title: {str(e)}"
+            cls.class_logger().warning(error_msg)
+            raise DatabaseParsingError(error_msg) from e
+
+    @classmethod
+    def _extract_text_from_rich_text(cls, rich_text: List[Dict[str, Any]]) -> str:
+        """
+        Extract plain text from a rich text array.
+
+        Args:
+            rich_text: A list of rich text objects from Notion API
+
+        Returns:
+            The concatenated plain text content
+        """
+        if not rich_text:
+            return ""
+
+        text_parts = []
+        for text_obj in rich_text:
+            if "plain_text" in text_obj:
+                text_parts.append(text_obj["plain_text"])
+
+        return "".join(text_parts)