notionary 0.1.29__py3-none-any.whl → 0.2.0__py3-none-any.whl

notionary/page/notion_page.py

@@ -1,11 +1,11 @@
+from __future__ import annotations
+from typing import Any, Dict, List, Optional
 import re
-from typing import Any, Dict, List, Optional, Union
 
-from notionary.elements.registry.block_element_registry import BlockElementRegistry
-from notionary.elements.registry.block_element_registry_builder import (
-    BlockElementRegistryBuilder,
-)
+from notionary.elements.registry.block_registry import BlockRegistry
+from notionary.elements.registry.block_registry_builder import BlockRegistryBuilder
 from notionary.notion_client import NotionClient
+from notionary.page.content.page_content_retriever import PageContentRetriever
 from notionary.page.metadata.metadata_editor import MetadataEditor
 from notionary.page.metadata.notion_icon_manager import NotionPageIconManager
 from notionary.page.metadata.notion_page_cover_manager import (
@@ -15,10 +15,12 @@ from notionary.page.properites.database_property_service import (
     DatabasePropertyService,
 )
 from notionary.page.relations.notion_page_relation_manager import (
-    NotionRelationManager,
+    NotionPageRelationManager,
 )
-from notionary.page.content.page_content_manager import PageContentManager
+from notionary.page.content.page_content_writer import PageContentWriter
 from notionary.page.properites.page_property_manager import PagePropertyManager
+from notionary.page.relations.notion_page_title_resolver import NotionPageTitleResolver
+from notionary.util.warn_direct_constructor_usage import warn_direct_constructor_usage
 from notionary.util.logging_mixin import LoggingMixin
 from notionary.util.page_id_utils import extract_and_validate_page_id
 from notionary.page.relations.page_database_relation import PageDatabaseRelation
@@ -26,9 +28,10 @@ from notionary.page.relations.page_database_relation import PageDatabaseRelation
 
 class NotionPage(LoggingMixin):
     """
-    High-Level Facade for managing content and metadata of a Notion page.
+    Managing content and metadata of a Notion page.
     """
 
+    @warn_direct_constructor_usage
     def __init__(
         self,
         page_id: Optional[str] = None,
@@ -44,15 +47,20 @@ class NotionPage(LoggingMixin):
         self._title_loaded = title is not None
         self._url_loaded = url is not None
 
-        self._block_element_registry = (
-            BlockElementRegistryBuilder.create_full_registry()
+        self._block_element_registry = BlockRegistryBuilder.create_full_registry()
+
+        self._page_content_writer = PageContentWriter(
+            page_id=self._page_id,
+            client=self._client,
+            block_registry=self._block_element_registry,
         )
 
-        self._page_content_manager = PageContentManager(
+        self._page_content_retriever = PageContentRetriever(
             page_id=self._page_id,
             client=self._client,
             block_registry=self._block_element_registry,
         )
+
         self._metadata = MetadataEditor(self._page_id, self._client)
         self._page_cover_manager = NotionPageCoverManager(
             page_id=self._page_id, client=self._client
@@ -66,7 +74,7 @@ class NotionPage(LoggingMixin):
         )
         self._db_property_service = None
 
-        self._relation_manager = NotionRelationManager(
+        self._relation_manager = NotionPageRelationManager(
             page_id=self._page_id, client=self._client
         )
 
@@ -74,18 +82,68 @@ class NotionPage(LoggingMixin):
             self._page_id, self._client, self._metadata, self._db_relation
         )
 
+    @classmethod
+    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
+        """
+        from notionary.page.notion_page_factory import NotionPageFactory
+
+        cls.logger.info("Creating page from ID: %s", page_id)
+        return NotionPageFactory().from_page_id(page_id, token)
+
+    @classmethod
+    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
+        """
+        from notionary.page.notion_page_factory import NotionPageFactory
+
+        cls.logger.info("Creating page from URL: %s", url)
+        return NotionPageFactory().from_url(url, token)
+
+    @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.
+
+        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
+        """
+        from notionary.page.notion_page_factory import NotionPageFactory
+
+        return await NotionPageFactory().from_page_name(page_name, token)
+
     @property
     def id(self) -> str:
         """
         Get the ID of the page.
-
-        Returns:
-            str: The page ID.
         """
         return self._page_id
 
     @property
-    def block_registry(self) -> BlockElementRegistry:
+    def block_registry(self) -> BlockRegistry:
         """
         Get the block element registry associated with this page.
 
@@ -94,8 +152,18 @@ class NotionPage(LoggingMixin):
         """
         return self._block_element_registry
 
+    @property
+    def block_registry_builder(self) -> BlockRegistryBuilder:
+        """
+        Get the block element registry builder associated with this page.
+
+        Returns:
+            BlockElementRegistryBuilder: The builder for block elements.
+        """
+        return self._block_element_registry.builder
+
     @block_registry.setter
-    def block_registry(self, block_registry: BlockElementRegistry) -> None:
+    def block_registry(self, block_registry: BlockRegistry) -> None:
         """
         Set the block element registry for the page content manager.
 
@@ -103,10 +171,22 @@ class NotionPage(LoggingMixin):
             block_registry: The registry of block elements to use.
         """
         self._block_element_registry = block_registry
-        self._page_content_manager = PageContentManager(
+        self._page_content_writer = PageContentRetriever(
+            page_id=self._page_id, client=self._client, block_registry=block_registry
+        )
+        self._page_content_retriever = PageContentRetriever(
             page_id=self._page_id, client=self._client, block_registry=block_registry
         )
 
+    def get_notion_markdown_system_prompt(self) -> str:
+        """
+        Get the formatting prompt for the page content manager.
+
+        Returns:
+            str: The formatting prompt.
+        """
+        return self._block_element_registry.get_notion_markdown_syntax_prompt()
+
     async def get_title(self) -> str:
         """
         Get the title of the page, loading it if necessary.
@@ -115,9 +195,25 @@ class NotionPage(LoggingMixin):
             str: The page title.
         """
         if not self._title_loaded:
-            await self._load_page_title()
+            self._title = await self._fetch_page_title()
         return self._title
 
+    async def set_title(self, title: str) -> Optional[Dict[str, Any]]:
+        """
+        Set the title of the page.
+
+        Args:
+            title: The new title.
+
+        Returns:
+            Optional[Dict[str, Any]]: Response data from the API if successful, None otherwise.
+        """
+        result = await self._metadata.set_title(title)
+        if result:
+            self._title = title
+            self._title_loaded = True
+        return result
+
     async def get_url(self) -> str:
         """
         Get the URL of the page, constructing it if necessary.
@@ -126,11 +222,11 @@ class NotionPage(LoggingMixin):
             str: The page URL.
         """
         if not self._url_loaded:
-            self._url = await self._build_notion_url()
+            self._url = await self._generate_url_from_title()
             self._url_loaded = True
         return self._url
 
-    async def append_markdown(self, markdown: str, append_divider = False) -> str:
+    async def append_markdown(self, markdown: str, append_divider=False) -> bool:
         """
         Append markdown content to the page.
 
@@ -140,18 +236,20 @@ class NotionPage(LoggingMixin):
         Returns:
             str: Status or confirmation message.
         """
-        return await self._page_content_manager.append_markdown(markdown_text=markdown, append_divider=append_divider)
+        return await self._page_content_writer.append_markdown(
+            markdown_text=markdown, append_divider=append_divider
+        )
 
-    async def clear(self) -> str:
+    async def clear_page_content(self) -> bool:
         """
         Clear all content from the page.
 
         Returns:
             str: Status or confirmation message.
         """
-        return await self._page_content_manager.clear()
+        return await self._page_content_writer.clear_page_content()
 
-    async def replace_content(self, markdown: str) -> str:
+    async def replace_content(self, markdown: str) -> bool:
         """
         Replace the entire page content with new markdown content.
 
@@ -161,59 +259,58 @@ class NotionPage(LoggingMixin):
         Returns:
             str: Status or confirmation message.
         """
-        await self._page_content_manager.clear()
-        return await self._page_content_manager.append_markdown(markdown)
+        clear_result = await self._page_content_writer.clear_page_content()
+        if not clear_result:
+            self.logger.error("Failed to clear page content before replacement")
+            return False
+
+        return await self._page_content_writer.append_markdown(
+            markdown_text=markdown, append_divider=False
+        )
 
-    async def get_text(self) -> str:
+    async def get_text_content(self) -> str:
         """
         Get the text content of the page.
 
         Returns:
             str: The text content of the page.
         """
-        return await self._page_content_manager.get_text()
+        return await self._page_content_retriever.get_page_content()
 
-    async def set_title(self, title: str) -> Optional[Dict[str, Any]]:
+    async def get_icon(self) -> str:
         """
-        Set the title of the page.
-
-        Args:
-            title: The new title.
+        Retrieve the page icon - either emoji or external URL.
 
         Returns:
-            Optional[Dict[str, Any]]: Response data from the API if successful, None otherwise.
+            Optional[str]: The icon emoji or URL, or None if no icon is set.
         """
-        result = await self._metadata.set_title(title)
-        if result:
-            self._title = title
-            self._title_loaded = True
-        return result
+        return await self._page_icon_manager.get_icon()
 
-    async def set_page_icon(
-        self, emoji: Optional[str] = None, external_url: Optional[str] = None
-    ) -> Optional[Dict[str, Any]]:
+    async def set_emoji_icon(self, emoji: str) -> Optional[str]:
         """
-        Set the icon for the page. Provide either emoji or external_url.
+        Sets the page icon to an emoji.
 
         Args:
-            emoji: Optional emoji to use as icon.
-            external_url: Optional URL to an external image to use as icon.
+            emoji (str): The emoji character to set as the icon.
 
         Returns:
             Optional[Dict[str, Any]]: Response data from the API if successful, None otherwise.
         """
-        return await self._page_icon_manager.set_icon(emoji, external_url)
+        return await self._page_icon_manager.set_emoji_icon(emoji=emoji)
 
-    async def get_icon(self) -> str:
+    async def set_external_icon(self, url: str) -> Optional[str]:
         """
-        Retrieve the page icon - either emoji or external URL.
+        Sets the page icon to an external image.
+
+        Args:
+            url (str): The URL of the external image to set as the icon.
 
         Returns:
-            Optional[str]: The icon emoji or URL, or None if no icon is set.
+            Optional[Dict[str, Any]]: Response data from the API if successful, None otherwise.
         """
-        return await self._page_icon_manager.get_icon()
+        return await self._page_icon_manager.set_external_icon(external_icon_url=url)
 
-    async def get_cover_url(self) -> str:
+    async def get_cover_url(self) -> Optional[str]:
         """
         Get the URL of the page cover image.
 
@@ -222,7 +319,7 @@ class NotionPage(LoggingMixin):
         """
         return await self._page_cover_manager.get_cover_url()
 
-    async def set_page_cover(self, external_url: str) -> Optional[Dict[str, Any]]:
+    async def set_cover(self, external_url: str) -> Optional[str]:
         """
         Set the cover image for the page using an external URL.
 
@@ -243,16 +340,7 @@ class NotionPage(LoggingMixin):
         """
         return await self._page_cover_manager.set_random_gradient_cover()
 
-    async def get_properties(self) -> Dict[str, Any]:
-        """
-        Retrieve all properties of the page.
-
-        Returns:
-            Dict[str, Any]: Dictionary of property names and their values.
-        """
-        return await self._property_manager.get_properties()
-
-    async def get_property_value(self, property_name: str) -> Any:
+    async def get_property_value_by_name(self, property_name: str) -> Any:
         """
         Get the value of a specific property.
 
@@ -262,126 +350,86 @@ class NotionPage(LoggingMixin):
         Returns:
             Any: The value of the property.
         """
-        return await self._property_manager.get_property_value(
-            property_name, self._relation_manager.get_relation_values
-        )
+        properties = await self._property_manager._get_properties()
 
-    async def set_property_by_name(
-        self, property_name: str, value: Any
-    ) -> Optional[Dict[str, Any]]:
-        """
-        Set the value of a specific property by its name.
-
-        Args:
-            property_name: The name of the property.
-            value: The new value to set.
-
-        Returns:
-            Optional[Dict[str, Any]]: Response data from the API if successful, None otherwise.
-        """
-        return await self._property_manager.set_property_by_name(
-            property_name=property_name,
-            value=value,
-        )
-
-    async def is_database_page(self) -> bool:
-        """
-        Check if this page belongs to a database.
+        if property_name not in properties:
+            return None
 
-        Returns:
-            bool: True if the page belongs to a database, False otherwise.
-        """
-        return await self._db_relation.is_database_page()
+        prop_data = properties[property_name]
+        prop_type = prop_data.get("type")
 
-    async def get_parent_database_id(self) -> Optional[str]:
-        """
-        Get the ID of the database this page belongs to, if any.
+        if prop_type == "relation":
+            return await self._relation_manager.get_relation_values(property_name)
 
-        Returns:
-            Optional[str]: The database ID or None if the page doesn't belong to a database.
-        """
-        return await self._db_relation.get_parent_database_id()
+        return await self._property_manager.get_property_value(property_name)
 
-    async def get_available_options_for_property(self, property_name: str) -> List[str]:
+    async def get_options_for_property(
+        self, property_name: str, limit: int = 100
+    ) -> List[str]:
         """
-        Get the available option names for a property (select, multi_select, status).
+        Get the available options for a property (select, multi_select, status, relation).
 
         Args:
             property_name: The name of the property.
+            limit: Maximum number of options to return (only affects relation properties).
 
         Returns:
-            List[str]: List of available option names.
+            List[str]: List of available option names or page titles.
         """
-        db_service = await self._get_db_property_service()
-        if db_service:
-            return await db_service.get_option_names(property_name)
-        return []
+        property_type = await self._get_property_type(property_name)
 
-    async def get_property_type(self, property_name: str) -> Optional[str]:
-        """
-        Get the type of a specific property.
+        if property_type is None:
+            return []
 
-        Args:
-            property_name: The name of the property.
+        if property_type == "relation":
+            return await self._relation_manager.get_relation_options(
+                property_name, limit
+            )
 
-        Returns:
-            Optional[str]: The type of the property or None if not found.
-        """
         db_service = await self._get_db_property_service()
         if db_service:
-            return await db_service.get_property_type(property_name)
-        return None
-
-    async def get_database_metadata(
-        self, include_types: Optional[List[str]] = None
-    ) -> Dict[str, Any]:
-        """
-        Get complete metadata about the database this page belongs to.
-
-        Args:
-            include_types: Optional list of property types to include. If None, all properties are included.
+            return await db_service.get_option_names(property_name)
 
-        Returns:
-            Dict[str, Any]: Database metadata or empty dict if not a database page.
-        """
-        db_service = await self._get_db_property_service()
-        if db_service:
-            return await db_service.get_database_metadata(include_types)
-        return {"properties": {}}
+        return []
 
-    async def get_relation_options(
-        self, property_name: str, limit: int = 100
-    ) -> List[Dict[str, Any]]:
+    async def set_property_value_by_name(
+        self, property_name: str, value: Any
+    ) -> Optional[Dict[str, Any]]:
         """
-        Return available options for a relation property.
+        Set the value of a specific property by its name.
 
         Args:
-            property_name: The name of the relation property.
-            limit: Maximum number of options to return.
+            property_name: The name of the property.
+            value: The new value to set.
 
         Returns:
-            List[Dict[str, Any]]: List of available relation options.
+            Optional[Dict[str, Any]]: Response data from the API if successful, None otherwise.
         """
-        return await self._relation_manager.get_relation_options(property_name, limit)
+        return await self._property_manager.set_property_by_name(
+            property_name=property_name,
+            value=value,
+        )
 
-    async def add_relations_by_name(
-        self, relation_property_name: str, page_titles: Union[str, List[str]]
-    ) -> Optional[Dict[str, Any]]:
+    async def set_relation_property_values_by_name(
+        self, relation_property_name: str, page_titles: List[str]
+    ) -> List[str]:
         """
         Add one or more relations to a relation property.
 
         Args:
             relation_property_name: The name of the relation property.
-            page_titles: One or more page titles to relate to.
+            page_titles: A list of page titles to relate to.
 
         Returns:
             Optional[Dict[str, Any]]: Response data from the API if successful, None otherwise.
         """
-        return await self._relation_manager.add_relation_by_name(
+        return await self._relation_manager.set_relation_values_by_page_titles(
             property_name=relation_property_name, page_titles=page_titles
         )
 
-    async def get_relation_values(self, property_name: str) -> List[str]:
+    async def get_relation_property_values_by_name(
+        self, property_name: str
+    ) -> List[str]:
         """
         Return the current relation values for a property.
 
@@ -393,25 +441,7 @@ class NotionPage(LoggingMixin):
         """
         return await self._relation_manager.get_relation_values(property_name)
 
-    async def get_relation_property_ids(self) -> List[str]:
-        """
-        Return a list of all relation property names.
-
-        Returns:
-            List[str]: List of relation property names.
-        """
-        return await self._relation_manager.get_relation_property_ids()
-
-    async def get_all_relations(self) -> Dict[str, List[str]]:
-        """
-        Return all relation properties and their values.
-
-        Returns:
-            Dict[str, List[str]]: Dictionary mapping relation property names to their values.
-        """
-        return await self._relation_manager.get_all_relations()
-
-    async def get_last_edited_time(self) -> str:
+    async def get_last_edit_time(self) -> str:
         """
         Get the timestamp when the page was last edited.
 
@@ -419,78 +449,35 @@ class NotionPage(LoggingMixin):
             str: ISO 8601 formatted timestamp string of when the page was last edited.
         """
         try:
-            page_data = await self._client.get_page(self._page_id)
-            if "last_edited_time" in page_data:
-                return page_data["last_edited_time"]
-
-            self.logger.warning("last_edited_time not found in page data")
-            return ""
+            page_response = await self._client.get_page(self._page_id)
+            return (
+                page_response.last_edited_time if page_response.last_edited_by else ""
+            )
 
         except Exception as e:
             self.logger.error("Error retrieving last edited time: %s", str(e))
             return ""
 
-    async def _load_page_title(self) -> str:
+    async def _fetch_page_title(self) -> str:
         """
         Load the page title from Notion API if not already loaded.
 
         Returns:
             str: The page title.
         """
-        if self._title is not None:
-            return self._title
-
-        self.logger.debug("Lazy loading page title for page: %s", self._page_id)
-        try:
-            # Retrieve page data
-            page_data = await self._client.get(f"pages/{self._page_id}")
-            self._title = self._extract_title_from_page_data(page_data)
-        except Exception as e:
-            self.logger.error("Error loading page title: %s", str(e))
-            self._title = "Untitled"
-
-        self._title_loaded = True
-        self.logger.debug("Loaded page title: %s", self._title)
-        return self._title
-
-    def _extract_title_from_page_data(self, page_data: Dict[str, Any]) -> str:
-        """
-        Extract title from page data.
-
-        Args:
-            page_data: The page data from Notion API
-
-        Returns:
-            str: The extracted title or "Untitled" if not found
-        """
-        if "properties" not in page_data:
-            return "Untitled"
-
-        for prop_value in page_data["properties"].values():
-            if prop_value.get("type") != "title":
-                continue
-
-            title_array = prop_value.get("title", [])
-            if not title_array:
-                continue
-
-            text_parts = []
-            for text_obj in title_array:
-                if "plain_text" in text_obj:
-                    text_parts.append(text_obj["plain_text"])
-
-            return "".join(text_parts) or "Untitled"
-
-        return "Untitled"
+        notion_page_title_resolver = NotionPageTitleResolver(self._client)
+        return await notion_page_title_resolver.get_title_by_page_id(
+            page_id=self._page_id
+        )
 
-    async def _build_notion_url(self) -> str:
+    async def _generate_url_from_title(self) -> str:
         """
         Build a Notion URL from the page ID, including the title if available.
 
         Returns:
             str: The Notion URL for the page.
         """
-        title = await self._load_page_title()
+        title = await self._fetch_page_title()
 
         url_title = ""
         if title and title != "Untitled":
@@ -520,3 +507,21 @@ class NotionPage(LoggingMixin):
         self._db_property_service = DatabasePropertyService(database_id, self._client)
         await self._db_property_service.load_schema()
         return self._db_property_service
+
+    async def _get_property_type(self, property_name: str) -> Optional[str]:
+        """
+        Get the type of a specific property.
+
+        Args:
+            property_name: The name of the property.
+
+        Returns:
+            Optional[str]: The type of the property, or None if not found.
+        """
+        properties = await self._property_manager._get_properties()
+
+        if property_name not in properties:
+            return None
+
+        prop_data = properties[property_name]
+        return prop_data.get("type")