notionary 0.2.27__py3-none-any.whl → 0.2.28__py3-none-any.whl

notionary/database/service.py

@@ -0,0 +1,169 @@
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Awaitable, Callable
+from typing import Self
+
+from notionary.blocks.rich_text.rich_text_markdown_converter import RichTextToMarkdownConverter
+from notionary.data_source.service import NotionDataSource
+from notionary.database.client import NotionDatabaseHttpClient
+from notionary.database.database_metadata_update_client import DatabaseMetadataUpdateClient
+from notionary.database.schemas import NotionDatabaseDto
+from notionary.shared.entity.dto_parsers import (
+    extract_cover_image_url_from_dto,
+    extract_description,
+    extract_emoji_icon_from_dto,
+    extract_external_icon_url_from_dto,
+    extract_title,
+)
+from notionary.shared.entity.service import Entity
+from notionary.user.schemas import PartialUserDto
+from notionary.workspace.query.service import WorkspaceQueryService
+
+type DataSourceFactory = Callable[[str], Awaitable[NotionDataSource]]
+
+
+class NotionDatabase(Entity):
+    def __init__(
+        self,
+        id: str,
+        title: str,
+        created_time: str,
+        created_by: PartialUserDto,
+        last_edited_time: str,
+        last_edited_by: PartialUserDto,
+        url: str,
+        in_trash: bool,
+        is_inline: bool,
+        data_source_ids: list[str],
+        public_url: str | None = None,
+        emoji_icon: str | None = None,
+        external_icon_url: str | None = None,
+        cover_image_url: str | None = None,
+        description: str | None = None,
+        client: NotionDatabaseHttpClient | None = None,
+        metadata_update_client: DatabaseMetadataUpdateClient | None = None,
+    ) -> None:
+        super().__init__(
+            id=id,
+            created_time=created_time,
+            created_by=created_by,
+            last_edited_time=last_edited_time,
+            last_edited_by=last_edited_by,
+            in_trash=in_trash,
+            emoji_icon=emoji_icon,
+            external_icon_url=external_icon_url,
+            cover_image_url=cover_image_url,
+        )
+        self._title = title
+        self._url = url
+        self._public_url = public_url
+        self._description = description
+        self._is_inline = is_inline
+
+        self._data_sources: list[NotionDataSource] | None = None
+        self._data_source_ids = data_source_ids
+
+        self.client = client or NotionDatabaseHttpClient(database_id=id)
+        self._metadata_update_client = metadata_update_client or DatabaseMetadataUpdateClient(database_id=id)
+
+    @classmethod
+    async def from_id(
+        cls,
+        database_id: str,
+        rich_text_converter: RichTextToMarkdownConverter | None = None,
+        database_client: NotionDatabaseHttpClient | None = None,
+    ) -> Self:
+        converter = rich_text_converter or RichTextToMarkdownConverter()
+        client = database_client or NotionDatabaseHttpClient(database_id=database_id)
+
+        async with client:
+            response_dto = await client.get_database()
+
+        return await cls._create_from_dto(response_dto, converter, client)
+
+    @classmethod
+    async def from_title(
+        cls,
+        database_title: str,
+        min_similarity: float = 0.6,
+        search_service: WorkspaceQueryService | None = None,
+    ) -> Self:
+        service = search_service or WorkspaceQueryService()
+        return await service.find_database(database_title, min_similarity=min_similarity)
+
+    @classmethod
+    async def _create_from_dto(
+        cls,
+        response: NotionDatabaseDto,
+        rich_text_converter: RichTextToMarkdownConverter,
+        client: NotionDatabaseHttpClient,
+    ) -> Self:
+        title, description = await asyncio.gather(
+            extract_title(response, rich_text_converter), extract_description(response, rich_text_converter)
+        )
+
+        return cls(
+            id=response.id,
+            title=title,
+            description=description,
+            created_time=response.created_time,
+            created_by=response.created_by,
+            last_edited_time=response.last_edited_time,
+            last_edited_by=response.last_edited_by,
+            in_trash=response.in_trash,
+            is_inline=response.is_inline,
+            url=response.url,
+            public_url=response.public_url,
+            emoji_icon=extract_emoji_icon_from_dto(response),
+            external_icon_url=extract_external_icon_url_from_dto(response),
+            cover_image_url=extract_cover_image_url_from_dto(response),
+            data_source_ids=[ds.id for ds in response.data_sources],
+            client=client,
+        )
+
+    @property
+    def _entity_metadata_update_client(self) -> DatabaseMetadataUpdateClient:
+        return self._metadata_update_client
+
+    @property
+    def title(self) -> str:
+        return self._title
+
+    @property
+    def url(self) -> str:
+        return self._url
+
+    @property
+    def public_url(self) -> str | None:
+        return self._public_url
+
+    @property
+    def is_inline(self) -> bool:
+        return self._is_inline
+
+    def get_description(self) -> str | None:
+        return self._description
+
+    async def get_data_sources(
+        self,
+        data_source_factory: DataSourceFactory = NotionDataSource.from_id,
+    ) -> list[NotionDataSource]:
+        if self._data_sources is None:
+            self._data_sources = await self._load_data_sources(data_source_factory)
+        return self._data_sources
+
+    async def _load_data_sources(
+        self,
+        data_source_factory: DataSourceFactory,
+    ) -> list[NotionDataSource]:
+        tasks = [data_source_factory(ds_id) for ds_id in self._data_source_ids]
+        return list(await asyncio.gather(*tasks))
+
+    async def set_title(self, title: str) -> None:
+        result = await self.client.update_database_title(title=title)
+        self._title = result.title[0].plain_text if result.title else ""
+
+    async def set_description(self, description: str) -> None:
+        updated_description = await self.client.update_database_description(description=description)
+        self._description = updated_description

