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

notionary/data_source/query/schema.py

@@ -0,0 +1,302 @@
+from __future__ import annotations
+
+from enum import StrEnum
+from typing import Self
+
+from pydantic import BaseModel, ValidationInfo, field_validator, model_serializer, model_validator
+
+from notionary.shared.properties.type import PropertyType
+from notionary.shared.typings import JsonDict
+
+
+class FieldType(StrEnum):
+    STRING = "string"
+    NUMBER = "number"
+    BOOLEAN = "boolean"
+    DATE = "date"
+    DATETIME = "datetime"
+    ARRAY = "array"
+    RELATION = "relation"
+    PEOPLE = "people"
+
+
+class StringOperator(StrEnum):
+    EQUALS = "equals"
+    DOES_NOT_EQUAL = "does_not_equal"
+    CONTAINS = "contains"
+    DOES_NOT_CONTAIN = "does_not_contain"
+    STARTS_WITH = "starts_with"
+    ENDS_WITH = "ends_with"
+    IS_EMPTY = "is_empty"
+    IS_NOT_EMPTY = "is_not_empty"
+
+
+class NumberOperator(StrEnum):
+    EQUALS = "equals"
+    DOES_NOT_EQUAL = "does_not_equal"
+    GREATER_THAN = "greater_than"
+    GREATER_THAN_OR_EQUAL_TO = "greater_than_or_equal_to"
+    LESS_THAN = "less_than"
+    LESS_THAN_OR_EQUAL_TO = "less_than_or_equal_to"
+    IS_EMPTY = "is_empty"
+    IS_NOT_EMPTY = "is_not_empty"
+
+
+class BooleanOperator(StrEnum):
+    IS_TRUE = "is_true"
+    IS_FALSE = "is_false"
+
+
+class SelectOperator(StrEnum):
+    EQUALS = "equals"
+    DOES_NOT_EQUAL = "does_not_equal"
+    IS_EMPTY = "is_empty"
+    IS_NOT_EMPTY = "is_not_empty"
+
+
+class DateOperator(StrEnum):
+    EQUALS = "equals"
+    BEFORE = "before"
+    AFTER = "after"
+    ON_OR_BEFORE = "on_or_before"
+    ON_OR_AFTER = "on_or_after"
+    IS_EMPTY = "is_empty"
+    IS_NOT_EMPTY = "is_not_empty"
+
+
+class ArrayOperator(StrEnum):
+    CONTAINS = "contains"
+    DOES_NOT_CONTAIN = "does_not_contain"
+    IS_EMPTY = "is_empty"
+    IS_NOT_EMPTY = "is_not_empty"
+
+
+class LogicalOperator(StrEnum):
+    AND = "and"
+    OR = "or"
+
+
+class SortDirection(StrEnum):
+    ASCENDING = "ascending"
+    DESCENDING = "descending"
+
+
+class TimestampType(StrEnum):
+    CREATED_TIME = "created_time"
+    LAST_EDITED_TIME = "last_edited_time"
+
+
+class TimeUnit(StrEnum):
+    DAYS = "days"
+    WEEKS = "weeks"
+    MONTHS = "months"
+    YEARS = "years"
+
+
+type Operator = StringOperator | NumberOperator | BooleanOperator | DateOperator | ArrayOperator
+type FilterValue = str | int | float | bool | list[str | int | float]
+
+
+class FilterCondition(BaseModel):
+    field: str
+    field_type: FieldType
+    operator: Operator
+    value: FilterValue | None = None
+    time_value: int | None = None
+    time_unit: TimeUnit | None = None
+
+    @model_validator(mode="after")
+    def validate_operator_and_value(self) -> Self:
+        self._validate_no_value_operators()
+        self._validate_value_required_operators()
+        self._validate_value_type_matches_field_type()
+        return self
+
+    def _validate_no_value_operators(self) -> None:
+        no_value_ops = {
+            StringOperator.IS_EMPTY,
+            StringOperator.IS_NOT_EMPTY,
+            NumberOperator.IS_EMPTY,
+            NumberOperator.IS_NOT_EMPTY,
+            BooleanOperator.IS_TRUE,
+            BooleanOperator.IS_FALSE,
+            DateOperator.IS_EMPTY,
+            DateOperator.IS_NOT_EMPTY,
+            ArrayOperator.IS_EMPTY,
+            ArrayOperator.IS_NOT_EMPTY,
+        }
+        if self.operator in no_value_ops and self.value is not None:
+            raise ValueError(f"Operator '{self.operator}' does not expect a value")
+
+    def _validate_value_required_operators(self) -> None:
+        operators_to_skip = {
+            StringOperator.IS_EMPTY,
+            StringOperator.IS_NOT_EMPTY,
+            NumberOperator.IS_EMPTY,
+            NumberOperator.IS_NOT_EMPTY,
+            BooleanOperator.IS_TRUE,
+            BooleanOperator.IS_FALSE,
+            DateOperator.IS_EMPTY,
+            DateOperator.IS_NOT_EMPTY,
+            ArrayOperator.IS_EMPTY,
+            ArrayOperator.IS_NOT_EMPTY,
+        }
+
+        is_skipped_operator = self.operator in operators_to_skip
+        if not is_skipped_operator and self.value is None:
+            raise ValueError(f"Operator '{self.operator}' requires a value")
+
+    def _validate_value_type_matches_field_type(self) -> None:
+        if self.value is None:
+            return
+
+        if self.field_type == FieldType.STRING:
+            self._ensure_value_is_string()
+        elif self.field_type == FieldType.NUMBER:
+            self._ensure_value_is_number()
+        elif self.field_type == FieldType.BOOLEAN:
+            self._ensure_value_is_boolean()
+        elif self.field_type in (FieldType.DATE, FieldType.DATETIME) or self.field_type in (
+            FieldType.ARRAY,
+            FieldType.RELATION,
+            FieldType.PEOPLE,
+        ):
+            self._ensure_value_is_string()
+
+    def _ensure_value_is_string(self) -> None:
+        if not isinstance(self.value, str):
+            raise ValueError(
+                f"Value for field type '{self.field_type}' must be a string, got {type(self.value).__name__}"
+            )
+
+    def _ensure_value_is_number(self) -> None:
+        if not isinstance(self.value, (int, float)):
+            raise ValueError(
+                f"Value for field type '{self.field_type}' must be a number (int or float), "
+                f"got {type(self.value).__name__}"
+            )
+
+    def _ensure_value_is_boolean(self) -> None:
+        if not isinstance(self.value, bool):
+            raise ValueError(
+                f"Value for field type '{self.field_type}' must be a boolean, got {type(self.value).__name__}"
+            )
+
+    @field_validator("operator")
+    @classmethod
+    def validate_operator_for_field_type(
+        cls,
+        value: Operator,
+        info: ValidationInfo,
+    ) -> Operator:
+        if "field_type" not in info.data:
+            return value
+
+        field_type: FieldType = info.data["field_type"]
+        operator_value = value if isinstance(value, str) else value.value
+
+        if not cls._is_operator_valid_for_field_type(operator_value, field_type):
+            raise ValueError(f"Operator '{operator_value}' is not valid for field type '{field_type}'")
+
+        return value
+
+    @staticmethod
+    def _is_operator_valid_for_field_type(operator: str, field_type: FieldType) -> bool:
+        valid_operators: dict[FieldType, list[str]] = {
+            FieldType.STRING: [op.value for op in StringOperator],
+            FieldType.NUMBER: [op.value for op in NumberOperator],
+            FieldType.BOOLEAN: [op.value for op in BooleanOperator],
+            FieldType.DATE: [op.value for op in DateOperator],
+            FieldType.DATETIME: [op.value for op in DateOperator],
+            FieldType.ARRAY: [op.value for op in ArrayOperator],
+            FieldType.RELATION: [op.value for op in ArrayOperator],
+            FieldType.PEOPLE: [op.value for op in ArrayOperator],
+        }
+
+        return operator in valid_operators.get(field_type, [])
+
+
+class OrGroupMarker(BaseModel):
+    conditions: list[FilterCondition]
+
+
+type InternalFilterCondition = FilterCondition | OrGroupMarker
+
+
+class PropertyFilter(BaseModel):
+    property: str
+    property_type: PropertyType
+    operator: Operator
+    value: FilterValue | None = None
+
+    @model_validator(mode="after")
+    def validate_value_type(self) -> Self:
+        if self.value is None:
+            return self
+
+        if self.property_type in (PropertyType.PEOPLE, PropertyType.RELATION) and not isinstance(self.value, str):
+            raise ValueError(
+                f"Value for property type '{self.property_type.value}' must be a string, "
+                f"got {type(self.value).__name__}"
+            )
+
+        return self
+
+    @model_serializer
+    def serialize_model(self) -> JsonDict:
+        property_type_str = self.property_type.value
+        operator_str = self.operator.value
+        filter_value = self.value
+
+        if isinstance(self.operator, BooleanOperator):
+            operator_str = "equals"
+            filter_value = self.operator == BooleanOperator.IS_TRUE
+
+        return {
+            "property": self.property,
+            property_type_str: {operator_str: filter_value if filter_value is not None else True},
+        }
+
+
+class CompoundFilter(BaseModel):
+    operator: LogicalOperator
+    filters: list[PropertyFilter | CompoundFilter]
+
+    @model_serializer
+    def serialize_model(self) -> JsonDict:
+        operator_str = self.operator.value
+        return {operator_str: [f.model_dump() for f in self.filters]}
+
+
+type NotionFilter = PropertyFilter | CompoundFilter
+
+
+class PropertySort(BaseModel):
+    property: str
+    direction: SortDirection
+
+
+class TimestampSort(BaseModel):
+    timestamp: TimestampType
+    direction: SortDirection
+
+
+type NotionSort = PropertySort | TimestampSort
+
+
+class DataSourceQueryParams(BaseModel):
+    filter: NotionFilter | None = None
+    sorts: list[NotionSort] | None = None
+    page_size: int | None = None
+
+    @model_serializer
+    def to_api_params(self) -> JsonDict:
+        result: JsonDict = {}
+
+        if self.filter is not None:
+            result["filter"] = self.filter.model_dump()
+
+        if self.sorts is not None and len(self.sorts) > 0:
+            result["sorts"] = [sort.model_dump() for sort in self.sorts]
+
+        return result

