notionary 0.2.13__py3-none-any.whl → 0.2.14__py3-none-any.whl

notionary/database/notion_database_provider.py

@@ -0,0 +1,230 @@
+from __future__ import annotations
+
+from typing import Dict, Optional, TYPE_CHECKING
+from notionary.database.client import NotionDatabaseClient
+from notionary.database.database_exceptions import DatabaseNotFoundException
+from notionary.models.notion_database_response import NotionDatabaseResponse
+from notionary.util import LoggingMixin, FuzzyMatcher, format_uuid
+from notionary.util.singleton_metaclass import SingletonMetaClass
+
+if TYPE_CHECKING:
+    from notionary import NotionDatabase
+
+
+class NotionDatabaseProvider(LoggingMixin, metaclass=SingletonMetaClass):
+    """
+    Provider class for creating and caching Notion database instances.
+
+    Prevents duplicate database creation when working with multiple pages from the same database.
+    Each Notion page references its parent database to determine selectable properties and options.
+    By caching database instances, this provider avoids excessive network requests when reading options,
+    significantly improving performance for repeated property lookups across many pages.
+    """
+
+    def __init__(self):
+        self._database_cache: Dict[str, NotionDatabase] = {}
+
+    async def get_database_by_id(
+        self, database_id: str, token: Optional[str] = None, force_refresh: bool = False
+    ) -> NotionDatabase:
+        """Get a NotionDatabase by ID with caching."""
+        cache_key = self._create_id_cache_key(database_id)
+
+        if self._should_use_cache(cache_key, force_refresh):
+            self.logger.debug(f"Using cached database for ID: {database_id}")
+            return self._database_cache[cache_key]
+
+        database = await self._create_from_database_id(database_id, token)
+        self._cache_database(database, token)
+        return database
+
+    async def get_database_by_name(
+        self,
+        database_name: str,
+        token: Optional[str] = None,
+        min_similarity: float = 0.6,
+        force_refresh: bool = False,
+    ) -> NotionDatabase:
+        """Get a NotionDatabase by name with caching."""
+        name_cache_key = self._create_name_cache_key(database_name, token)
+
+        if self._should_use_cache(name_cache_key, force_refresh):
+            return self._database_cache[name_cache_key]
+
+        database = await self._create_from_database_name(
+            database_name, token, min_similarity
+        )
+
+        id_cache_key = self._create_id_cache_key(database.database_id)
+        if not force_refresh and id_cache_key in self._database_cache:
+            self.logger.debug(
+                f"Found existing cached database by ID: {database.database_id}"
+            )
+            existing_database = self._database_cache[id_cache_key]
+
+            self._database_cache[name_cache_key] = existing_database
+            return existing_database
+
+        self._cache_database(database, token, database_name)
+        self.logger.debug(
+            f"Cached database: {database.title} (ID: {database.database_id})"
+        )
+
+        return database
+
+    def invalidate_database_cache(self, database_id: str) -> bool:
+        """
+        Simply invalidate (remove) cache entries for a database without reloading.
+
+        Args:
+            database_id: The database ID to invalidate
+
+        Returns:
+            True if cache entries were found and removed, False otherwise
+        """
+
+        id_cache_key = self._create_id_cache_key(database_id)
+        was_cached = id_cache_key in self._database_cache
+
+        if not was_cached:
+            self.logger.debug(f"No cache entry found for database ID: {database_id}")
+            return False
+
+        removed_database = self._database_cache.pop(id_cache_key)
+        self.logger.debug(f"Invalidated cached database: {removed_database.title}")
+
+        name_keys_to_remove = [
+            cache_key
+            for cache_key, cached_db in self._database_cache.items()
+            if (cache_key.startswith("name:") and cached_db.database_id == database_id)
+        ]
+
+        for name_key in name_keys_to_remove:
+            self._database_cache.pop(name_key)
+            self.logger.debug(f"Invalidated name-based cache: {name_key}")
+
+        return was_cached
+
+    async def _create_from_database_id(
+        self, database_id: str, token: Optional[str]
+    ) -> NotionDatabase:
+        """Create a NotionDatabase from database ID via API."""
+        formatted_id = format_uuid(database_id) or database_id
+
+        async with NotionDatabaseClient(token=token) as client:
+            db_response = await client.get_database(formatted_id)
+            return self._create_from_response(db_response, token)
+
+    async def _create_from_database_name(
+        self,
+        database_name: str,
+        token: Optional[str] = None,
+        min_similarity: float = 0.6,
+    ) -> NotionDatabase:
+        """Create a NotionDatabase by finding it via name with fuzzy matching."""
+        async with NotionDatabaseClient(token=token) as client:
+            search_result = await client.search_databases(database_name, limit=10)
+
+            if not search_result.results:
+                self.logger.warning("No databases found for name: %s", database_name)
+                raise DatabaseNotFoundException(database_name)
+
+            best_match = FuzzyMatcher.find_best_match(
+                query=database_name,
+                items=search_result.results,
+                text_extractor=lambda db: self._extract_title(db),
+                min_similarity=min_similarity,
+            )
+
+            if not best_match:
+                available_titles = [
+                    self._extract_title(db) for db in search_result.results[:5]
+                ]
+                self.logger.warning(
+                    "No sufficiently similar database found for '%s' (min: %.3f). Available: %s",
+                    database_name,
+                    min_similarity,
+                    available_titles,
+                )
+                raise DatabaseNotFoundException(database_name)
+
+            database_id = best_match.item.id
+            db_response = await client.get_database(database_id=database_id)
+            instance = self._create_from_response(db_response, token)
+
+            self.logger.info(
+                "Created database: '%s' (ID: %s, similarity: %.3f)",
+                instance.title,
+                database_id,
+                best_match.similarity,
+            )
+
+            return instance
+
+    def _should_use_cache(self, cache_key: str, force_refresh: bool) -> bool:
+        """Returns True if the cache should be used for the given cache_key."""
+        return not force_refresh and cache_key in self._database_cache
+
+    def _cache_database(
+        self,
+        database: NotionDatabase,
+        token: Optional[str],
+        original_name: Optional[str] = None,
+    ) -> None:
+        """Cache a database by both ID and name (if provided)."""
+        # Always cache by ID
+        id_cache_key = self._create_id_cache_key(database.database_id)
+        self._database_cache[id_cache_key] = database
+
+        if original_name:
+            name_cache_key = self._create_name_cache_key(original_name, token)
+            self._database_cache[name_cache_key] = database
+
+    def _create_id_cache_key(self, database_id: str) -> str:
+        """Create cache key for database ID."""
+        return f"id:{database_id}"
+
+    def _create_name_cache_key(self, database_name: str, token: Optional[str]) -> str:
+        """Create cache key for database name."""
+        token_suffix = f":{hash(token)}" if token else ":default"
+        return f"name:{database_name.lower().strip()}{token_suffix}"
+
+    def _create_from_response(
+        self, db_response: NotionDatabaseResponse, token: Optional[str]
+    ) -> NotionDatabase:
+        """Create NotionDatabase instance from API response."""
+        from notionary import NotionDatabase
+
+        title = self._extract_title(db_response)
+        emoji_icon = self._extract_emoji_icon(db_response)
+
+        instance = NotionDatabase(
+            database_id=db_response.id,
+            title=title,
+            url=db_response.url,
+            emoji_icon=emoji_icon,
+            properties=db_response.properties,
+            token=token,
+        )
+
+        self.logger.info(
+            "Created database manager: '%s' (ID: %s)", title, db_response.id
+        )
+
+        return instance
+
+    def _extract_title(self, db_response: NotionDatabaseResponse) -> str:
+        """Extract title from database response."""
+        if db_response.title and len(db_response.title) > 0:
+            return db_response.title[0].plain_text
+        return "Untitled Database"
+
+    def _extract_emoji_icon(self, db_response: NotionDatabaseResponse) -> Optional[str]:
+        """Extract emoji from database response."""
+        if not db_response.icon:
+            return None
+
+        if db_response.icon.type == "emoji":
+            return db_response.icon.emoji
+
+        return None

