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

notionary/__init__.py

@@ -7,9 +7,9 @@ from .database.database_discovery import DatabaseDiscovery
 from .page.notion_page import NotionPage
 from .page.notion_page_factory import NotionPageFactory
 
-from .elements.registry.block_element_registry import BlockElementRegistry
-from .elements.registry.block_element_registry_builder import (
-    BlockElementRegistryBuilder,
+from .elements.registry.block_registry import BlockRegistry
+from .elements.registry.block_registry_builder import (
+    BlockRegistryBuilder,
 )
 
 __all__ = [
@@ -19,6 +19,6 @@ __all__ = [
     "DatabaseDiscovery",
     "NotionPage",
     "NotionPageFactory",
-    "BlockElementRegistry",
-    "BlockElementRegistryBuilder",
+    "BlockRegistry",
+    "BlockRegistryBuilder",
 ]

notionary/database/notion_database.py

@@ -1,7 +1,10 @@
+from __future__ import annotations
+import json
 from typing import Any, AsyncGenerator, Dict, List, Optional
 
 from notionary.notion_client import NotionClient
 from notionary.page.notion_page import NotionPage
+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 format_uuid
 
@@ -13,6 +16,7 @@ class NotionDatabase(LoggingMixin):
     for further page operations.
     """
 
+    @warn_direct_constructor_usage
     def __init__(self, database_id: str, token: Optional[str] = None):
         """
         Initialize the minimal database manager.
@@ -21,9 +25,33 @@ class NotionDatabase(LoggingMixin):
             database_id: ID of the Notion database
             token: Optional Notion API token
         """
-        self.database_id = format_uuid(database_id) or database_id
+        self.database_id = database_id
         self._client = NotionClient(token=token)
 
+    @classmethod
+    async def from_database_id(
+        cls, database_id: str, token: Optional[str] = None
+    ) -> NotionDatabase:
+        """
+        Create a NotionDatabase from a database ID.
+        Delegates to NotionDatabaseFactory.
+        """
+        from notionary.database.notion_database_factory import NotionDatabaseFactory
+
+        return await NotionDatabaseFactory.from_database_id(database_id, token)
+
+    @classmethod
+    async def from_database_name(
+        cls, database_name: str, token: Optional[str] = None
+    ) -> NotionDatabase:
+        """
+        Create a NotionDatabase by finding a database with a matching name.
+        Delegates to NotionDatabaseFactory.
+        """
+        from notionary.database.notion_database_factory import NotionDatabaseFactory
+
+        return await NotionDatabaseFactory.from_database_name(database_name, token)
+
     async def create_blank_page(self) -> Optional[NotionPage]:
         """
         Create a new blank page in the database with minimal properties.
@@ -42,7 +70,9 @@ class NotionDatabase(LoggingMixin):
                     "Created blank page %s in database %s", page_id, self.database_id
                 )
 
-                return NotionPage(page_id=page_id)
+                return NotionPage.from_page_id(
+                    page_id=page_id, token=self._client.token
+                )
 
             self.logger.warning("Page creation failed: invalid response")
             return None
@@ -122,7 +152,6 @@ class NotionDatabase(LoggingMixin):
         start_cursor: Optional[str] = None
         has_more = True
 
-        # Prepare the query body
         body: Dict[str, Any] = {"page_size": page_size}
 
         if filter_conditions:
@@ -145,46 +174,13 @@ class NotionDatabase(LoggingMixin):
 
             for page in result["results"]:
                 page_id: str = page.get("id", "")
-                title = self._extract_page_title(page)
 
-                page_url = f"https://notion.so/{page_id.replace('-', '')}"
-
-                notion_page_manager = NotionPage(
-                    page_id=page_id, title=title, url=page_url
-                )
-                yield notion_page_manager
+                yield NotionPage.from_page_id(page_id=page_id, token=self._client.token)
 
-            # Update pagination parameters
             has_more = result.get("has_more", False)
             start_cursor = result.get("next_cursor") if has_more else None
 
-    def _extract_page_title(self, page: Dict[str, Any]) -> str:
-        """
-        Extracts the title from a Notion page object.
-
-        Args:
-            page: The Notion page object
-
-        Returns:
-            The extracted title as a string, or an empty string if no title found
-        """
-        properties = page.get("properties", {})
-        if not properties:
-            return ""
-
-        for prop_value in properties.values():
-            if prop_value.get("type") != "title":
-                continue
-
-            title_array = prop_value.get("title", [])
-            if not title_array:
-                continue
-
-            return title_array[0].get("plain_text", "")
-
-        return ""
-
-    async def delete_page(self, page_id: str) -> Dict[str, Any]:
+    async def archive_page(self, page_id: str) -> bool:
         """
         Delete (archive) a page.
 
@@ -192,51 +188,46 @@ class NotionDatabase(LoggingMixin):
             page_id: The ID of the page to delete
 
         Returns:
-            Dict with success status, message, and page_id when successful
+            bool: True if successful, False otherwise
         """
         try:
-            formatted_page_id = format_uuid(page_id) or page_id
+            formatted_page_id = format_uuid(page_id)
 
-            # Archive the page (Notion's way of deleting)
             data = {"archived": True}
 
-            result = await self._client.patch(f"pages/{formatted_page_id}", data)
+            result = await self._client.patch_page(formatted_page_id, data)
+
             if not result:
                 self.logger.error("Error deleting page %s", formatted_page_id)
-                return {
-                    "success": False,
-                    "message": f"Failed to delete page {formatted_page_id}",
-                }
+                return False
 
             self.logger.info(
                 "Page %s successfully deleted (archived)", formatted_page_id
             )
-            return {"success": True, "page_id": formatted_page_id}
+            return True
 
         except Exception as e:
-            self.logger.error("Error in delete_page: %s", str(e))
-            return {"success": False, "message": f"Error: {str(e)}"}
+            self.logger.error("Error in archive_page: %s", str(e))
+            return False
 
     async def get_last_edited_time(self) -> Optional[str]:
         """
         Retrieve the last edited time of the database.
 
         Returns:
-            ISO 8601 timestamp string of the last database edit, or None if request fails
+            ISO 8601 timestamp string of the last database edit, or None if request fails.
         """
         try:
-            response = await self._client.get(f"databases/{self.database_id}")
-
-            if response and "last_edited_time" in response:
-                return response["last_edited_time"]
+            db = await self._client.get_database(self.database_id)
 
-            self.logger.warning(
-                "Could not retrieve last_edited_time for database %s", self.database_id
-            )
-            return None
+            return db.last_edited_time
 
         except Exception as e:
-            self.logger.error("Error fetching last_edited_time: %s", str(e))
+            self.logger.error(
+                "Error fetching last_edited_time for database %s: %s",
+                self.database_id,
+                str(e),
+            )
             return None
 
     async def close(self) -> None:

notionary/database/notion_database_factory.py

@@ -21,11 +21,6 @@ class NotionDatabaseFactory(LoggingMixin):
     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
@@ -40,14 +35,12 @@ class NotionDatabaseFactory(LoggingMixin):
         Returns:
             An initialized NotionDatabaseManager instance
         """
-        logger = cls.class_logger()
-
         try:
             formatted_id = format_uuid(database_id) or database_id
 
             manager = NotionDatabase(formatted_id, token)
 
-            logger.info(
+            cls.logger.info(
                 "Successfully created database manager for ID: %s", formatted_id
             )
             return manager
@@ -58,7 +51,7 @@ class NotionDatabaseFactory(LoggingMixin):
             raise
         except Exception as e:
             error_msg = f"Error connecting to database {database_id}: {str(e)}"
-            logger.error(error_msg)
+            cls.logger.error(error_msg)
             raise DatabaseConnectionError(error_msg) from e
 
     @classmethod
@@ -76,13 +69,12 @@ class NotionDatabaseFactory(LoggingMixin):
         Returns:
             An initialized NotionDatabaseManager instance
         """
-        logger = cls.class_logger()
-        logger.debug("Searching for database with name: %s", database_name)
+        cls.logger.debug("Searching for database with name: %s", database_name)
 
         client = NotionClient(token=token)
 
         try:
-            logger.debug("Using search endpoint to find databases")
+            cls.logger.debug("Using search endpoint to find databases")
 
             search_payload = {
                 "filter": {"property": "object", "value": "database"},
@@ -93,17 +85,19 @@ class NotionDatabaseFactory(LoggingMixin):
 
             if not response or "results" not in response:
                 error_msg = "Failed to fetch databases using search endpoint"
-                logger.error(error_msg)
+                cls.logger.error(error_msg)
                 raise DatabaseConnectionError(error_msg)
 
             databases = response.get("results", [])
 
             if not databases:
                 error_msg = "No databases found"
-                logger.warning(error_msg)
+                cls.logger.warning(error_msg)
                 raise DatabaseNotFoundException(database_name, error_msg)
 
-            logger.debug("Found %d databases, searching for best match", len(databases))
+            cls.logger.debug(
+                "Found %d databases, searching for best match", len(databases)
+            )
 
             best_match = None
             best_score = 0
@@ -121,19 +115,19 @@ class NotionDatabaseFactory(LoggingMixin):
 
             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)
+                cls.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)
+                cls.logger.error(error_msg)
                 raise DatabaseParsingError(error_msg)
 
             matched_name = cls._extract_title_from_database(best_match)
 