notionary/data_source/query/validator.py

@@ -0,0 +1,73 @@
+from typing import ClassVar
+
+from notionary.data_source.properties.schemas import DataSourceProperty
+from notionary.data_source.query.schema import (
+    ArrayOperator,
+    BooleanOperator,
+    DateOperator,
+    NumberOperator,
+    Operator,
+    SelectOperator,
+    StringOperator,
+)
+from notionary.exceptions.data_source.builder import InvalidOperatorForPropertyType
+from notionary.shared.properties.type import PropertyType
+
+
+class QueryValidator:
+    _PROPERTY_TYPE_OPERATORS: ClassVar[dict[PropertyType, list[type[Operator]]]] = {
+        PropertyType.TITLE: [StringOperator],
+        PropertyType.RICH_TEXT: [StringOperator],
+        PropertyType.URL: [StringOperator],
+        PropertyType.EMAIL: [StringOperator],
+        PropertyType.PHONE_NUMBER: [StringOperator],
+        PropertyType.SELECT: [SelectOperator],
+        PropertyType.STATUS: [SelectOperator],
+        PropertyType.MULTI_SELECT: [ArrayOperator],
+        PropertyType.NUMBER: [NumberOperator],
+        PropertyType.DATE: [DateOperator],
+        PropertyType.CREATED_TIME: [DateOperator],
+        PropertyType.LAST_EDITED_TIME: [DateOperator],
+        PropertyType.PEOPLE: [ArrayOperator],
+        PropertyType.CREATED_BY: [ArrayOperator],
+        PropertyType.LAST_EDITED_BY: [ArrayOperator],
+        PropertyType.RELATION: [ArrayOperator],
+        PropertyType.CHECKBOX: [BooleanOperator],
+    }
+
+    def validate_operator_for_property(
+        self, property_name: str, property_obj: DataSourceProperty, operator: Operator
+    ) -> None:
+        if not self._is_operator_valid_for_property_type(property_obj.type, operator):
+            valid_operators = self._get_valid_operators_for_property_type(property_obj.type)
+            raise InvalidOperatorForPropertyType(
+                property_name=property_name,
+                property_type=property_obj.type,
+                operator=operator,
+                valid_operators=valid_operators,
+            )
+
+    def _is_operator_valid_for_property_type(self, property_type: PropertyType, operator: Operator) -> bool:
+        allowed_operator_types = self._PROPERTY_TYPE_OPERATORS.get(property_type, [])
+        valid_operator_values = self._get_operator_values_from_types(allowed_operator_types)
+        return operator.value in valid_operator_values
+
+    def _get_operator_values_from_types(self, operator_types: list[type[Operator]]) -> set[str]:
+        values: set[str] = set()
+        for operator_type in operator_types:
+            for operator in operator_type:
+                values.add(operator.value)
+        return values
+
+    def _get_valid_operators_for_property_type(self, property_type: PropertyType) -> list[Operator]:
+        allowed_operator_types = self._PROPERTY_TYPE_OPERATORS.get(property_type, [])
+        return self._collect_all_operators_from_types(allowed_operator_types)
+
+    def _collect_all_operators_from_types(self, operator_types: list[type[Operator]]) -> list[Operator]:
+        operators: list[Operator] = []
+        for operator_type in operator_types:
+            operators.extend(self._get_all_enum_values(operator_type))
+        return operators
+
+    def _get_all_enum_values(self, operator_type: type[Operator]) -> list[Operator]:
+        return list(operator_type)

