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

notionary/data_source/query/builder.py

@@ -1,7 +1,7 @@
 from collections.abc import Callable
 from typing import Self
 
-from notionary.data_source.properties.models import DataSourceProperty
+from notionary.data_source.properties.schemas import DataSourceProperty
 from notionary.data_source.query.schema import (
     ArrayOperator,
     BooleanOperator,
@@ -24,7 +24,7 @@ from notionary.data_source.query.schema import (
     TimestampSort,
     TimestampType,
 )
-from notionary.data_source.query.validator import OperatorValidator
+from notionary.data_source.query.validator import QueryValidator
 from notionary.exceptions.data_source.properties import DataSourcePropertyNotFound
 from notionary.utils.date import parse_date
 
@@ -33,11 +33,11 @@ class DataSourceQueryBuilder:
     def __init__(
         self,
         properties: dict[str, DataSourceProperty],
-        operator_validator: OperatorValidator | None = None,
+        query_validator: QueryValidator | None = None,
         date_parser: Callable[[str], str] = parse_date,
     ) -> None:
         self._properties = properties
-        self._operator_validator = operator_validator or OperatorValidator()
+        self._query_validator = query_validator or QueryValidator()
         self._date_parser = date_parser
 
         self._filters: list[InternalFilterCondition] = []
@@ -45,6 +45,8 @@ class DataSourceQueryBuilder:
         self._current_property: str | None = None
         self._negate_next = False
         self._or_group: list[FilterCondition] | None = None
+        self._page_size: int | None = None
+        self._total_results_limit: int | None = None
 
     def where(self, property_name: str) -> Self:
         self._finalize_current_or_group()
@@ -164,27 +166,53 @@ class DataSourceQueryBuilder:
         self._sorts.append(sort)
         return self
 
-    def order_by_ascending(self, property_name: str) -> Self:
+    def order_by_property_name_ascending(self, property_name: str) -> Self:
         return self.order_by(property_name, SortDirection.ASCENDING)
 
-    def order_by_descending(self, property_name: str) -> Self:
+    def order_by_property_name_descending(self, property_name: str) -> Self:
         return self.order_by(property_name, SortDirection.DESCENDING)
 
-    def order_by_created_time(self, direction: SortDirection = SortDirection.DESCENDING) -> Self:
+    def order_by_created_time_ascending(self) -> Self:
+        return self._order_by_created_time(SortDirection.ASCENDING)
+
+    def order_by_created_time_descending(self) -> Self:
+        return self._order_by_created_time(SortDirection.DESCENDING)
+
+    def _order_by_created_time(self, direction: SortDirection = SortDirection.DESCENDING) -> Self:
         sort = TimestampSort(timestamp=TimestampType.CREATED_TIME, direction=direction)
         self._sorts.append(sort)
         return self
 
-    def order_by_last_edited_time(self, direction: SortDirection = SortDirection.DESCENDING) -> Self:
+    def order_by_last_edited_time_ascending(self) -> Self:
+        return self._order_by_last_edited_time(SortDirection.ASCENDING)
+
+    def order_by_last_edited_time_descending(self) -> Self:
+        return self._order_by_last_edited_time(SortDirection.DESCENDING)
+
+    def _order_by_last_edited_time(self, direction: SortDirection = SortDirection.DESCENDING) -> Self:
         sort = TimestampSort(timestamp=TimestampType.LAST_EDITED_TIME, direction=direction)
         self._sorts.append(sort)
         return self
 
+    def total_results_limit(self, total_result_limit: int) -> Self:
+        if total_result_limit < 1:
+            raise ValueError("Limit must be at least 1")
+        self._total_results_limit = total_result_limit
+        return self
+
+    def page_size(self, page_size: int) -> Self:
+        if page_size < 1:
+            raise ValueError("Page size must be at least 1")
+        self._page_size = page_size
+        return self
+
     def build(self) -> DataSourceQueryParams:
         self._finalize_current_or_group()
         notion_filter = self._create_notion_filter_if_needed()
         sorts = self._create_sorts_if_needed()
-        return DataSourceQueryParams(filter=notion_filter, sorts=sorts)
+        return DataSourceQueryParams(
+            filter=notion_filter, sorts=sorts, page_size=self._page_size, total_results_limit=self._total_results_limit
+        )
 
     def _select_property_without_negation(self, property_name: str) -> None:
         self._current_property = property_name
@@ -273,7 +301,7 @@ class DataSourceQueryBuilder:
 
         property_obj = self._properties.get(self._current_property)
         if property_obj:
-            self._operator_validator.validate_operator_for_property(self._current_property, property_obj, operator)
+            self._query_validator.validate_operator_for_property(self._current_property, property_obj, operator)
         return self
 
     def _ensure_property_is_selected(self) -> None:

notionary/data_source/query/schema.py

@@ -1,11 +1,12 @@
 from __future__ import annotations
 
 from enum import StrEnum
-from typing import Any, Self
+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):
@@ -46,7 +47,7 @@ class BooleanOperator(StrEnum):
     IS_FALSE = "is_false"
 
 