-            logger.info(
+            cls.logger.info(
                 "Found matching database: '%s' (ID: %s) with score: %.2f",
                 matched_name,
                 database_id,
@@ -142,7 +136,9 @@ class NotionDatabaseFactory(LoggingMixin):
 
             manager = NotionDatabase(database_id, token)
 
-            logger.info("Successfully created database manager for '%s'", matched_name)
+            cls.logger.info(
+                "Successfully created database manager for '%s'", matched_name
+            )
             await client.close()
             return manager
 
@@ -151,7 +147,7 @@ class NotionDatabaseFactory(LoggingMixin):
             raise
         except Exception as e:
             error_msg = f"Error finding database by name: {str(e)}"
-            logger.error(error_msg)
+            cls.logger.error(error_msg)
             await client.close()
             raise DatabaseConnectionError(error_msg) from e
 

notionary/elements/audio_element.py

@@ -1,7 +1,7 @@
 import re
 from typing import Dict, Any, Optional, List
 from notionary.elements.notion_block_element import NotionBlockElement
-from notionary.elements.prompts.element_prompt_content import (
+from notionary.prompting.element_prompt_content import (
     ElementPromptBuilder,
     ElementPromptContent,
 )

notionary/elements/bookmark_element.py

@@ -2,7 +2,7 @@ import re
 from typing import Dict, Any, Optional, List, Tuple
 
 from notionary.elements.notion_block_element import NotionBlockElement
-from notionary.elements.prompts.element_prompt_content import (
+from notionary.prompting.element_prompt_content import (
     ElementPromptBuilder,
     ElementPromptContent,
 )

notionary/elements/bulleted_list_element.py

@@ -1,7 +1,7 @@
 import re
 from typing import Dict, Any, Optional
 from notionary.elements.notion_block_element import NotionBlockElement
-from notionary.elements.prompts.element_prompt_content import (
+from notionary.prompting.element_prompt_content import (
     ElementPromptBuilder,
     ElementPromptContent,
 )
@@ -65,12 +65,6 @@ class BulletedListElement(NotionBlockElement):
                 "Use for lists where order doesn't matter, such as features, options, or items without hierarchy."
             )
             .with_syntax("- Item text")
-            .with_examples(
-                [
-                    "- First item\n- Second item\n- Third item",
-                    "* Apple\n* Banana\n* Cherry",
-                    "+ Task A\n+ Task B",
-                ]
-            )
+            .with_standard_markdown()
             .build()
         )

notionary/elements/callout_element.py

@@ -1,7 +1,7 @@
 import re
 from typing import Dict, Any, Optional
 
-from notionary.elements.prompts.element_prompt_content import (
+from notionary.prompting.element_prompt_content import (
     ElementPromptBuilder,
     ElementPromptContent,
 )

notionary/elements/code_block_element.py

@@ -1,7 +1,7 @@
 import re
 from typing import Dict, Any, Optional, List, Tuple
 from notionary.elements.notion_block_element import NotionBlockElement
-from notionary.elements.prompts.element_prompt_content import (
+from notionary.prompting.element_prompt_content import (
     ElementPromptBuilder,
     ElementPromptContent,
 )

notionary/elements/divider_element.py

@@ -2,7 +2,7 @@ import re
 from typing import Dict, Any, Optional
 
 from notionary.elements.notion_block_element import NotionBlockElement
-from notionary.elements.prompts.element_prompt_content import (
+from notionary.prompting.element_prompt_content import (
     ElementPromptBuilder,
     ElementPromptContent,
 )

notionary/elements/embed_element.py

@@ -1,7 +1,7 @@
 import re
 from typing import Dict, Any, Optional, List
 from notionary.elements.notion_block_element import NotionBlockElement
-from notionary.elements.prompts.element_prompt_content import (
+from notionary.prompting.element_prompt_content import (
     ElementPromptBuilder,
     ElementPromptContent,
 )

notionary/elements/heading_element.py

@@ -2,7 +2,7 @@ import re
 from typing import Dict, Any, Optional
 
 from notionary.elements.notion_block_element import NotionBlockElement
-from notionary.elements.prompts.element_prompt_content import (
+from notionary.prompting.element_prompt_content import (
     ElementPromptBuilder,
     ElementPromptContent,
 )
@@ -86,12 +86,6 @@ class HeadingElement(NotionBlockElement):
                 "Use to group content into sections and define a visual hierarchy."
             )
             .with_syntax("## Your Heading Text")
-            .with_examples(
-                [
-                    "# Main Title",
-                    "## Section Title",
-                    "### Subsection Title",
-                ]
-            )
+            .with_standard_markdown()
             .build()
         )

notionary/elements/image_element.py

@@ -1,7 +1,7 @@
 import re
 from typing import Dict, Any, Optional, List
 from notionary.elements.notion_block_element import NotionBlockElement
-from notionary.elements.prompts.element_prompt_content import (
+from notionary.prompting.element_prompt_content import (
     ElementPromptBuilder,
     ElementPromptContent,
 )

notionary/elements/mention_element.py

@@ -3,7 +3,7 @@ from typing import Dict, Any, Optional, List
 from typing_extensions import override
 
 from notionary.elements.notion_block_element import NotionBlockElement
-from notionary.elements.prompts.element_prompt_content import (
+from notionary.prompting.element_prompt_content import (
     ElementPromptBuilder,
     ElementPromptContent,
 )

notionary/elements/notion_block_element.py

@@ -1,7 +1,7 @@
 from typing import Dict, Any, Optional
 from abc import ABC
 
-from notionary.elements.prompts.element_prompt_content import ElementPromptContent
+from notionary.prompting.element_prompt_content import ElementPromptContent
 
 
 class NotionBlockElement(ABC):

notionary/elements/numbered_list_element.py

@@ -1,7 +1,7 @@
 import re
 from typing import Dict, Any, Optional
 from notionary.elements.notion_block_element import NotionBlockElement
-from notionary.elements.prompts.element_prompt_content import (
+from notionary.prompting.element_prompt_content import (
     ElementPromptBuilder,
     ElementPromptContent,
 )
@@ -67,11 +67,6 @@ class NumberedListElement(NotionBlockElement):
                 "Use for lists where order matters, such as steps, rankings, or sequential items."
             )
             .with_syntax("1. Item text")
-            .with_examples(
-                [
-                    "1. First step\n2. Second step\n3. Third step",
-                    "1. Gather materials\n2. Assemble parts\n3. Test the result",
-                ]
-            )
+            .with_standard_markdown()
             .build()
         )

notionary/elements/paragraph_element.py

@@ -1,7 +1,7 @@
 from typing import Dict, Any, Optional
 
 from notionary.elements.notion_block_element import NotionBlockElement
-from notionary.elements.prompts.element_prompt_content import (
+from notionary.prompting.element_prompt_content import (
     ElementPromptBuilder,
     ElementPromptContent,
 )

notionary/elements/qoute_element.py

@@ -1,7 +1,7 @@
 import re
 from typing import Dict, Any, Optional, List, Tuple
 from notionary.elements.notion_block_element import NotionBlockElement
-from notionary.elements.prompts.element_prompt_content import (
+from notionary.prompting.element_prompt_content import (
     ElementPromptBuilder,
     ElementPromptContent,
 )

notionary/elements/registry/{block_element_registry.py → block_registry.py}

@@ -1,50 +1,94 @@
-from typing import Dict, Any, Optional, List, Type
+from __future__ import annotations
+from typing import Dict, Any, Optional, List, Set, Type
 
 from notionary.elements.notion_block_element import NotionBlockElement
-from notionary.elements.prompts.synthax_prompt_builder import (
-    MarkdownSyntaxPromptBuilder,
+from notionary.prompting.markdown_syntax_prompt_generator import (
+    MarkdownSyntaxPromptGenerator,
 )
 from notionary.elements.text_inline_formatter import TextInlineFormatter
 
+from notionary.elements.notion_block_element import NotionBlockElement
+
 
-class BlockElementRegistry:
+class BlockRegistry:
     """Registry of elements that can convert between Markdown and Notion."""
 
     def __init__(self, elements=None):
         """
         Initialize a new registry instance.
+
+        Args:
+            elements: Initial elements to register
+            builder: The builder that created this registry (optional)
         """
         self._elements: List[NotionBlockElement] = []
+        self._element_types: Set[Type[NotionBlockElement]] = set()
 
         if elements:
             for element in elements:
                 self.register(element)
 
-    def register(self, element_class: Type[NotionBlockElement]):
-        """Register an element class."""
+    def to_builder(self):
+        """
+        Convert this registry to a builder for modifications.
+        Imports only when needed to avoid circular imports.
+        """
+        from notionary.elements.registry.block_registry_builder import (
+            BlockRegistryBuilder,
+        )
+
+        builder = BlockRegistryBuilder()
+        for element in self._elements:
+            builder.add_element(element)
+        return builder
+
+    @property
+    def builder(self):
+        """
+        Returns a new builder pre-configured with the current registry elements.
+        Uses lazy import to avoid circular dependencies.
+        """
+        return self.to_builder()
+
+    def register(self, element_class: Type[NotionBlockElement]) -> bool:
+        """
+        Register an element class.
+
+        Args:
+            element_class: The element class to register
+
+        Returns:
+            bool: True if element was added, False if it already existed
+        """
+        if element_class in self._element_types:
+            return False
+
         self._elements.append(element_class)
-        return self
+        self._element_types.add(element_class)
+        return True
 
     def deregister(self, element_class: Type[NotionBlockElement]) -> bool:
         """
         Deregister an element class.
         """
-        if element_class in self._elements:
+        if element_class in self._element_types:
             self._elements.remove(element_class)
+            self._element_types.remove(element_class)
             return True
         return False
 
     def contains(self, element_class: Type[NotionBlockElement]) -> bool:
         """
-        Check if the registry contains the specified element class.
+        Prüft, ob ein bestimmtes Element im Registry enthalten ist.
+
+        Args:
+            element_class: Die zu prüfende Element-Klasse
+
+        Returns:
+            bool: True, wenn das Element enthalten ist, sonst False
         """
         return element_class in self._elements
 
-    def clear(self):
-        """Clear the registry completely."""
-        self._elements.clear()
-        return self
-
     def find_markdown_handler(self, text: str) -> Optional[Type[NotionBlockElement]]:
         """Find an element that can handle the given markdown text."""
         for element in self._elements:
@@ -52,15 +96,6 @@ class BlockElementRegistry:
                 return element
         return None
 
-    def find_notion_handler(
-        self, block: Dict[str, Any]
-    ) -> Optional[Type[NotionBlockElement]]:
-        """Find an element that can handle the given Notion block."""
-        for element in self._elements:
-            if element.match_notion(block):
-                return element
-        return None
-
     def markdown_to_notion(self, text: str) -> Optional[Dict[str, Any]]:
         """Convert markdown to Notion block using registered elements."""
         handler = self.find_markdown_handler(text)
@@ -70,7 +105,7 @@ class BlockElementRegistry:
 
     def notion_to_markdown(self, block: Dict[str, Any]) -> Optional[str]:
         """Convert Notion block to markdown using registered elements."""
-        handler = self.find_notion_handler(block)
+        handler = self._find_notion_handler(block)
         if handler:
             return handler.notion_to_markdown(block)
         return None
@@ -83,7 +118,7 @@ class BlockElementRegistry:
         """Get all registered elements."""
         return self._elements.copy()
 
-    def generate_llm_prompt(self) -> str:
+    def get_notion_markdown_syntax_prompt(self) -> str:
         """
         Generates an LLM system prompt that describes the Markdown syntax of all registered elements.
         """
@@ -93,4 +128,13 @@ class BlockElementRegistry:
         if "TextInlineFormatter" not in formatter_names:
             element_classes = [TextInlineFormatter] + element_classes
 
-        return MarkdownSyntaxPromptBuilder.generate_system_prompt(element_classes)
+        return MarkdownSyntaxPromptGenerator.generate_system_prompt(element_classes)
+
+    def _find_notion_handler(
+        self, block: Dict[str, Any]
+    ) -> Optional[Type[NotionBlockElement]]:
+        """Find an element that can handle the given Notion block."""
+        for element in self._elements:
+            if element.match_notion(block):
+                return element
+        return None