notionary/data_source/schema/registry.py

@@ -0,0 +1,104 @@
+from dataclasses import dataclass
+
+from notionary.shared.properties.type import PropertyType
+
+
+@dataclass(frozen=True)
+class PropertyTypeDescriptor:
+    display_name: str
+    description: str
+
+
+class DatabasePropertyTypeDescriptorRegistry:
+    def __init__(self):
+        self._DESCRIPTORS = {
+            PropertyType.TITLE: PropertyTypeDescriptor(
+                display_name="Title", description="Required field for the main heading of the entry"
+            ),
+            PropertyType.RICH_TEXT: PropertyTypeDescriptor(
+                display_name="Rich Text", description="Free-form text field for additional information"
+            ),
+            PropertyType.NUMBER: PropertyTypeDescriptor(display_name="Number", description="Numeric value field"),
+            PropertyType.CHECKBOX: PropertyTypeDescriptor(
+                display_name="Checkbox", description="Boolean value (true/false)"
+            ),
+            PropertyType.DATE: PropertyTypeDescriptor(display_name="Date", description="Date or date range field"),
+            PropertyType.URL: PropertyTypeDescriptor(display_name="URL", description="Web address field"),
+            PropertyType.EMAIL: PropertyTypeDescriptor(display_name="Email", description="Email address field"),
+            PropertyType.PHONE_NUMBER: PropertyTypeDescriptor(
+                display_name="Phone Number", description="Phone number field"
+            ),
+            PropertyType.FILES: PropertyTypeDescriptor(
+                display_name="Files & Media", description="Upload or link to files"
+            ),
+            PropertyType.PEOPLE: PropertyTypeDescriptor(display_name="People", description="Reference to Notion users"),
+            PropertyType.SELECT: PropertyTypeDescriptor(
+                display_name="Single Select", description="Choose one option from available choices"
+            ),
+            PropertyType.MULTI_SELECT: PropertyTypeDescriptor(
+                display_name="Multi Select", description="Choose multiple options from available choices"
+            ),
+            PropertyType.STATUS: PropertyTypeDescriptor(
+                display_name="Status", description="Track status with predefined options"
+            ),
+            PropertyType.RELATION: PropertyTypeDescriptor(
+                display_name="Relation", description="Link to entries in another database"
+            ),
+            PropertyType.CREATED_TIME: PropertyTypeDescriptor(
+                display_name="Created Time",
+                description="Automatically set when the page is created",
+            ),
+            PropertyType.CREATED_BY: PropertyTypeDescriptor(
+                display_name="Created By",
+                description="Automatically set to the user who created the page",
+            ),
+            PropertyType.LAST_EDITED_TIME: PropertyTypeDescriptor(
+                display_name="Last Edited Time",
+                description="Automatically updated when the page is modified",
+            ),
+            PropertyType.LAST_EDITED_BY: PropertyTypeDescriptor(
+                display_name="Last Edited By",
+                description="Automatically set to the user who last edited the page",
+            ),
+            PropertyType.LAST_VISITED_TIME: PropertyTypeDescriptor(
+                display_name="Last Visited Time",
+                description="Automatically updated when the page is visited",
+            ),
+            PropertyType.FORMULA: PropertyTypeDescriptor(
+                display_name="Formula",
+                description="Computed value based on other properties",
+            ),
+            PropertyType.ROLLUP: PropertyTypeDescriptor(
+                display_name="Rollup",
+                description="Aggregate values from related database entries",
+            ),
+            PropertyType.BUTTON: PropertyTypeDescriptor(
+                display_name="Button",
+                description="Interactive button that triggers an action",
+            ),
+            PropertyType.LOCATION: PropertyTypeDescriptor(
+                display_name="Location",
+                description="Geographic location field",
+            ),
+            PropertyType.PLACE: PropertyTypeDescriptor(
+                display_name="Place",
+                description="Place or venue information",
+            ),
+            PropertyType.VERIFICATION: PropertyTypeDescriptor(
+                display_name="Verification",
+                description="Verification status field",
+            ),
+            PropertyType.UNIQUE_ID: PropertyTypeDescriptor(
+                display_name="Unique ID",
+                description="Auto-generated unique identifier",
+            ),
+        }
+
+    def get_descriptor(self, property_type: PropertyType) -> PropertyTypeDescriptor:
+        return self._DESCRIPTORS.get(
+            property_type,
+            PropertyTypeDescriptor(display_name=self._format_unknown_type_name(property_type), description=""),
+        )
+
+    def _format_unknown_type_name(self, property_type: PropertyType) -> str:
+        return property_type.value.replace("_", " ").title()

