notionary 0.1.11__py3-none-any.whl → 0.1.13__py3-none-any.whl

notionary/page/notion_page_factory.py

@@ -0,0 +1,256 @@
+import logging
+from typing import List, Optional, Dict, Any
+from difflib import SequenceMatcher
+
+from notionary import NotionPage, NotionClient
+from notionary.util.logging_mixin import LoggingMixin
+from notionary.util.page_id_utils import format_uuid, extract_and_validate_page_id
+
+
+class NotionPageFactory(LoggingMixin):
+    """
+    Factory class for creating NotionPage instances.
+    Provides methods for creating page instances by page ID, URL, or name.
+    """
+
+    @classmethod
+    def class_logger(cls):
+        """Class logger - for class methods"""
+        return logging.getLogger(cls.__name__)
+
+    @classmethod
+    async def from_page_id(
+        cls, page_id: str, token: Optional[str] = None
+    ) -> NotionPage:
+        """
+        Create a NotionPage from a page ID.
+
+        Args:
+            page_id: The ID of the Notion page
+            token: Optional Notion API token (uses environment variable if not provided)
+
+        Returns:
+            An initialized NotionPage instance
+
+        Raises:
+            NotionError: If there is any error during page creation or connection
+        """
+        logger = cls.class_logger()
+
+        try:
+            formatted_id = format_uuid(page_id) or page_id
+
+            page = NotionPage(page_id=formatted_id, token=token)
+
+            logger.info("Successfully created page instance for ID: %s", formatted_id)
+            return page
+
+        except Exception as e:
+            error_msg = f"Error connecting to page {page_id}: {str(e)}"
+            logger.error(error_msg)
+
+    @classmethod
+    async def from_url(cls, url: str, token: Optional[str] = None) -> NotionPage:
+        """
+        Create a NotionPage from a Notion URL.
+
+        Args:
+            url: The URL of the Notion page
+            token: Optional Notion API token (uses environment variable if not provided)
+
+        Returns:
+            An initialized NotionPage instance
+
+        Raises:
+            NotionError: If there is any error during page creation or connection
+        """
+        logger = cls.class_logger()
+
+        try:
+            page_id = extract_and_validate_page_id(url=url)
+            if not page_id:
+                error_msg = f"Could not extract valid page ID from URL: {url}"
+                logger.error(error_msg)
+
+            page = NotionPage(page_id=page_id, url=url, token=token)
+
+            logger.info(
+                "Successfully created page instance from URL for ID: %s", page_id
+            )
+            return page
+
+        except Exception as e:
+            error_msg = f"Error connecting to page with URL {url}: {str(e)}"
+            logger.error(error_msg)
+
+    @classmethod
+    async def from_page_name(
+        cls, page_name: str, token: Optional[str] = None
+    ) -> NotionPage:
+        """
+        Create a NotionPage by finding a page with a matching name.
+        Uses fuzzy matching to find the closest match to the given name.
+        If no good match is found, suggests closest alternatives ("Did you mean?").
+
+        Args:
+            page_name: The name of the Notion page to search for
+            token: Optional Notion API token (uses environment variable if not provided)
+
+        Returns:
+            An initialized NotionPage instance
+
+        Raises:
+            NotionError: If there is any error during page search or connection
+            NotionPageNotFoundError: If no matching page found, includes suggestions
+        """
+        logger = cls.class_logger()
+        logger.debug("Searching for page with name: %s", page_name)
+
+        client = NotionClient(token=token)
+
+        try:
+            logger.debug("Using search endpoint to find pages")
+
+            search_payload = {
+                "filter": {"property": "object", "value": "page"},
+                "page_size": 100,
+            }
+
+            response = await client.post("search", search_payload)
+
+            if not response or "results" not in response:
+                error_msg = "Failed to fetch pages using search endpoint"
+                logger.error(error_msg)
+
+            pages = response.get("results", [])
+
+            if not pages:
+                error_msg = f"No pages found matching '{page_name}'"
+                logger.warning(error_msg)
+
+            logger.debug("Found %d pages, searching for best match", len(pages))
+
+            # Store all matches with their scores for potential suggestions
+            matches = []
+            best_match = None
+            best_score = 0
+
+            for page in pages:
+                title = cls._extract_title_from_page(page)
+                score = SequenceMatcher(None, page_name.lower(), title.lower()).ratio()
+
+                matches.append((page, title, score))
+
+                if score > best_score:
+                    best_score = score
+                    best_match = page
+
+            if best_score < 0.6 or not best_match:
+                # Sort matches by score in descending order
+                matches.sort(key=lambda x: x[2], reverse=True)
+
+                # Take top N suggestions (adjust as needed)
+                suggestions = [title for _, title, _ in matches[:5]]
+
+                error_msg = f"No good match found for '{page_name}'. Did you mean one of these?\n"
+                error_msg += "\n".join(f"- {suggestion}" for suggestion in suggestions)
+
+                logger.warning(
+                    "No good match found for '%s'. Best score: %.2f",
+                    page_name,
+                    best_score,
+                )
+
+            page_id = best_match.get("id")
+
+            if not page_id:
+                error_msg = "Best match page has no ID"
+                logger.error(error_msg)
+
+            matched_name = cls._extract_title_from_page(best_match)
+
+            logger.info(
+                "Found matching page: '%s' (ID: %s) with score: %.2f",
+                matched_name,
+                page_id,
+                best_score,
+            )
+
+            page = NotionPage(
+                page_id=page_id, title=matched_name, token=token
+            )
+
+            logger.info("Successfully created page instance for '%s'", matched_name)
+            await client.close()
+            return page
+
+        except Exception as e:
+            error_msg = f"Error finding page by name: {str(e)}"
+            logger.error(error_msg)
+
+    @classmethod
+    def _extract_title_from_page(cls, page: Dict[str, Any]) -> str:
+        """
+        Extract the title from a page object.
+
+        Args:
+            page: The page object returned from the Notion API
+
+        Returns:
+            The title of the page
+
+        Raises:
+            NotionError: If the title cannot be extracted
+        """
+        try:
+            if "properties" in page:
+                for prop_value in page["properties"].values():
+                    if prop_value.get("type") != "title":
+                        continue
+                    title_array = prop_value.get("title", [])
+                    if not title_array:
+                        continue
+                    return cls._extract_text_from_rich_text(title_array)
+
+            if "child_page" in page:
+                return page.get("child_page", {}).get("title", "Untitled")
+
+            return "Untitled"
+
+        except Exception as e:
+            error_msg = f"Error extracting page title: {str(e)}"
+            cls.class_logger().warning(error_msg)
+            return "Untitled"
+
+    @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 the Notion API
+
+        Returns:
+            The combined 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)
+
+
+async def demo():
+    clipboard = await NotionPageFactory.from_page_name("Jarvis Clipboard")
+    icon = await clipboard.get_icon()
+    print(f"Icon: {icon}")
+
+
+if __name__ == "__main__":
+    import asyncio
+
+    asyncio.run(demo())