notionary/exceptions/__init__.py

@@ -0,0 +1,33 @@
+from .api import (
+    NotionApiError,
+    NotionAuthenticationError,
+    NotionConnectionError,
+    NotionRateLimitError,
+    NotionResourceNotFoundError,
+    NotionServerError,
+    NotionValidationError,
+)
+from .base import NotionaryError
+from .data_source.properties import DataSourcePropertyNotFound, DataSourcePropertyTypeError
+from .properties import AccessPagePropertyWithoutDataSourceError, PagePropertyNotFoundError, PagePropertyTypeError
+from .search import DatabaseNotFound, DataSourceNotFound, EntityNotFound, PageNotFound
+
+__all__ = [
+    "AccessPagePropertyWithoutDataSourceError",
+    "DataSourceNotFound",
+    "DataSourcePropertyNotFound",
+    "DataSourcePropertyTypeError",
+    "DatabaseNotFound",
+    "EntityNotFound",
+    "NotionApiError",
+    "NotionAuthenticationError",
+    "NotionConnectionError",
+    "NotionRateLimitError",
+    "NotionResourceNotFoundError",
+    "NotionServerError",
+    "NotionValidationError",
+    "NotionaryError",
+    "PageNotFound",
+    "PagePropertyNotFoundError",
+    "PagePropertyTypeError",
+]

notionary/exceptions/api.py

@@ -0,0 +1,41 @@
+from notionary.exceptions.base import NotionaryError
+
+
+class NotionApiError(NotionaryError):
+    def __init__(
+        self,
+        message: str,
+        status_code: int | None = None,
+        response_text: int | None = None,
+    ):
+        super().__init__(message)
+        self.status_code = status_code
+        self.response_text = response_text
+
+
+class NotionAuthenticationError(NotionApiError):
+    pass
+
+
+class NotionPermissionError(NotionApiError):
+    pass
+
+
+class NotionRateLimitError(NotionApiError):
+    pass
+
+
+class NotionResourceNotFoundError(NotionApiError):
+    pass
+
+
+class NotionValidationError(NotionApiError):
+    pass
+
+
+class NotionServerError(NotionApiError):
+    pass
+
+
+class NotionConnectionError(NotionApiError):
+    pass

