notionary 0.1.6__py3-none-any.whl → 0.1.7__py3-none-any.whl

notionary/core/page/relations/notion_page_relation_manager.py

@@ -0,0 +1,364 @@
+from typing import Any, Dict, List, Optional
+from notionary.core.notion_client import NotionClient
+from notionary.core.page.relations.notion_page_title_resolver import NotionPageTitleResolver
+from notionary.core.page.relations.relation_operation_result import RelationOperationResult
+from notionary.util.logging_mixin import LoggingMixin
+from notionary.util.page_id_utils import is_valid_uuid
+
+class NotionRelationManager(LoggingMixin):
+    """
+    Manager for relation properties of a Notion page.
+    Manages links between pages and loads available relation options.
+    """
+
+    def __init__(self, page_id: str, client: NotionClient, database_id: Optional[str] = None):
+        """
+        Initializes the relation manager.
+
+        Args:
+            page_id: ID of the Notion page
+            client: NotionClient instance
+            database_id: Optional, ID of the database the page belongs to (loaded if needed)
+        """
+        self._page_id = page_id
+        self._client = client
+        self._database_id = database_id
+        self._page_properties = None
+
+        self._page_title_resolver = NotionPageTitleResolver(client=client)
+
+    async def _get_page_properties(self, force_refresh: bool = False) -> Dict[str, Any]:
+        """
+        Loads the properties of the page.
+
+        Args:
+            force_refresh: If True, a fresh API call will be made
+
+        Returns:
+            Dict[str, Any]: The properties of the page
+        """
+        if self._page_properties is None or force_refresh:
+            page_data = await self._client.get_page(self._page_id)
+            if page_data and "properties" in page_data:
+                self._page_properties = page_data["properties"]
+            else:
+                self._page_properties = {}
+
+        return self._page_properties
+
+    async def _ensure_database_id(self) -> Optional[str]:
+        """
+        Ensures the database_id is available. Loads it if necessary.
+
+        Returns:
+            Optional[str]: The database ID or None
+        """
+        if self._database_id:
+            return self._database_id
+
+        page_data = await self._client.get_page(self._page_id)
+        if page_data and "parent" in page_data:
+            parent = page_data["parent"]
+            if parent.get("type") == "database_id":
+                self._database_id = parent.get("database_id")
+                return self._database_id
+
+        return None
+
+    async def get_relation_property_ids(self) -> List[str]:
+        """
+        Returns a list of all relation property names.
+
+        Returns:
+            List[str]: Names of all relation properties
+        """
+        properties = await self._get_page_properties()
+
+        return [
+            prop_name for prop_name, prop_data in properties.items()
+            if prop_data.get("type") == "relation"
+        ]
+
+    async def get_relation_values(self, property_name: str) -> List[str]:
+        """
+        Returns the current relation values for a property.
+
+        Args:
+            property_name: Name of the relation property
+
+        Returns:
+            List[str]: List of linked page IDs
+        """
+        properties = await self._get_page_properties()
+
+        if property_name not in properties:
+            return []
+
+        prop_data = properties[property_name]
+
+        if prop_data.get("type") != "relation" or "relation" not in prop_data:
+            return []
+
+        return [rel.get("id") for rel in prop_data["relation"]]
+
+    async def get_relation_details(self, property_name: str) -> Optional[Dict[str, Any]]:
+        """
+        Returns details about the relation property, including the linked database.
+
+        Args:
+            property_name: Name of the relation property
+
+        Returns:
+            Optional[Dict[str, Any]]: Relation details or None
+        """
+        database_id = await self._ensure_database_id()
+        if not database_id:
+            return None
+
+        try:
+            database = await self._client.get(f"databases/{database_id}")
+            if not database or "properties" not in database:
+                return None
+
+            properties = database["properties"]
+
+            if property_name not in properties:
+                return None
+
+            prop_data = properties[property_name]
+
+            if prop_data.get("type") != "relation":
+                return None
+
+            return prop_data.get("relation", {})
+
+        except Exception as e:
+            self.logger.error("Error retrieving relation details: %s", str(e))
+            return None
+
+    async def get_relation_database_id(self, property_name: str) -> Optional[str]:
+        """
+        Returns the ID of the linked database for a relation property.
+
+        Args:
+            property_name: Name of the relation property
+
+        Returns:
+            Optional[str]: ID of the linked database or None
+        """
+        relation_details = await self.get_relation_details(property_name)
+
+        if not relation_details:
+            return None
+
+        return relation_details.get("database_id")
+
+    async def get_relation_options(self, property_name: str, limit: int = 100) -> List[Dict[str, Any]]:
+        """
+        Returns available options for a relation property.
+
+        Args:
+            property_name: Name of the relation property
+            limit: Maximum number of options to return
+
+        Returns:
+            List[Dict[str, Any]]: List of available options with ID and name
+        """
+        related_db_id = await self.get_relation_database_id(property_name)
+
+        if not related_db_id:
+            return []
+
+        try:
+            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 []
+
+            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
+                    })
+
+            return options
+        except Exception as e:
+            self.logger.error("Error retrieving relation options: %s", 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 the Notion API
+
+        Returns:
+            Optional[str]: The page title or None
+        """
+        if "properties" not in page:
+            return None
+
+        properties = page["properties"]
+
+        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 None
+
+    async def add_relation(self, property_name: str, page_ids: List[str]) -> Optional[Dict[str, Any]]:
+        """
+        Adds one or more relations.
+
+        Args:
+            property_name: Name of the relation property
+            page_ids: List of page IDs to add
+
+        Returns:
+            Optional[Dict[str, Any]]: API response or None on error
+        """
+        existing_relations = await self.get_relation_values(property_name) or []
+
+        all_relations = list(set(existing_relations + page_ids))
+
+        relation_payload = {
+            "relation": [{"id": page_id} for page_id in all_relations]
+        }
+
+        try:
+            result = await self._client.patch(
+                f"pages/{self._page_id}",
+                {
+                    "properties": {
+                        property_name: relation_payload
+                    }
+                },
+            )
+
+            self._page_properties = None
+
+            return result
+        except Exception as e:
+            self.logger.error("Error adding relation: %s", str(e))
+            return None
+
+    async def add_relation_by_name(self, property_name: str, page_titles: List[str]) -> RelationOperationResult:
+        """
+        Adds one or more relations based on page titles.
+
+        Args:
+            property_name: Name of the relation property
+            page_titles: List of page titles to link
+
+        Returns:
+            RelationOperationResult: Result of the operation with details on which pages were found and added
+        """
+        found_pages = []
+        not_found_pages = []
+        page_ids = []
+        
+        self.logger.info("Attempting to add %d relation(s) to property '%s'", len(page_titles), property_name)
+        
+        for page in page_titles:
+            if is_valid_uuid(page):
+                page_ids.append(page)
+                found_pages.append(page)
+                self.logger.debug("Using page ID directly: %s", page)
+            else:
+                page_id = await self._page_title_resolver.get_page_id_by_title(page)
+                if page_id:
+                    page_ids.append(page_id)
+                    found_pages.append(page)
+                    self.logger.debug("Found page ID %s for title '%s'", page_id, page)
+                else:
+                    not_found_pages.append(page)
+                    self.logger.warning("No page found with title '%s'", page)
+
+        if not page_ids:
+            self.logger.warning("No valid page IDs found for any of the titles, no changes applied")
+            return RelationOperationResult.from_no_pages_found(property_name, not_found_pages)
+
+        api_response = await self.add_relation(property_name, page_ids)
+        
+        if api_response:
+            result = RelationOperationResult.from_success(
+                property_name=property_name,
+                found_pages=found_pages,
+                not_found_pages=not_found_pages,
+                page_ids_added=page_ids,
+                api_response=api_response
+            )
+            
+            if not_found_pages:
+                not_found_str = "', '".join(not_found_pages)
+                self.logger.info("Added %d relation(s) to '%s', but couldn't find pages: '%s'", 
+                                len(page_ids), property_name, not_found_str)
+            else:
+                self.logger.info("Successfully added all %d relation(s) to '%s'", 
+                                len(page_ids), property_name)
+                
+            return result
+        
+        self.logger.error("Failed to add relations to '%s' (API error)", property_name)
+        return RelationOperationResult.from_no_api_response(
+            property_name=property_name,
+            found_pages=found_pages,
+            page_ids_added=page_ids
+        )
+
+    async def set_relations(self, property_name: str, page_ids: List[str]) -> Optional[Dict[str, Any]]:
+        """
+        Sets the relations to the specified IDs (replaces existing ones).
+
+        Args:
+            property_name: Name of the relation property
+            page_ids: List of page IDs to set
+
+        Returns:
+            Optional[Dict[str, Any]]: API response or None on error
+        """
+        relation_payload = {
+            "relation": [{"id": page_id} for page_id in page_ids]
+        }
+
+        try:
+            result = await self._client.patch(
+                f"pages/{self._page_id}",
+                {
+                    "properties": {
+                        property_name: relation_payload
+                    }
+                },
+            )
+
+            self._page_properties = None
+
+            return result
+        except Exception as e:
+            self.logger.error("Error setting relations: %s", str(e))
+            return None
+        
+    async def get_all_relations(self) -> Dict[str, List[str]]:
+        """ Returns all relation properties and their values.
+        """
+        relation_properties = await self.get_relation_property_ids()
+        if not relation_properties:
+            return {}
+            
+        result = {}
+        for prop_name in relation_properties:
+            result[prop_name] = await self.get_relation_values(prop_name)
+            
+        return result

notionary/core/page/relations/notion_page_title_resolver.py

@@ -0,0 +1,43 @@
+from typing import Optional
+from notionary.core.notion_client import NotionClient
+from notionary.util.logging_mixin import LoggingMixin
+
+
+class NotionPageTitleResolver(LoggingMixin):
+    def __init__(self, client: NotionClient):
+        self._client = client
+        
+    async def get_page_id_by_title(self, title: str) -> Optional[str]:
+        """
+        Searches for a Notion page by its title and returns the corresponding page ID if found.
+        """
+        try:
+            search_results = await self._client.post(
+                "search",
+                {
+                    "query": title,
+                    "filter": {
+                        "value": "page",
+                        "property": "object"
+                    }
+                }
+            )
+
+            for result in search_results.get("results", []):
+                properties = result.get("properties", {})
+
+                for prop_value in properties.values():
+                    if prop_value.get("type") == "title":
+                        title_texts = prop_value.get("title", [])
+
+                        page_title = " ".join([t.get("plain_text", "") for t in title_texts])
+
+                        if page_title == title or title in page_title:
+                            self.logger.debug("Found page: '%s' with ID: %s", page_title, result.get("id"))
+                            return result.get("id")
+
+            self.logger.debug("No page found with title '%s'", title)
+            return None
+        except Exception as e:
+            self.logger.error("Error while searching for page '%s': %s", title, e)
+            return None

notionary/core/page/relations/page_database_relation.py

@@ -0,0 +1,70 @@
+from typing import Dict, Optional, Any
+from notionary.core.notion_client import NotionClient
+from notionary.util.logging_mixin import LoggingMixin
+
+
+class PageDatabaseRelation(LoggingMixin):
+    """
+    Manages the relationship between a Notion page and its parent database.
+    Provides methods to access database schema and property options.
+    """
+    
+    def __init__(self, page_id: str, client: NotionClient):
+        """
+        Initialize the page-database relationship handler.
+        
+        Args:
+            page_id: ID of the Notion page
+            client: Instance of NotionClient
+        """
+        self._page_id = page_id
+        self._client = client
+        self._parent_database_id = None
+        self._database_schema = None
+        self._page_data = None
+    
+    async def _get_page_data(self, force_refresh=False) -> Dict[str, Any]:
+        """
+        Gets the page data and caches it for future use.
+        
+        Args:
+            force_refresh: Whether to force a refresh of the page data
+            
+        Returns:
+            Dict[str, Any]: The page data
+        """
+        if self._page_data is None or force_refresh:
+            self._page_data = await self._client.get_page(self._page_id)
+        return self._page_data
+    
+    async def get_parent_database_id(self) -> Optional[str]:
+        """
+        Gets the ID of the database this page belongs to, if any.
+        
+        Returns:
+            Optional[str]: The database ID or None if the page doesn't belong to a database
+        """
+        if self._parent_database_id is not None:
+            return self._parent_database_id
+            
+        page_data = await self._get_page_data()
+        
+        if not page_data or "parent" not in page_data:
+            return None
+            
+        parent = page_data.get("parent", {})
+        if parent.get("type") == "database_id":
+            self._parent_database_id = parent.get("database_id")
+            return self._parent_database_id
+            
+        return None
+    
+    async def is_database_page(self) -> bool:
+        """
+        Checks if this page belongs to a database.
+        
+        Returns:
+            bool: True if the page belongs to a database, False otherwise
+        """
+        database_id = await self.get_parent_database_id()
+        return database_id is not None

notionary/core/page/relations/relation_operation_result.py

@@ -0,0 +1,135 @@
+from typing import Any, Dict, List, Optional
+from dataclasses import dataclass, field
+
+@dataclass
+class RelationOperationResult:
+    """
+    Result of a relation operation in Notion.
+    
+    Attributes:
+        success: Whether the operation was successful overall
+        property_name: Name of the affected relation property
+        found_pages: List of page titles/IDs that were successfully found
+        not_found_pages: List of page titles that could not be found
+        page_ids_added: List of page IDs that were added to the relation
+        error: Error message, if any
+        api_response: The original API response
+    """
+    success: bool
+    property_name: str
+    found_pages: List[str] = field(default_factory=list)
+    not_found_pages: List[str] = field(default_factory=list)
+    page_ids_added: List[str] = field(default_factory=list)
+    error: Optional[str] = None
+    api_response: Optional[Dict[str, Any]] = None
+    
+    NO_API_RESPONSE = "Failed to update relation (no API response)"
+    NO_PAGES_FOUND = "No valid pages found for relation"
+    
+    @classmethod
+    def from_success(cls, property_name: str, 
+                     found_pages: List[str], 
+                     page_ids_added: List[str], 
+                     api_response: Dict[str, Any],
+                     not_found_pages: Optional[List[str]] = None) -> "RelationOperationResult":
+        """Creates a success result."""
+        return cls(
+            success=True, 
+            property_name=property_name,
+            found_pages=found_pages,
+            not_found_pages=not_found_pages or [],
+            page_ids_added=page_ids_added,
+            api_response=api_response
+        )
+    
+    @classmethod
+    def from_error(cls, property_name: str, 
+                  error: str,
+                  found_pages: Optional[List[str]] = None,
+                  not_found_pages: Optional[List[str]] = None,
+                  page_ids_added: Optional[List[str]] = None) -> "RelationOperationResult":
+        """Creates an error result."""
+        return cls(
+            success=False,
+            property_name=property_name,
+            found_pages=found_pages or [],
+            not_found_pages=not_found_pages or [],
+            page_ids_added=page_ids_added or [],
+            error=error
+        )
+    
+    @classmethod
+    def from_no_pages_found(cls, property_name: str, 
+                            not_found_pages: List[str]) -> "RelationOperationResult":
+        """Creates a standardized result for when no pages were found."""
+        return cls.from_error(
+            property_name=property_name,
+            error=cls.NO_PAGES_FOUND,
+            not_found_pages=not_found_pages
+        )
+
+    @classmethod
+    def from_no_api_response(cls, property_name: str, 
+                            found_pages: List[str],
+                            page_ids_added: List[str]) -> "RelationOperationResult":
+        """Creates a standardized result for a missing API response."""
+        return cls.from_error(
+            property_name=property_name,
+            error=cls.NO_API_RESPONSE,
+            found_pages=found_pages,
+            page_ids_added=page_ids_added
+        )
+    
+    @property
+    def has_not_found_pages(self) -> bool:
+        """Returns True if there were any pages that couldn't be found."""
+        return len(self.not_found_pages) > 0
+    
+    @property
+    def has_found_pages(self) -> bool:
+        """Returns True if any pages were found."""
+        return len(self.found_pages) > 0
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Converts the result to a dictionary."""
+        result = {
+            "success": self.success,
+            "property": self.property_name,
+        }
+        
+        if self.found_pages:
+            result["found_pages"] = self.found_pages
+            
+        if self.not_found_pages:
+            result["not_found_pages"] = self.not_found_pages
+            
+        if self.page_ids_added:
+            result["page_ids_added"] = self.page_ids_added
+        
+        if not self.success:
+            result["error"] = self.error
+            
+        if self.api_response:
+            result["api_response"] = self.api_response
+            
+        return result
+    
+    def __str__(self) -> str:
+        """String representation of the result."""
+        if self.success:
+            base = f"Success: Added {len(self.page_ids_added)} relation(s) to property '{self.property_name}'"
+            
+            if self.not_found_pages:
+                pages_str = "', '".join(self.not_found_pages)
+                base += f"\nWarning: Could not find pages: '{pages_str}'"
+                
+            return base
+        
+        if not self.found_pages and self.not_found_pages:
+            pages_str = "', '".join(self.not_found_pages)
+            return f"Error: {self.error}\nNone of the requested pages were found: '{pages_str}'"
+        
+        if self.found_pages and not self.page_ids_added:
+            return f"Error: {self.error}\nPages were found but could not be added to the relation."
+            
+        return f"Error: {self.error}"

notionary/util/{uuid_utils.py → page_id_utils.py}

@@ -22,3 +22,18 @@ def format_uuid(value: str) -> Optional[str]:
     if is_valid_uuid(value):
         return value
     return extract_uuid(value)
+
+
+def extract_and_validate_page_id(page_id: Optional[str], url: Optional[str]) -> str:
+    if not page_id and not url:
+        raise ValueError("Either page_id or url must be provided")
+
+    candidate = page_id or url
+    extracted_id = extract_uuid(candidate)
+    if not extracted_id:
+        raise ValueError(f"Could not extract a valid UUID from: {candidate}")
+
+    formatted = format_uuid(extracted_id)
+    if not is_valid_uuid(formatted):
+        raise ValueError(f"Invalid UUID format: {formatted}")
+    return formatted

{notionary-0.1.6.dist-info → notionary-0.1.7.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: notionary
-Version: 0.1.6
+Version: 0.1.7
 Summary: A toolkit to convert between Markdown and Notion blocks
 Home-page: https://github.com/mathisarends/notionary
 Author: Mathis Arends