notionary/{core/page → page}/properites/database_property_service.py

@@ -1,5 +1,5 @@
 from typing import Dict, List, Optional, Any, Tuple
-from notionary.core.notion_client import NotionClient
+from notionary.notion_client import NotionClient
 from notionary.util.logging_mixin import LoggingMixin
 
 
@@ -12,7 +12,7 @@ class DatabasePropertyService(LoggingMixin):
     def __init__(self, database_id: str, client: NotionClient):
         """
         Initialize the database property service.
-        
+
         Args:
             database_id: ID of the Notion database
             client: Instance of NotionClient
@@ -20,20 +20,20 @@ class DatabasePropertyService(LoggingMixin):
         self._database_id = database_id
         self._client = client
         self._schema = None
-    
+
     async def load_schema(self, force_refresh=False) -> bool:
         """
         Loads the database schema.
-        
+
         Args:
             force_refresh: Whether to force a refresh of the schema
-            
+
         Returns:
             bool: True if schema loaded successfully, False otherwise
         """
         if self._schema is not None and not force_refresh:
             return True
-            
+
         try:
             database = await self._client.get(f"databases/{self._database_id}")
             if database and "properties" in database:
@@ -41,290 +41,306 @@ class DatabasePropertyService(LoggingMixin):
                 self.logger.debug("Loaded schema for database %s", self._database_id)
                 return True
             else:
-                self.logger.error("Failed to load schema: missing 'properties' in response")
+                self.logger.error(
+                    "Failed to load schema: missing 'properties' in response"
+                )
                 return False
         except Exception as e:
             self.logger.error("Error loading database schema: %s", str(e))
             return False
-    
+
     async def _ensure_schema_loaded(self) -> None:
         """
         Ensures the schema is loaded before accessing it.
         """
         if self._schema is None:
             await self.load_schema()
-    
+
     async def get_schema(self) -> Dict[str, Any]:
         """
         Gets the database schema.