notionary/exceptions/base.py

@@ -0,0 +1,2 @@
+class NotionaryError(Exception):
+    pass

notionary/exceptions/block_parsing.py

@@ -0,0 +1,16 @@
+from notionary.exceptions.base import NotionaryError
+
+RATIO_TOLERANCE = 0.0001
+
+
+class InsufficientColumnsError(NotionaryError):
+    def __init__(self, column_count: int) -> None:
+        self.column_count = column_count
+        super().__init__(f"Columns container must contain at least 2 column blocks, but only {column_count} found")
+
+
+class InvalidColumnRatioSumError(NotionaryError):
+    def __init__(self, total: float, tolerance: float = RATIO_TOLERANCE) -> None:
+        self.total = total
+        self.tolerance = tolerance
+        super().__init__(f"Width ratios must sum to 1.0 (±{tolerance}), but sum is {total}")

notionary/exceptions/data_source/__init__.py

@@ -0,0 +1,6 @@
+from .properties import DataSourcePropertyNotFound, DataSourcePropertyTypeError
+
+__all__ = [
+    "DataSourcePropertyNotFound",
+    "DataSourcePropertyTypeError",
+]

notionary/exceptions/data_source/builder.py

@@ -0,0 +1,182 @@
+from typing import Any
+
+from notionary.data_source.query.schema import (
+    ArrayOperator,
+    BooleanOperator,
+    DateOperator,
+    NumberOperator,
+    Operator,
+    StringOperator,
+)
+from notionary.exceptions.base import NotionaryError
+from notionary.shared.properties.type import PropertyType
+
+
+class QueryBuilderError(NotionaryError):
+    def __init__(self, message: str, property_name: str | None = None) -> None:
+        self.property_name = property_name
+        super().__init__(message)
+
+
+class InvalidOperatorForPropertyType(QueryBuilderError):
+    def __init__(
+        self,
+        property_name: str,
+        property_type: PropertyType,
+        operator: Operator,
+        valid_operators: list[Operator],
+    ) -> None:
+        self.property_type = property_type
+        self.operator = operator
+        self.valid_operators = valid_operators
+
+        valid_operators_str = ", ".join([f"'{op.value}'" for op in valid_operators])
+        message = (
+            f"Cannot use operator '{operator.value}' on property '{property_name}' of type '{property_type}'. "
+            f"Valid operators for this property type are: {valid_operators_str}"
+        )
+        super().__init__(message, property_name)
+
+
+class InvalidValueForOperator(QueryBuilderError):
+    def __init__(
+        self,
+        property_name: str,
+        operator: Operator,
+        provided_value: Any,
+        expected_value_type: str,
+        example_value: Any | None = None,
+    ) -> None:
+        self.operator = operator
+        self.provided_value = provided_value
+        self.expected_value_type = expected_value_type
+        self.example_value = example_value
+
+        message = (
+            f"Invalid value for operator '{operator.value}' on property '{property_name}'. "
+            f"Expected {expected_value_type}, but got {type(provided_value).__name__}"
+        )
+
+        if example_value is not None:
+            message += f". Example: {example_value}"
+
+        super().__init__(message, property_name)
+
+
+class MissingRequiredValue(QueryBuilderError):
+    def __init__(
+        self,
+        property_name: str,
+        operator: StringOperator | NumberOperator | BooleanOperator | DateOperator | ArrayOperator,
+    ) -> None:
+        self.operator = operator
+
+        message = f"Operator '{operator.value}' on property '{property_name}' requires a value, but none was provided"
+        super().__init__(message, property_name)
+
+
+class ValueNotAllowedForOperator(QueryBuilderError):
+    def __init__(
+        self,
+        property_name: str,
+        operator: StringOperator | NumberOperator | BooleanOperator | DateOperator | ArrayOperator,
+    ) -> None:
+        self.operator = operator
+
+        message = (
+            f"Operator '{operator.value}' on property '{property_name}' does not accept a value. "
+            f"Operators like 'is_empty', 'is_not_empty', 'is_true', 'is_false' don't need values"
+        )
+        super().__init__(message, property_name)
+
+
+class InvalidDateFormat(QueryBuilderError):
+    def __init__(
+        self,
+        property_name: str,
+        provided_date: str,
+        expected_format: str = "ISO 8601 (YYYY-MM-DD or YYYY-MM-DDTHH:MM:SS)",
+    ) -> None:
+        self.provided_date = provided_date
+        self.expected_format = expected_format
+
+        message = (
+            f"Invalid date format for property '{property_name}'. "
+            f"Provided: '{provided_date}', expected format: {expected_format}"
+        )
+        super().__init__(message, property_name)
+
+
+class InvalidNumberValue(QueryBuilderError):
+    def __init__(
+        self,
+        property_name: str,
+        provided_value: Any,
+        reason: str,
+    ) -> None:
+        self.provided_value = provided_value
+        self.reason = reason
+
+        message = f"Invalid number value for property '{property_name}': {reason}. Provided value: {provided_value}"
+        super().__init__(message, property_name)
+
+
+class PropertyNotConfigured(QueryBuilderError):
+    def __init__(
+        self,
+        property_name: str,
+    ) -> None:
+        message = (
+            f"Property '{property_name}' exists but has no type configuration. "
+            f"Cannot determine valid operators for this property"
+        )
+        super().__init__(message, property_name)
+
+
+class NoPropertySelected(QueryBuilderError):
+    def __init__(self) -> None:
+        message = (
+            "No property selected. Use .where('property_name') or .where_not('property_name') "
+            "before calling an operator method like .equals(), .contains(), etc."
+        )
+        super().__init__(message)
+
+
+class EmptyOrGroupError(QueryBuilderError):
+    def __init__(self) -> None:
+        message = (
+            "Cannot create an OR group with no conditions. Add at least one filter condition before using .or_where()"
+        )
+        super().__init__(message)
+
+
+class ConflictingFiltersError(QueryBuilderError):
+    def __init__(
+        self,
+        property_name: str,
+        description: str,
+    ) -> None:
+        message = (
+            f"Conflicting filters detected on property '{property_name}': {description}. "
+            f"This query will never return any results"
+        )
+        super().__init__(message, property_name)
+
+
+class InvalidSortProperty(QueryBuilderError):
+    def __init__(
+        self,
+        property_name: str,
+        reason: str,
+        available_properties: list[str] | None = None,
+    ) -> None:
+        self.available_properties = available_properties
+        self.reason = reason
+
+        message = f"Cannot sort by property '{property_name}': {reason}"
+
+        if available_properties:
+            props_str = ", ".join([f"'{p}'" for p in sorted(available_properties)])
+            message += f". Available properties: {props_str}"
+
+        super().__init__(message, property_name)