-class StatusOperator(StrEnum):
+class SelectOperator(StrEnum):
     EQUALS = "equals"
     DOES_NOT_EQUAL = "does_not_equal"
     IS_EMPTY = "is_empty"
@@ -70,10 +71,6 @@ class ArrayOperator(StrEnum):
     IS_NOT_EMPTY = "is_not_empty"
 
 
-RelationOperator = ArrayOperator
-PeopleOperator = ArrayOperator
-
-
 class LogicalOperator(StrEnum):
     AND = "and"
     OR = "or"
@@ -246,7 +243,7 @@ class PropertyFilter(BaseModel):
         return self
 
     @model_serializer
-    def serialize_model(self) -> dict[str, Any]:
+    def serialize_model(self) -> JsonDict:
         property_type_str = self.property_type.value
         operator_str = self.operator.value
         filter_value = self.value
@@ -266,7 +263,7 @@ class CompoundFilter(BaseModel):
     filters: list[PropertyFilter | CompoundFilter]
 
     @model_serializer
-    def serialize_model(self) -> dict[str, Any]:
+    def serialize_model(self) -> JsonDict:
         operator_str = self.operator.value
         return {operator_str: [f.model_dump() for f in self.filters]}
 
@@ -290,10 +287,13 @@ type NotionSort = PropertySort | TimestampSort
 class DataSourceQueryParams(BaseModel):
     filter: NotionFilter | None = None
     sorts: list[NotionSort] | None = None
+    page_size: int | None = None
+
+    total_results_limit: int | None = None
 
     @model_serializer
-    def serialize_model(self) -> dict[str, Any]:
-        result: dict[str, Any] = {}
+    def to_api_params(self) -> JsonDict:
+        result: JsonDict = {}
 
         if self.filter is not None:
             result["filter"] = self.filter.model_dump()
@@ -301,4 +301,7 @@ class DataSourceQueryParams(BaseModel):
         if self.sorts is not None and len(self.sorts) > 0:
             result["sorts"] = [sort.model_dump() for sort in self.sorts]
 
+        if self.page_size is not None:
+            result["page_size"] = self.page_size
+
         return result

notionary/data_source/query/validator.py

@@ -1,38 +1,38 @@
 from typing import ClassVar
 
-from notionary.data_source.properties.models import DataSourceProperty
+from notionary.data_source.properties.schemas import DataSourceProperty
 from notionary.data_source.query.schema import (
     ArrayOperator,
     BooleanOperator,
     DateOperator,
     NumberOperator,
     Operator,
-    StatusOperator,
+    SelectOperator,
     StringOperator,
 )
 from notionary.exceptions.data_source.builder import InvalidOperatorForPropertyType
 from notionary.shared.properties.type import PropertyType
 
 
-class OperatorValidator:
+class QueryValidator:
     _PROPERTY_TYPE_OPERATORS: ClassVar[dict[PropertyType, list[type[Operator]]]] = {
         PropertyType.TITLE: [StringOperator],
         PropertyType.RICH_TEXT: [StringOperator],
-        PropertyType.NUMBER: [NumberOperator],
-        PropertyType.SELECT: [StringOperator],
-        PropertyType.MULTI_SELECT: [ArrayOperator],
-        PropertyType.STATUS: [StatusOperator],
-        PropertyType.DATE: [DateOperator],
-        PropertyType.PEOPLE: [ArrayOperator],
-        PropertyType.CHECKBOX: [BooleanOperator],
         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.CREATED_BY: [ArrayOperator],
         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(

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

@@ -1,7 +1,7 @@
 from pydantic import BaseModel
 
 from notionary.blocks.rich_text.models import RichText
-from notionary.data_source.properties.models import DiscriminatedDataSourceProperty
+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