notionary/data_source/schema/service.py

@@ -0,0 +1,136 @@
+from collections.abc import Awaitable, Callable
+
+from notionary.blocks.rich_text.name_id_resolver import DataSourceNameIdResolver
+from notionary.data_source.properties.schemas import (
+    DataSourceMultiSelectProperty,
+    DataSourceProperty,
+    DataSourceRelationProperty,
+    DataSourceSelectProperty,
+    DataSourceStatusProperty,
+)
+from notionary.data_source.schema.registry import DatabasePropertyTypeDescriptorRegistry, PropertyTypeDescriptor
+from notionary.shared.properties.type import PropertyType
+
+
+class PropertyFormatter:
+    INDENTATION = "   - "
+
+    def __init__(
+        self,
+        relation_options_fetcher: Callable[[DataSourceRelationProperty], Awaitable[list[str]]],
+        type_descriptor_registry: DatabasePropertyTypeDescriptorRegistry | None = None,
+        data_source_resolver: DataSourceNameIdResolver | None = None,
+    ) -> None:
+        self._relation_options_fetcher = relation_options_fetcher
+        self._type_descriptor_registry = type_descriptor_registry or DatabasePropertyTypeDescriptorRegistry()
+        self._data_source_resolver = data_source_resolver or DataSourceNameIdResolver()
+
+    async def format_property(self, prop: DataSourceProperty) -> list[str]:
+        specific_details = await self._format_property_specific_details(prop)
+
+        if specific_details:
+            return [*specific_details, *self._format_custom_description(prop)]
+
+        descriptor = self._type_descriptor_registry.get_descriptor(prop.type)
+        return [*self._format_property_description(descriptor), *self._format_custom_description(prop)]
+
+    def _format_property_description(self, descriptor: PropertyTypeDescriptor) -> list[str]:
+        if not descriptor.description:
+            return []
+        return [f"{self.INDENTATION}{descriptor.description}"]
+
+    async def _format_property_specific_details(self, prop: DataSourceProperty) -> list[str]:
+        if isinstance(prop, DataSourceSelectProperty):
+            return self._format_available_options("Choose one option from", prop.option_names)
+
+        if isinstance(prop, DataSourceMultiSelectProperty):
+            return self._format_available_options("Choose multiple options from", prop.option_names)
+
+        if isinstance(prop, DataSourceStatusProperty):
+            return self._format_available_options("Available statuses", prop.option_names)
+
+        if isinstance(prop, DataSourceRelationProperty):
+            return await self._format_relation_details(prop)
+
+        return []
+
+    def _format_custom_description(self, prop: DataSourceProperty) -> list[str]:
+        if not prop.description:
+            return []
+        return [f"{self.INDENTATION}Description: {prop.description}"]
+
+    def _format_available_options(self, label: str, options: list[str]) -> list[str]:
+        options_text = ", ".join(options)
+        return [f"{self.INDENTATION}{label}: {options_text}"]
+
+    async def _format_relation_details(self, prop: DataSourceRelationProperty) -> list[str]:
+        if not prop.related_data_source_id:
+            return []
+
+        data_source_name = await self._data_source_resolver.resolve_id_to_name(prop.related_data_source_id)
+        data_source_display = data_source_name or prop.related_data_source_id
+        lines = [f"{self.INDENTATION}Links to datasource: {data_source_display}"]
+
+        available_entries = await self._fetch_relation_entries(prop)
+        if available_entries:
+            entries_text = ", ".join(available_entries)
+            lines.append(f"{self.INDENTATION}Available entries: {entries_text}")
+
+        return lines
+
+    async def _fetch_relation_entries(self, prop: DataSourceRelationProperty) -> list[str] | None:
+        try:
+            return await self._relation_options_fetcher(prop)
+        except Exception:
+            return None
+
+
+class DataSourcePropertySchemaFormatter:
+    def __init__(
+        self,
+        relation_options_fetcher: Callable[[DataSourceRelationProperty], Awaitable[list[str]]] | None = None,
+        data_source_resolver: DataSourceNameIdResolver | None = None,
+    ) -> None:
+        self._property_formatter = PropertyFormatter(
+            relation_options_fetcher, data_source_resolver=data_source_resolver
+        )
+
+    async def format(self, title: str, description: str | None, properties: dict[str, DataSourceProperty]) -> str:
+        lines = self._format_header(title, description)
+        lines.append("Properties:")
+        lines.append("")
+        lines.extend(await self._format_properties(properties))
+
+        return "\n".join(lines)
+
+    def _format_header(self, title: str, description: str | None) -> list[str]:
+        lines = [f"Data Source: {title}", ""]
+
+        if description:
+            lines.append(f"Description: {description}")
+            lines.append("")
+
+        return lines
+
+    async def _format_properties(self, properties: dict[str, DataSourceProperty]) -> list[str]:
+        lines = []
+        sorted_properties = self._sort_with_title_first(properties)
+
+        for index, (name, prop) in enumerate(sorted_properties, start=1):
+            lines.extend(await self._format_single_property(index, name, prop))
+
+        return lines
+
+    def _sort_with_title_first(self, properties: dict[str, DataSourceProperty]) -> list[tuple[str, DataSourceProperty]]:
+        return sorted(properties.items(), key=lambda item: (self._is_not_title_property(item[1]), item[0]))
+
+    def _is_not_title_property(self, prop: DataSourceProperty) -> bool:
+        return prop.type != PropertyType.TITLE
+
+    async def _format_single_property(self, index: int, name: str, prop: DataSourceProperty) -> list[str]:
+        lines = [f"{index}. - Property Name: '{name}'", f"   - Property Type: '{prop.type.value}'"]
+
+        lines.extend(await self._property_formatter.format_property(prop))
+        lines.append("")
+
+        return lines

notionary/data_source/schemas.py

@@ -0,0 +1,27 @@
+from pydantic import BaseModel
+
+from notionary.blocks.rich_text.models import RichText
+from notionary.data_source.properties.schemas import DiscriminatedDataSourceProperty
+from notionary.page.schemas import NotionPageDto
+from notionary.shared.entity.schemas import EntityResponseDto, NotionEntityUpdateDto
+from notionary.shared.models.parent import Parent
+
+
+class UpdateDataSourceDto(NotionEntityUpdateDto):
+    title: list[RichText]
+    description: list[RichText]
+    archived: bool
+
+
+class QueryDataSourceResponse(BaseModel):
+    results: list[NotionPageDto]
+    next_cursor: str | None = None
+    has_more: bool
+
+
+class DataSourceDto(EntityResponseDto):
+    database_parent: Parent
+    title: list[RichText]
+    description: list[RichText]
+    archived: bool
+    properties: dict[str, DiscriminatedDataSourceProperty]