notionary/exceptions/data_source/properties.py

@@ -0,0 +1,34 @@
+import difflib
+
+from notionary.exceptions.base import NotionaryError
+
+
+class DataSourcePropertyNotFound(NotionaryError):
+    def __init__(
+        self,
+        property_name: str,
+        available_properties: list[str] | None = None,
+        max_suggestions: int = 5,
+        cutoff: float = 0.6,
+    ) -> None:
+        self.property_name = property_name
+
+        # Calculate suggestions from available properties
+        if available_properties:
+            self.suggestions = difflib.get_close_matches(
+                property_name, available_properties, n=max_suggestions, cutoff=cutoff
+            )
+        else:
+            self.suggestions = []
+
+        message = f"Property '{self.property_name}' not found."
+        if self.suggestions:
+            suggestions_str = "', '".join(self.suggestions)
+            message += f" Did you mean '{suggestions_str}'?"
+        super().__init__(message)
+
+
+class DataSourcePropertyTypeError(NotionaryError):
+    def __init__(self, property_name: str, expected_type: str, actual_type: str) -> None:
+        message = f"Property '{property_name}' has the wrong type. Expected: '{expected_type}', found: '{actual_type}'."
+        super().__init__(message)

notionary/exceptions/properties.py

@@ -0,0 +1,58 @@
+import difflib
+from typing import ClassVar
+
+from notionary.exceptions.base import NotionaryError
+from notionary.shared.models.parent import ParentType
+
+
+class PagePropertyNotFoundError(NotionaryError):
+    def __init__(
+        self,
+        page_url: str,
+        property_name: str,
+        available_properties: list[str] | None = None,
+        max_suggestions: int = 3,
+        cutoff: float = 0.6,
+    ) -> None:
+        self.property_name = property_name
+
+        if available_properties:
+            self.suggestions = difflib.get_close_matches(
+                property_name, available_properties, n=max_suggestions, cutoff=cutoff
+            )
+        else:
+            self.suggestions = []
+
+        message = f"Property '{property_name}' not found."
+        if self.suggestions:
+            suggestions_str = "', '".join(self.suggestions)
+            message += f" Did you mean '{suggestions_str}'?"
+        message += f" Please check the page at {page_url} to verify if the property exists and is correctly named."
+        super().__init__(message)
+
+
+class PagePropertyTypeError(NotionaryError):
+    def __init__(
+        self,
+        property_name: str,
+        actual_type: str,
+    ) -> None:
+        message = f"Property '{property_name}' is of type '{actual_type}'. Use the appropriate getter method for this property type."
+        super().__init__(message)
+
+
+class AccessPagePropertyWithoutDataSourceError(NotionaryError):
+    _PARENT_DESCRIPTIONS: ClassVar[dict[ParentType, str]] = {
+        ParentType.WORKSPACE: "the workspace itself",
+        ParentType.PAGE_ID: "another page",
+        ParentType.BLOCK_ID: "a block",
+        ParentType.DATABASE_ID: "a database",
+    }
+
+    def __init__(self, parent_type: ParentType) -> None:
+        parent_desc = self._PARENT_DESCRIPTIONS.get(parent_type, f"its parent type is '{parent_type}'")
+        message = (
+            f"Cannot access properties other than title because this page's parent is {parent_desc}. "
+            "To use operations like property reading/writing, you need to use a page whose parent is a data source."
+        )
+        super().__init__(message)

notionary/exceptions/search.py

@@ -0,0 +1,33 @@
+from notionary.exceptions.base import NotionaryError
+
+
+class EntityNotFound(NotionaryError):
+    def __init__(self, entity_type: str, query: str, available_titles: list[str] | None = None) -> None:
+        self.entity_type = entity_type
+        self.query = query
+        self.available_titles = available_titles or []
+
+        if self.available_titles:
+            message = (
+                f"No sufficiently similar {entity_type} found for query '{query}'. "
+                f"Did you mean one of these? Top results: {self.available_titles}"
+            )
+        else:
+            message = f"No {entity_type} found for query '{query}'. The search returned no results."
+
+        super().__init__(message)
+
+
+class PageNotFound(EntityNotFound):
+    def __init__(self, query: str, available_titles: list[str] | None = None) -> None:
+        super().__init__("page", query, available_titles)
+
+
+class DataSourceNotFound(EntityNotFound):
+    def __init__(self, query: str, available_titles: list[str] | None = None) -> None:
+        super().__init__("data source", query, available_titles)
+
+
+class DatabaseNotFound(EntityNotFound):
+    def __init__(self, query: str, available_titles: list[str] | None = None) -> None:
+        super().__init__("database", query, available_titles)