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

notionary/page/properties/models.py

@@ -0,0 +1,308 @@
+from enum import StrEnum
+from typing import Annotated, Any, Literal, TypeVar
+
+from pydantic import BaseModel, Field
+
+from notionary.blocks.rich_text.models import RichText
+from notionary.shared.properties.type import PropertyType
+from notionary.shared.typings import JsonDict
+from notionary.user.schemas import PersonUserResponseDto, UserResponseDto
+
+# ============================================================================
+# Base Models
+# ============================================================================
+
+
+class PageProperty(BaseModel):
+    id: str
+    type: str
+
+
+class StatusOption(BaseModel):
+    id: str
+    name: str
+
+
+class SelectOption(BaseModel):
+    id: str | None = None
+    name: str
+
+
+class RelationItem(BaseModel):
+    id: str
+
+
+class DateValue(BaseModel):
+    start: str
+    end: str | None = None
+    time_zone: str | None = None
+
+
+# ============================================================================
+# File Models
+# ============================================================================
+
+
+class FileType(StrEnum):
+    EXTERNAL = "external"
+    FILE = "file"
+
+
+class ExternalFile(BaseModel):
+    """External file hosted outside of Notion."""
+
+    url: str
+
+
+class NotionFile(BaseModel):
+    """File uploaded to Notion with expiration."""
+
+    url: str
+    expiry_time: str
+
+
+class FileObject(BaseModel):
+    """File object can be external or uploaded to Notion."""
+
+    name: str
+    type: FileType
+    external: ExternalFile | None = None
+    file: NotionFile | None = None
+
+
+# ============================================================================
+# Formula Models
+# ============================================================================
+
+
+class FormulaValueType(StrEnum):
+    BOOLEAN = "boolean"
+    DATE = "date"
+    NUMBER = "number"
+    STRING = "string"
+
+
+class FormulaValue(BaseModel):
+    type: FormulaValueType
+    boolean: bool | None = None
+    date: DateValue | None = None
+    number: float | None = None
+    string: str | None = None
+
+
+# ============================================================================
+# Rollup Models
+# ============================================================================
+
+
+class RollupValueType(StrEnum):
+    NUMBER = "number"
+    DATE = "date"
+    ARRAY = "array"
+    INCOMPLETE = "incomplete"
+    UNSUPPORTED = "unsupported"
+
+
+class RollupValue(BaseModel):
+    type: RollupValueType
+    function: str  # e.g., "sum", "count", "average", "max", "min", etc.
+    number: float | None = None
+    date: DateValue | None = None
+    array: list[Any] | None = None
+
+
+# ============================================================================
+# Unique ID Models
+# ============================================================================
+
+
+class UniqueIdValue(BaseModel):
+    number: int  # Auto-incrementing count
+    prefix: str | None = None  # Optional prefix like "RL"
+
+
+# ============================================================================
+# Verification Models
+# ============================================================================
+
+
+class VerificationState(StrEnum):
+    VERIFIED = "verified"
+    UNVERIFIED = "unverified"
+
+
+class VerificationValue(BaseModel):
+    state: VerificationState
+    verified_by: UserResponseDto | None = None
+    date: DateValue | None = None  # start = verification date, end = expiration
+
+
+# ============================================================================
+# Page Property Classes
+# ============================================================================
+
+
+class PageStatusProperty(PageProperty):
+    type: Literal[PropertyType.STATUS] = PropertyType.STATUS
+    status: StatusOption | None = None
+    options: list[StatusOption] = Field(default_factory=list)
+
+    @property
+    def option_names(self) -> list[str]:
+        return [option.name for option in self.options]
+
+
+class PageRelationProperty(PageProperty):
+    type: Literal[PropertyType.RELATION] = PropertyType.RELATION
+    relation: list[RelationItem] = Field(default_factory=list)
+    has_more: bool = False
+
+
+class PageURLProperty(PageProperty):
+    type: Literal[PropertyType.URL] = PropertyType.URL
+    url: str | None = None
+
+
+class PageRichTextProperty(PageProperty):
+    type: Literal[PropertyType.RICH_TEXT] = PropertyType.RICH_TEXT
+    rich_text: list[RichText] = Field(default_factory=list)
+
+
+class PageMultiSelectProperty(PageProperty):
+    type: Literal[PropertyType.MULTI_SELECT] = PropertyType.MULTI_SELECT
+    multi_select: list[SelectOption] = Field(default_factory=list)
+    options: list[SelectOption] = Field(default_factory=list)
+
+    @property
+    def option_names(self) -> list[str]:
+        return [option.name for option in self.options]
+
+
+class PageSelectProperty(PageProperty):
+    type: Literal[PropertyType.SELECT] = PropertyType.SELECT
+    select: SelectOption | None = None
+    options: list[SelectOption] = Field(default_factory=list)
+
+    @property
+    def option_names(self) -> list[str]:
+        return [option.name for option in self.options]
+
+
+class PagePeopleProperty(PageProperty):
+    type: Literal[PropertyType.PEOPLE] = PropertyType.PEOPLE
+    people: list[PersonUserResponseDto] = Field(default_factory=list)
+
+
+class PageDateProperty(PageProperty):
+    type: Literal[PropertyType.DATE] = PropertyType.DATE
+    date: DateValue | None = None
+
+
+class PageTitleProperty(PageProperty):
+    type: Literal[PropertyType.TITLE] = PropertyType.TITLE
+    title: list[RichText] = Field(default_factory=list)
+
+
+class PageNumberProperty(PageProperty):
+    type: Literal[PropertyType.NUMBER] = PropertyType.NUMBER
+    number: float | None = None
+
+
+class PageCheckboxProperty(PageProperty):
+    type: Literal[PropertyType.CHECKBOX] = PropertyType.CHECKBOX
+    checkbox: bool = False
+
+
+class PageEmailProperty(PageProperty):
+    type: Literal[PropertyType.EMAIL] = PropertyType.EMAIL
+    email: str | None = None
+
+
+class PagePhoneNumberProperty(PageProperty):
+    type: Literal[PropertyType.PHONE_NUMBER] = PropertyType.PHONE_NUMBER
+    phone_number: str | None = None
+
+
+class PageCreatedTimeProperty(PageProperty):
+    type: Literal[PropertyType.CREATED_TIME] = PropertyType.CREATED_TIME
+    created_time: str  # ISO 8601 datetime - read-only
+
+
+class PageLastEditedTimeProperty(PageProperty):
+    type: Literal[PropertyType.LAST_EDITED_TIME] = PropertyType.LAST_EDITED_TIME
+    last_edited_time: str  # ISO 8601 datetime - read-only
+
+
+class PageCreatedByProperty(PageProperty):
+    type: Literal[PropertyType.CREATED_BY] = PropertyType.CREATED_BY
+    created_by: UserResponseDto  # User object - read-only
+
+
+class PageLastEditedByProperty(PageProperty):
+    type: Literal[PropertyType.LAST_EDITED_BY] = PropertyType.LAST_EDITED_BY
+    last_edited_by: UserResponseDto  # User object - read-only
+
+
+class PageFilesProperty(PageProperty):
+    type: Literal[PropertyType.FILES] = PropertyType.FILES
+    files: list[FileObject] = Field(default_factory=list)
+
+
+class PageFormulaProperty(PageProperty):
+    type: Literal[PropertyType.FORMULA] = PropertyType.FORMULA
+    formula: FormulaValue
+
+
+class PageRollupProperty(PageProperty):
+    type: Literal[PropertyType.ROLLUP] = PropertyType.ROLLUP
+    rollup: RollupValue
+
+
+class PageUniqueIdProperty(PageProperty):
+    type: Literal[PropertyType.UNIQUE_ID] = PropertyType.UNIQUE_ID
+    unique_id: UniqueIdValue
+
+
+class PageVerificationProperty(PageProperty):
+    type: Literal[PropertyType.VERIFICATION] = PropertyType.VERIFICATION
+    verification: VerificationValue
+
+
+class PageButtonProperty(PageProperty):
+    type: Literal[PropertyType.BUTTON] = PropertyType.BUTTON
+    button: JsonDict = Field(default_factory=dict)
+
+
+# ============================================================================
+# Discriminated Union
+# ============================================================================
+
+
+DiscriminatedPageProperty = Annotated[
+    PageStatusProperty
+    | PageRelationProperty
+    | PageURLProperty
+    | PageRichTextProperty
+    | PageMultiSelectProperty
+    | PageSelectProperty
+    | PagePeopleProperty
+    | PageDateProperty
+    | PageTitleProperty
+    | PageNumberProperty
+    | PageCheckboxProperty
+    | PageEmailProperty
+    | PagePhoneNumberProperty
+    | PageCreatedTimeProperty
+    | PageLastEditedTimeProperty
+    | PageCreatedByProperty
+    | PageLastEditedByProperty
+    | PageFilesProperty
+    | PageFormulaProperty
+    | PageRollupProperty
+    | PageUniqueIdProperty
+    | PageVerificationProperty
+    | PageButtonProperty,
+    Field(discriminator="type"),
+]
+
+PagePropertyT = TypeVar("PagePropertyT", bound=PageProperty)