-        
+
         Returns:
             Dict[str, Any]: The database schema
         """
         await self._ensure_schema_loaded()
         return self._schema or {}
-    
+
     async def get_property_types(self) -> Dict[str, str]:
         """
         Gets all property types for the database.
-        
+
         Returns:
             Dict[str, str]: Dictionary mapping property names to their types
         """
         await self._ensure_schema_loaded()
-        
+
         if not self._schema:
             return {}
-            
+
         return {
             prop_name: prop_data.get("type", "unknown")
             for prop_name, prop_data in self._schema.items()
         }
-    
+
     async def get_property_schema(self, property_name: str) -> Optional[Dict[str, Any]]:
         """
         Gets the schema for a specific property.
-        
+
         Args:
             property_name: The name of the property
-            
+
         Returns:
             Optional[Dict[str, Any]]: The property schema or None if not found
         """
         await self._ensure_schema_loaded()
-        
+
         if not self._schema or property_name not in self._schema:
             return None
-            
+
         return self._schema[property_name]
-    
+
     async def get_property_type(self, property_name: str) -> Optional[str]:
         """
         Gets the type of a specific property.
-        
+
         Args:
             property_name: The name of the property
-            
+
         Returns:
             Optional[str]: The property type or None if not found
         """
         property_schema = await self.get_property_schema(property_name)
-        
+
         if not property_schema:
             return None
-            
+
         return property_schema.get("type")
-    
+
     async def property_exists(self, property_name: str) -> bool:
         """
         Checks if a property exists in the database.
-        
+
         Args:
             property_name: The name of the property
-            
+
         Returns:
             bool: True if the property exists, False otherwise
         """
         property_schema = await self.get_property_schema(property_name)
         return property_schema is not None
-    
+
     async def get_property_options(self, property_name: str) -> List[Dict[str, Any]]:
         """
         Gets the available options for a property (select, multi_select, status).
-        
+
         Args:
             property_name: The name of the property
-            
+
         Returns:
             List[Dict[str, Any]]: List of available options with their metadata
         """
         property_schema = await self.get_property_schema(property_name)
-        
+
         if not property_schema:
             return []
-            
+
         property_type = property_schema.get("type")
-        
+
         if property_type in ["select", "multi_select", "status"]:
             return property_schema.get(property_type, {}).get("options", [])
-            
+
         return []
-    
+
     async def get_option_names(self, property_name: str) -> List[str]:
         """
         Gets the available option names for a property (select, multi_select, status).
-        
+
         Args:
             property_name: The name of the property
-            
+
         Returns:
             List[str]: List of available option names
         """
         options = await self.get_property_options(property_name)
         return [option.get("name", "") for option in options]
-    
-    async def get_relation_details(self, property_name: str) -> Optional[Dict[str, Any]]:
+
+    async def get_relation_details(
+        self, property_name: str
+    ) -> Optional[Dict[str, Any]]:
         """
         Gets details about a relation property, including the related database.
-        
+
         Args:
             property_name: The name of the property
-            
+
         Returns:
             Optional[Dict[str, Any]]: The relation details or None if not a relation
         """
         property_schema = await self.get_property_schema(property_name)
-        
+
         if not property_schema or property_schema.get("type") != "relation":
             return None
-            
+
         return property_schema.get("relation", {})
-    
-    async def get_relation_options(self, property_name: str, limit: int = 100) -> List[Dict[str, Any]]:
+
+    async def get_relation_options(
+        self, property_name: str, limit: int = 100
+    ) -> List[Dict[str, Any]]:
         """
         Gets available options for a relation property by querying the related database.
-        
+
         Args:
             property_name: The name of the relation property
             limit: Maximum number of options to retrieve
-            
+
         Returns:
             List[Dict[str, Any]]: List of pages from the related database
         """
         relation_details = await self.get_relation_details(property_name)
-        
+
         if not relation_details or "database_id" not in relation_details:
             return []
-            
+
         related_db_id = relation_details["database_id"]
-        
+
         try:
             # Query the related database to get options
             query_result = await self._client.post(
                 f"databases/{related_db_id}/query",
                 {
                     "page_size": limit,
-                }
+                },
             )
-            
+
             if not query_result or "results" not in query_result:
                 return []
-                
+
             # Extract relevant information from each page
             options = []
             for page in query_result["results"]:
                 page_id = page.get("id")
                 title = self._extract_title_from_page(page)
-                
+
                 if page_id and title:
-                    options.append({
-                        "id": page_id,
-                        "name": title
-                    })
-                    
+                    options.append({"id": page_id, "name": title})
+
             return options
         except Exception as e:
             self.logger.error(f"Error getting relation options: {str(e)}")
             return []
-    
+
     def _extract_title_from_page(self, page: Dict[str, Any]) -> Optional[str]:
         """
         Extracts the title from a page object.