notionary/models/notion_database_response.py

@@ -1,10 +1,11 @@
 from pydantic import BaseModel
 from dataclasses import dataclass
-from typing import Optional, List, Dict, Any, Literal
+from typing import Optional, List, Dict, Any, Literal, Union
 
-from notionary.models.notion_page_response import Icon
+from notionary.models.notion_page_response import Cover, Icon
 
 
+# Reusing existing types from your codebase
 @dataclass
 class TextContent:
     content: str
@@ -27,11 +28,214 @@ class User:
 
 @dataclass
 class Parent:
-    type: Literal["page_id", "workspace", "block_id"]
+    type: Literal["page_id", "workspace", "block_id", "database_id"]
     page_id: Optional[str] = None
-    block_id: Optional[str] = None  # Added block_id field
+    block_id: Optional[str] = None
+    database_id: Optional[str] = None
 
 
+# Rich text types for Pydantic models
+class TextContentPydantic(BaseModel):
+    content: str
+    link: Optional[Dict[str, str]] = None
+
+
+class Annotations(BaseModel):
+    bold: bool
+    italic: bool
+    strikethrough: bool
+    underline: bool
+    code: bool
+    color: str
+
+
+class RichTextItemPydantic(BaseModel):
+    type: str  # 'text', 'mention', 'equation'
+    text: Optional[TextContentPydantic] = None
+    annotations: Annotations
+    plain_text: str
+    href: Optional[str] = None
+
+
+# Database property schema types (these are schema definitions, not values)
+class StatusOption(BaseModel):
+    id: str
+    name: str
+    color: str
+    description: Optional[str] = None
+
+
+class StatusGroup(BaseModel):
+    id: str
+    name: str
+    color: str
+    option_ids: List[str]
+
+
+class StatusPropertySchema(BaseModel):
+    options: List[StatusOption]
+    groups: List[StatusGroup]
+
+
+class DatabaseStatusProperty(BaseModel):
+    id: str
+    name: str
+    type: Literal["status"]
+    status: StatusPropertySchema
+
+
+class RelationPropertySchema(BaseModel):
+    database_id: str
+    type: str  # "single_property"
+    single_property: Dict[str, Any]
+
+
+class DatabaseRelationProperty(BaseModel):
+    id: str
+    name: str
+    type: Literal["relation"]
+    relation: RelationPropertySchema
+
+
+class DatabaseUrlProperty(BaseModel):
+    id: str
+    name: str
+    type: Literal["url"]
+    url: Dict[str, Any]  # Usually empty dict
+
+
+class DatabaseRichTextProperty(BaseModel):
+    id: str
+    name: str
+    type: Literal["rich_text"]
+    rich_text: Dict[str, Any]  # Usually empty dict
+
+
+class MultiSelectOption(BaseModel):
+    id: str
+    name: str
+    color: str
+    description: Optional[str] = None
+
+
+class MultiSelectPropertySchema(BaseModel):
+    options: List[MultiSelectOption]
+
+
+class DatabaseMultiSelectProperty(BaseModel):
+    id: str
+    name: str
+    type: Literal["multi_select"]
+    multi_select: MultiSelectPropertySchema
+
+
+class DatabaseTitleProperty(BaseModel):
+    id: str
+    name: str
+    type: Literal["title"]
+    title: Dict[str, Any]  # Usually empty dict
+
+
+# Generic database property for unknown types
+class GenericDatabaseProperty(BaseModel):
+    id: str
+    name: str
+    type: str
+
+    class Config:
+        extra = "allow"
+
+
+# Union of all database property types
+DatabaseProperty = Union[
+    DatabaseStatusProperty,
+    DatabaseRelationProperty,
+    DatabaseUrlProperty,
+    DatabaseRichTextProperty,
+    DatabaseMultiSelectProperty,
+    DatabaseTitleProperty,
+    GenericDatabaseProperty,
+]
+
+
+# Page property value types (these are actual values, not schemas)
+class StatusValue(BaseModel):
+    id: str
+    name: str
+    color: str
+
+
+class StatusProperty(BaseModel):
+    id: str
+    type: str  # 'status'
+    status: Optional[StatusValue] = None
+
+
+class RelationItem(BaseModel):
+    id: str
+
+
+class RelationProperty(BaseModel):
+    id: str
+    type: str  # 'relation'
+    relation: List[RelationItem]
+    has_more: bool
+
+
+class UrlProperty(BaseModel):
+    id: str
+    type: str  # 'url'
+    url: Optional[str] = None
+
+
+class RichTextProperty(BaseModel):
+    id: str
+    type: str  # 'rich_text'
+    rich_text: List[RichTextItemPydantic]
+
+
+class MultiSelectItem(BaseModel):
+    id: str
+    name: str
+    color: str
+
+
+class MultiSelectProperty(BaseModel):
+    id: str
+    type: str  # 'multi_select'
+    multi_select: List[MultiSelectItem]
+
+
+class TitleProperty(BaseModel):
+    id: str
+    type: str  # 'title'
+    title: List[RichTextItemPydantic]
+
+
+# Cover types
+class ExternalCover(BaseModel):
+    url: str
+
+
+class NotionCover(BaseModel):
+    type: str  # 'external', 'file'
+    external: Optional[ExternalCover] = None
+
+
+# Parent types for Pydantic
+class NotionParent(BaseModel):
+    type: str  # 'database_id', 'page_id', 'workspace'
+    database_id: Optional[str] = None
+    page_id: Optional[str] = None
+
+
+# User type for Pydantic
+class NotionUser(BaseModel):
+    object: str  # 'user'
+    id: str
+
+
+# Database object
 class NotionDatabaseResponse(BaseModel):
     """
     Represents the response from the Notion API when retrieving a database.
@@ -39,19 +243,96 @@ class NotionDatabaseResponse(BaseModel):
 
     object: Literal["database"]
     id: str
-    cover: Optional[Any]
-    icon: Optional[Icon]
+    cover: Optional[Any] = None
+    icon: Optional[Icon] = None
+    cover: Optional[Cover]
     created_time: str
     last_edited_time: str
-    created_by: User
-    last_edited_by: User
-    title: List[RichText]
+    created_by: NotionUser
+    last_edited_by: NotionUser
+    title: List[RichTextItemPydantic]
     description: List[Any]
     is_inline: bool
-    properties: Dict[str, Any]
-    parent: Parent
+    properties: Dict[
+        str, Any
+    ]  # Using Any for flexibility with different property schemas
+    parent: NotionParent
     url: str
-    public_url: Optional[str]
+    public_url: Optional[str] = None
     archived: bool
     in_trash: bool
-    request_id: Optional[str] = None
+
+
+class NotionPageResponse(BaseModel):
+    object: Literal["page"]
+    id: str
+    created_time: str
+    last_edited_time: str
+    created_by: NotionUser
+    last_edited_by: NotionUser
+    cover: Optional[NotionCover] = None
+    icon: Optional[Icon] = None
+    parent: NotionParent
+    archived: bool
+    in_trash: bool
+    properties: Dict[str, Any]
+    url: str
+    public_url: Optional[str] = None
+
+
+class NotionQueryResponse(BaseModel):
+    """
+    Complete Notion search/query response model that can contain both pages and databases.
+    """
+
+    object: Literal["list"]
+    results: List[Union[NotionPageResponse, NotionDatabaseResponse]]
+    next_cursor: Optional[str] = None
+    has_more: bool
+    type: Literal["page_or_database"]
+    page_or_database: Dict[str, Any]
+    request_id: str
+
+
+# Specific response type for database queries (pages only)
+class NotionQueryDatabaseResponse(BaseModel):
+    """
+    Notion database query response model for querying pages within a database.
+    """
+
+    object: Literal["list"]
+    results: List[NotionPageResponse]
+    next_cursor: Optional[str] = None
+    has_more: bool
+    type: Literal["page_or_database"]
+    page_or_database: Dict[str, Any]
+    request_id: str
+
+
+# Specific response type for search results (can be mixed)
+class NotionSearchResponse(BaseModel):
+    """
+    Notion search response model that can return both pages and databases.
+    """
+
+    object: Literal["list"]
+    results: List[Union[NotionPageResponse, NotionDatabaseResponse]]
+    next_cursor: Optional[str] = None
+    has_more: bool
+    type: Literal["page_or_database"]
+    page_or_database: Dict[str, Any]
+    request_id: str
+
+
+class NotionDatabaseSearchResponse(BaseModel):
+    """
+    Notion search response model for database-only searches.
+    """
+
+    object: Literal["list"]
+    results: List[NotionDatabaseResponse]
+    next_cursor: Optional[str] = None
+    has_more: bool
+    type: Literal["page_or_database"]
+    page_or_database: Dict[str, Any]
+    request_id: str

notionary/models/notion_page_response.py

@@ -1,73 +1,52 @@
-from dataclasses import dataclass
 from typing import Literal, Optional, Dict, Any, Union
 
 from pydantic import BaseModel
 
 
-@dataclass
-class User:
+class User(BaseModel):
     """Represents a Notion user object."""
 
     object: str
     id: str
 
 
-@dataclass
-class ExternalFile:
+class ExternalFile(BaseModel):
     """Represents an external file, e.g., for cover images."""
 
     url: str
 
 
-@dataclass
-class Cover:
+class Cover(BaseModel):
     """Cover image for a Notion page."""
 
     type: str
     external: ExternalFile
 
 
-@dataclass
-class EmojiIcon:
+class EmojiIcon(BaseModel):
     type: Literal["emoji"]
     emoji: str
 
 
-@dataclass
-class ExternalIcon:
+class ExternalIcon(BaseModel):
     type: Literal["external"]
     external: ExternalFile
 
 
-@dataclass
-class FileObject:
-    url: str
-    expiry_time: str
-
-
-@dataclass
-class FileIcon:
-    type: Literal["file"]
-    file: FileObject
-
-
-Icon = Union[EmojiIcon, ExternalIcon, FileIcon]
+Icon = Union[EmojiIcon, ExternalIcon]
 
 
-@dataclass
-class DatabaseParent:
+class DatabaseParent(BaseModel):
     type: Literal["database_id"]
     database_id: str
 
 
-@dataclass
-class PageParent:
+class PageParent(BaseModel):
     type: Literal["page_id"]
     page_id: str
 
 
-@dataclass
-class WorkspaceParent:
+class WorkspaceParent(BaseModel):
     type: Literal["workspace"]
     workspace: bool = True
 
@@ -75,7 +54,6 @@ class WorkspaceParent:
 Parent = Union[DatabaseParent, PageParent, WorkspaceParent]
 
 
-@dataclass
 class NotionPageResponse(BaseModel):
     """
     Represents a full Notion page object as returned by the Notion API.