notionary/page/properties/service.py

@@ -0,0 +1,261 @@
+from __future__ import annotations
+
+import asyncio
+from typing import TYPE_CHECKING, Never
+
+from notionary.blocks.rich_text.rich_text_markdown_converter import convert_rich_text_to_markdown
+from notionary.exceptions.properties import (
+    AccessPagePropertyWithoutDataSourceError,
+    PagePropertyNotFoundError,
+    PagePropertyTypeError,
+)
+from notionary.page.properties.client import PagePropertyHttpClient
+from notionary.page.properties.models import (
+    PageCheckboxProperty,
+    PageCreatedTimeProperty,
+    PageDateProperty,
+    PageEmailProperty,
+    PageMultiSelectProperty,
+    PageNumberProperty,
+    PagePeopleProperty,
+    PagePhoneNumberProperty,
+    PageProperty,
+    PagePropertyT,
+    PageRelationProperty,
+    PageRichTextProperty,
+    PageSelectProperty,
+    PageStatusProperty,
+    PageTitleProperty,
+    PageURLProperty,
+)
+from notionary.shared.models.parent import ParentType
+
+if TYPE_CHECKING:
+    from notionary import NotionDataSource
+
+
+class PagePropertyHandler:
+    def __init__(
+        self,
+        properties: dict[str, PageProperty],
+        parent_type: ParentType,
+        page_url: str,
+        page_property_http_client: PagePropertyHttpClient,
+        parent_data_source: str,
+    ) -> None:
+        self._properties = properties
+        self._parent_type = parent_type
+        self._page_url = page_url
+        self._property_http_client = page_property_http_client
+        self._parent_data_source_id = parent_data_source
+        self._parent_data_source: NotionDataSource | None = None
+        self._data_source_loaded = False
+
+    # =========================================================================
+    # Reader Methods
+    # =========================================================================
+
+    def get_value_of_status_property(self, name: str) -> str | None:
+        status_property = self._get_typed_property_or_raise(name, PageStatusProperty)
+        return status_property.status.name if status_property.status else None
+
+    def get_value_of_select_property(self, name: str) -> str | None:
+        select_property = self._get_typed_property_or_raise(name, PageSelectProperty)
+        return select_property.select.name if select_property.select else None
+
+    async def get_value_of_title_property(self, name: str) -> str:
+        title_property = self._get_typed_property_or_raise(name, PageTitleProperty)
+        return await convert_rich_text_to_markdown(title_property.title)
+
+    def get_values_of_people_property(self, property_name: str) -> list[str]:
+        people_prop = self._get_typed_property_or_raise(property_name, PagePeopleProperty)
+        return [person.name for person in people_prop.people if person.name]
+
+    def get_value_of_created_time_property(self, name: str) -> str | None:
+        created_time_property = self._get_typed_property_or_raise(name, PageCreatedTimeProperty)
+        return created_time_property.created_time
+
+    async def get_values_of_relation_property(self, name: str) -> list[str]:
+        from notionary import NotionPage
+
+        relation_property = self._get_typed_property_or_raise(name, PageRelationProperty)
+        relation_page_ids = [rel.id for rel in relation_property.relation]
+        notion_pages = [await NotionPage.from_id(page_id) for page_id in relation_page_ids]
+        return [page.title for page in notion_pages if page]
+
+    def get_values_of_multiselect_property(self, name: str) -> list[str]:
+        multiselect_property = self._get_typed_property_or_raise(name, PageMultiSelectProperty)
+        return [option.name for option in multiselect_property.multi_select]
+
+    def get_value_of_url_property(self, name: str) -> str | None:
+        url_property = self._get_typed_property_or_raise(name, PageURLProperty)
+        return url_property.url
+
+    def get_value_of_number_property(self, name: str) -> float | None:
+        number_property = self._get_typed_property_or_raise(name, PageNumberProperty)
+        return number_property.number
+
+    def get_value_of_checkbox_property(self, name: str) -> bool:
+        checkbox_property = self._get_typed_property_or_raise(name, PageCheckboxProperty)
+        return checkbox_property.checkbox
+
+    def get_value_of_date_property(self, name: str) -> str | None:
+        date_property = self._get_typed_property_or_raise(name, PageDateProperty)
+        return date_property.date.start if date_property.date else None
+
+    async def get_value_of_rich_text_property(self, name: str) -> str:
+        rich_text_property = self._get_typed_property_or_raise(name, PageRichTextProperty)
+        return await convert_rich_text_to_markdown(rich_text_property.rich_text)
+
+    def get_value_of_email_property(self, name: str) -> str | None:
+        email_property = self._get_typed_property_or_raise(name, PageEmailProperty)
+        return email_property.email
+
+    def get_value_of_phone_number_property(self, name: str) -> str | None:
+        phone_property = self._get_typed_property_or_raise(name, PagePhoneNumberProperty)
+        return phone_property.phone_number
+
+    # =========================================================================
+    # Options Getters
+    # =========================================================================
+
+    async def get_select_options_by_property_name(self, property_name: str) -> list[str]:
+        data_source = await self._get_parent_data_source_or_raise()
+        return data_source.get_select_options_by_property_name(property_name)
+
+    async def get_multi_select_options_by_property_name(self, property_name: str) -> list[str]:
+        data_source = await self._get_parent_data_source_or_raise()
+        return data_source.get_multi_select_options_by_property_name(property_name)
+
+    async def get_status_options_by_property_name(self, property_name: str) -> list[str]:
+        data_source = await self._get_parent_data_source_or_raise()
+        return data_source.get_status_options_by_property_name(property_name)
+
+    async def get_relation_options_by_property_name(self, property_name: str) -> list[str]:
+        data_source = await self._get_parent_data_source_or_raise()
+        return await data_source.get_relation_options_by_property_name(property_name)
+
+    async def get_options_for_property_by_name(self, property_name: str) -> list[str]:
+        data_source = await self._get_parent_data_source_or_raise()
+        return await data_source.get_options_for_property_by_name(property_name)
+
+    async def get_schema_description(self, property_name: str) -> str:
+        data_source = await self._get_parent_data_source_or_raise()
+        return await data_source.get_schema_description(property_name)
+
+    # =========================================================================
+    # Writer Methods
+    # =========================================================================
+
+    async def set_title_property(self, property_name: str, title: str) -> None:
+        self._get_typed_property_or_raise(property_name, PageTitleProperty)
+        updated_page = await self._property_http_client.patch_title(property_name, title)
+        self._properties = updated_page.properties
+
+    async def set_rich_text_property(self, property_name: str, text: str) -> None:
+        self._get_typed_property_or_raise(property_name, PageRichTextProperty)
+        updated_page = await self._property_http_client.patch_rich_text_property(property_name, text)
+        self._properties = updated_page.properties
+
+    async def set_url_property(self, property_name: str, url: str) -> None:
+        self._get_typed_property_or_raise(property_name, PageURLProperty)
+        updated_page = await self._property_http_client.patch_url_property(property_name, url)
+        self._properties = updated_page.properties
+
+    async def set_email_property(self, property_name: str, email: str) -> None:
+        self._get_typed_property_or_raise(property_name, PageEmailProperty)
+        updated_page = await self._property_http_client.patch_email_property(property_name, email)
+        self._properties = updated_page.properties
+
+    async def set_phone_number_property(self, property_name: str, phone_number: str) -> None:
+        self._get_typed_property_or_raise(property_name, PagePhoneNumberProperty)
+        updated_page = await self._property_http_client.patch_phone_property(property_name, phone_number)
+        self._properties = updated_page.properties
+
+    async def set_number_property(self, property_name: str, number: int | float) -> None:
+        self._get_typed_property_or_raise(property_name, PageNumberProperty)
+        updated_page = await self._property_http_client.patch_number_property(property_name, number)
+        self._properties = updated_page.properties
+
+    async def set_checkbox_property(self, property_name: str, checked: bool) -> None:
+        self._get_typed_property_or_raise(property_name, PageCheckboxProperty)
+        updated_page = await self._property_http_client.patch_checkbox_property(property_name, checked)
+        self._properties = updated_page.properties
+
+    async def set_date_property(self, property_name: str, date_value: str | dict) -> None:
+        self._get_typed_property_or_raise(property_name, PageDateProperty)
+        updated_page = await self._property_http_client.patch_date_property(property_name, date_value)
+        self._properties = updated_page.properties
+
+    async def set_select_property_by_option_name(self, property_name: str, option_name: str) -> None:
+        self._get_typed_property_or_raise(property_name, PageSelectProperty)
+        updated_page = await self._property_http_client.patch_select_property(property_name, option_name)
+        self._properties = updated_page.properties
+
+    async def set_multi_select_property_by_option_names(self, property_name: str, option_names: list[str]) -> None:
+        self._get_typed_property_or_raise(property_name, PageMultiSelectProperty)
+        updated_page = await self._property_http_client.patch_multi_select_property(property_name, option_names)
+        self._properties = updated_page.properties
+
+    async def set_status_property_by_option_name(self, property_name: str, status: str) -> None:
+        self._get_typed_property_or_raise(property_name, PageStatusProperty)
+        updated_page = await self._property_http_client.patch_status_property(property_name, status)
+        self._properties = updated_page.properties
+
+    async def set_relation_property_by_page_titles(self, property_name: str, page_titles: list[str]) -> None:
+        self._get_typed_property_or_raise(property_name, PageRelationProperty)
+        relation_ids = await self._convert_page_titles_to_ids(page_titles)
+        updated_page = await self._property_http_client.patch_relation_property(property_name, relation_ids)
+        self._properties = updated_page.properties
+
+    async def _ensure_data_source_loaded(self) -> None:
+        from notionary import NotionDataSource
+
+        if self._data_source_loaded:
+            return
+
+        self._parent_data_source = (
+            await NotionDataSource.from_id(self._parent_data_source_id) if self._parent_data_source_id else None
+        )
+        self._data_source_loaded = True
+
+    async def _get_parent_data_source_or_raise(self) -> NotionDataSource:
+        await self._ensure_data_source_loaded()
+
+        if not self._parent_data_source:
+            raise AccessPagePropertyWithoutDataSourceError(self._parent_type)
+        return self._parent_data_source
+
+    def _get_typed_property_or_raise(self, name: str, property_type: type[PagePropertyT]) -> PagePropertyT:
+        prop = self._properties.get(name)
+
+        if prop is None:
+            self._handle_prop_not_found(name)
+
+        if not isinstance(prop, property_type):
+            self._handle_incorrect_type(name, type(prop))
+
+        return prop
+
+    def _handle_prop_not_found(self, name: str) -> Never:
+        raise PagePropertyNotFoundError(
+            property_name=name,
+            page_url=self._page_url,
+            available_properties=list(self._properties.keys()),
+        )
+
+    def _handle_incorrect_type(self, property_name: str, actual_type: type) -> Never:
+        raise PagePropertyTypeError(
+            property_name=property_name,
+            actual_type=actual_type.__name__,
+        )
+
+    async def _convert_page_titles_to_ids(self, page_titles: list[str]) -> list[str]:
+        from notionary import NotionPage
+
+        if not page_titles:
+            return []
+
+        pages = await asyncio.gather(*[NotionPage.from_title(title=title) for title in page_titles])
+
+        return [page.id for page in pages if page]

notionary/page/schemas.py

@@ -0,0 +1,13 @@
+from pydantic import BaseModel
+
+from notionary.page.properties.models import DiscriminatedPageProperty
+from notionary.shared.entity.schemas import EntityResponseDto
+
+
+class NotionPageDto(EntityResponseDto):
+    archived: bool
+    properties: dict[str, DiscriminatedPageProperty]
+
+
+class PgePropertiesUpdateDto(BaseModel):
+    properties: dict[str, DiscriminatedPageProperty]