-        
+
         Args:
             page: The page object from Notion API
-            
+
         Returns:
             Optional[str]: The page title or None if not found
         """
         if "properties" not in page:
             return None
-            
+
         properties = page["properties"]
-        
+
         # Look for a title property
         for prop_data in properties.values():
             if prop_data.get("type") == "title" and "title" in prop_data:
                 title_parts = prop_data["title"]
-                return "".join([text_obj.get("plain_text", "") for text_obj in title_parts])
-                
+                return "".join(
+                    [text_obj.get("plain_text", "") for text_obj in title_parts]
+                )
+
         return None
-    
-    async def validate_property_value(self, property_name: str, value: Any) -> Tuple[bool, Optional[str], Optional[List[str]]]:
+
+    async def validate_property_value(
+        self, property_name: str, value: Any
+    ) -> Tuple[bool, Optional[str], Optional[List[str]]]:
         """
         Validates a value for a property.
-        
+
         Args:
             property_name: The name of the property
             value: The value to validate
-            
+
         Returns:
-            Tuple[bool, Optional[str], Optional[List[str]]]: 
+            Tuple[bool, Optional[str], Optional[List[str]]]:
                 - Boolean indicating if valid
                 - Error message if invalid
                 - Available options if applicable
         """
         property_schema = await self.get_property_schema(property_name)
-        
+
         if not property_schema:
             return False, f"Property '{property_name}' does not exist", None
-            
+
         property_type = property_schema.get("type")
-        
+
         # Validate select, multi_select, status properties
         if property_type in ["select", "status"]:
             options = await self.get_option_names(property_name)
-            
+
             if isinstance(value, str) and value not in options:
-                return False, f"Invalid {property_type} option. Value '{value}' is not in the available options.", options
-                
+                return (
+                    False,
+                    f"Invalid {property_type} option. Value '{value}' is not in the available options.",
+                    options,
+                )
+
         elif property_type == "multi_select":
             options = await self.get_option_names(property_name)
-            
+
             if isinstance(value, list):
                 invalid_values = [val for val in value if val not in options]
                 if invalid_values:
-                    return False, f"Invalid multi_select options: {', '.join(invalid_values)}", options
-        
+                    return (
+                        False,
+                        f"Invalid multi_select options: {', '.join(invalid_values)}",
+                        options,
+                    )
+
         return True, None, None
-    
-    async def get_database_metadata(self, include_types: Optional[List[str]] = None) -> Dict[str, Any]:
+
+    async def get_database_metadata(
+        self, include_types: Optional[List[str]] = None
+    ) -> Dict[str, Any]:
         """
         Gets the complete metadata of the database, including property options.
-        
+
         Args:
             include_types: List of property types to include (if None, include all)
-            
+
         Returns:
             Dict[str, Any]: The database metadata
         """
         await self._ensure_schema_loaded()
-        
+
         if not self._schema:
             return {"properties": {}}
-            
+
         metadata = {"properties": {}}
-        
+
         for prop_name, prop_data in self._schema.items():
             prop_type = prop_data.get("type")
-            
+
             # Skip if we're filtering and this type isn't included
             if include_types and prop_type not in include_types:
                 continue
-                
-            prop_metadata = {
-                "type": prop_type,
-                "options": []
-            }
-            
+
+            prop_metadata = {"type": prop_type, "options": []}
+
             # Include options for select, multi_select, status
             if prop_type in ["select", "multi_select", "status"]:
-                prop_metadata["options"] = prop_data.get(prop_type, {}).get("options", [])
-                
+                prop_metadata["options"] = prop_data.get(prop_type, {}).get(
+                    "options", []
+                )
+
             # For relation properties, we might want to include related database info
             elif prop_type == "relation":
                 prop_metadata["relation_details"] = prop_data.get("relation", {})
-                
+
             metadata["properties"][prop_name] = prop_metadata
-            
-        return metadata
+
+        return metadata