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

notionary/page/service.py

@@ -0,0 +1,225 @@
+from collections.abc import Callable
+from typing import Self
+
+from notionary.blocks.client import NotionBlockHttpClient
+from notionary.blocks.rich_text.rich_text_markdown_converter import convert_rich_text_to_markdown
+from notionary.comments.models import Comment
+from notionary.comments.service import CommentService
+from notionary.page.content.factory import PageContentServiceFactory
+from notionary.page.content.markdown.builder import MarkdownBuilder
+from notionary.page.content.service import PageContentService
+from notionary.page.page_http_client import NotionPageHttpClient
+from notionary.page.page_metadata_update_client import PageMetadataUpdateClient
+from notionary.page.properties.factory import PagePropertyHandlerFactory
+from notionary.page.properties.models import PageTitleProperty
+from notionary.page.properties.service import PagePropertyHandler
+from notionary.page.schemas import NotionPageDto
+from notionary.shared.entity.dto_parsers import (
+    extract_cover_image_url_from_dto,
+    extract_emoji_icon_from_dto,
+    extract_external_icon_url_from_dto,
+)
+from notionary.shared.entity.service import Entity
+from notionary.user.schemas import PartialUserDto
+from notionary.workspace.query.service import WorkspaceQueryService
+
+
+class NotionPage(Entity):
+    def __init__(
+        self,
+        id: str,
+        title: str,
+        created_time: str,
+        created_by: PartialUserDto,
+        last_edited_time: str,
+        last_edited_by: PartialUserDto,
+        url: str,
+        archived: bool,
+        in_trash: bool,
+        page_property_handler: PagePropertyHandler,
+        block_client: NotionBlockHttpClient,
+        comment_service: CommentService,
+        page_content_service: PageContentService,
+        metadata_update_client: PageMetadataUpdateClient,
+        public_url: str | None = None,
+        emoji_icon: str | None = None,
+        external_icon_url: str | None = None,
+        cover_image_url: str | 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._archived = archived
+        self._url = url
+        self._public_url = public_url
+
+        self._block_client = block_client
+        self._comment_service = comment_service
+        self._page_content_service = page_content_service
+        self.properties = page_property_handler
+        self._metadata_update_client = metadata_update_client
+
+    @classmethod
+    async def from_id(
+        cls,
+        page_id: str,
+        page_property_handler_factory: PagePropertyHandlerFactory | None = None,
+    ) -> Self:
+        factory = page_property_handler_factory or PagePropertyHandlerFactory()
+        response = await cls._fetch_page_dto(page_id)
+        return await cls._create_from_dto(response, factory)
+
+    @classmethod
+    async def from_title(
+        cls,
+        page_title: str,
+        search_service: WorkspaceQueryService | None = None,
+    ) -> Self:
+        service = search_service or WorkspaceQueryService()
+        return await service.find_page(page_title)
+
+    @classmethod
+    async def _fetch_page_dto(cls, page_id: str) -> NotionPageDto:
+        async with NotionPageHttpClient(page_id=page_id) as client:
+            return await client.get_page()
+
+    @classmethod
+    async def _create_from_dto(
+        cls,
+        response: NotionPageDto,
+        page_property_handler_factory: PagePropertyHandlerFactory,
+    ) -> Self:
+        title_task = cls._extract_title_from_dto(response)
+        page_property_handler = page_property_handler_factory.create_from_page_response(response)
+
+        title = await title_task
+
+        return cls._create_with_dependencies(
+            id=response.id,
+            title=title,
+            created_time=response.created_time,
+            created_by=response.created_by,
+            last_edited_time=response.last_edited_time,
+            last_edited_by=response.last_edited_by,
+            archived=response.archived,
+            in_trash=response.in_trash,
+            url=response.url,
+            page_property_handler=page_property_handler,
+            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),
+        )
+
+    @classmethod
+    def _create_with_dependencies(
+        cls,
+        id: str,
+        title: str,
+        created_time: str,
+        created_by: PartialUserDto,
+        last_edited_time: str,
+        last_edited_by: PartialUserDto,
+        url: str,
+        archived: bool,
+        in_trash: bool,
+        page_property_handler: PagePropertyHandler,
+        public_url: str | None = None,
+        emoji_icon: str | None = None,
+        external_icon_url: str | None = None,
+        cover_image_url: str | None = None,
+    ) -> Self:
+        block_client = NotionBlockHttpClient()
+        comment_service = CommentService()
+
+        page_content_service_factory = PageContentServiceFactory()
+        page_content_service = page_content_service_factory.create(page_id=id, block_client=block_client)
+
+        metadata_update_client = PageMetadataUpdateClient(page_id=id)
+
+        return cls(
+            id=id,
+            title=title,
+            created_time=created_time,
+            created_by=created_by,
+            last_edited_time=last_edited_time,
+            last_edited_by=last_edited_by,
+            url=url,
+            archived=archived,
+            in_trash=in_trash,
+            page_property_handler=page_property_handler,
+            block_client=block_client,
+            comment_service=comment_service,
+            page_content_service=page_content_service,
+            metadata_update_client=metadata_update_client,
+            public_url=public_url,
+            emoji_icon=emoji_icon,
+            external_icon_url=external_icon_url,
+            cover_image_url=cover_image_url,
+        )
+
+    @staticmethod
+    async def _extract_title_from_dto(response: NotionPageDto) -> str:
+        title_property = next(
+            (prop for prop in response.properties.values() if isinstance(prop, PageTitleProperty)),
+            None,
+        )
+        rich_text_title = title_property.title if title_property else []
+        return await convert_rich_text_to_markdown(rich_text_title)
+
+    @property
+    def _entity_metadata_update_client(self) -> PageMetadataUpdateClient:
+        return self._metadata_update_client
+
+    @property
+    def title(self) -> str:
+        return self._title
+
+    @property
+    def url(self) -> str:
+        return self._url
+
+    @property
+    def markdown_builder() -> MarkdownBuilder:
+        return MarkdownBuilder()
+
+    async def get_comments(self) -> list[Comment]:
+        return await self._comment_service.list_all_comments_for_page(page_id=self._id)
+
+    async def post_top_level_comment(self, comment: str) -> None:
+        await self._comment_service.create_comment_on_page(page_id=self._id, text=comment)
+
+    async def post_reply_to_discussion(self, discussion_id: str, comment: str) -> None:
+        await self._comment_service.reply_to_discussion_by_id(discussion_id=discussion_id, text=comment)
+
+    async def set_title(self, title: str) -> None:
+        await self.properties.set_title_property(title)
+        self._title = title
+
+    async def append_markdown(
+        self,
+        content: (str | Callable[[MarkdownBuilder], MarkdownBuilder]),
+    ) -> None:
+        await self._page_content_service.append_markdown(content=content)
+
+    async def replace_content(
+        self,
+        content: (str | Callable[[MarkdownBuilder], MarkdownBuilder]),
+    ) -> None:
+        await self._page_content_service.clear()
+        await self._page_content_service.append_markdown(content=content)
+
+    async def clear_page_content(self) -> None:
+        await self._page_content_service.clear()
+
+    async def get_markdown_content(self) -> str:
+        return await self._page_content_service.get_as_markdown()

notionary/shared/entity/client.py

@@ -0,0 +1,29 @@
+from typing import TypeVar, override
+
+from notionary.http.client import NotionHttpClient
+from notionary.shared.entity.entity_metadata_update_client import EntityMetadataUpdateClient
+from notionary.shared.entity.schemas import EntityResponseDto, NotionEntityUpdateDto
+
+ResponseType = TypeVar("ResponseType", bound=EntityResponseDto)
+
+
+class GenericEntityMetadataUpdateClient(NotionHttpClient, EntityMetadataUpdateClient):
+    def __init__(
+        self,
+        entity_id: str,
+        path_segment: str,
+        response_dto_class: type[ResponseType],
+        timeout: int = 30,
+    ) -> None:
+        super().__init__(timeout)
+        self._entity_id = entity_id
+        self._path_segment = path_segment
+        self._response_dto_class = response_dto_class
+
+    @override
+    async def patch_metadata(self, updated_data: NotionEntityUpdateDto) -> ResponseType:
+        updated_data_dict = updated_data.model_dump(exclude_unset=True, exclude_none=True)
+        url = f"{self._path_segment}/{self._entity_id}"
+
+        response_dict = await self.patch(url, data=updated_data_dict)
+        return self._response_dto_class.model_validate(response_dict)

notionary/shared/entity/dto_parsers.py

@@ -0,0 +1,53 @@
+from typing import cast
+
+from notionary.blocks.rich_text.rich_text_markdown_converter import RichTextToMarkdownConverter
+from notionary.shared.entity.schemas import Describable, EntityResponseDto, Titled
+from notionary.shared.models.cover import CoverType
+from notionary.shared.models.icon import IconType
+from notionary.shared.models.parent import DatabaseParent, DataSourceParent, ParentType
+
+
+def extract_emoji_icon_from_dto(entity_dto: EntityResponseDto) -> str | None:
+    if not entity_dto.icon or entity_dto.icon.type != IconType.EMOJI:
+        return None
+    return entity_dto.icon.emoji
+
+
+def extract_external_icon_url_from_dto(entity_dto: EntityResponseDto) -> str | None:
+    if not entity_dto.icon or entity_dto.icon.type != IconType.EXTERNAL:
+        return None
+    return entity_dto.icon.external.url if entity_dto.icon.external else None
+
+
+def extract_cover_image_url_from_dto(entity_dto: EntityResponseDto) -> str | None:
+    if not entity_dto.cover or entity_dto.cover.type != CoverType.EXTERNAL:
+        return None
+    return entity_dto.cover.external.url if entity_dto.cover.external else None
+
+
+def extract_database_id(entity_dto: EntityResponseDto) -> str | None:
+    if entity_dto.parent.type == ParentType.DATA_SOURCE_ID:
+        data_source_parent = cast(DataSourceParent, entity_dto.parent)
+        return data_source_parent.database_id if data_source_parent else None
+
+    if entity_dto.parent.type == ParentType.DATABASE_ID:
+        database_parent = cast(DatabaseParent, entity_dto.parent)
+        return database_parent.database_id if database_parent else None
+
+    return None
+
+
+async def extract_title(
+    entity: Titled,
+    rich_text_converter: RichTextToMarkdownConverter,
+) -> str:
+    return await rich_text_converter.to_markdown(entity.title)
+
+
+async def extract_description(
+    entity: Describable,
+    rich_text_converter: RichTextToMarkdownConverter,
+) -> str | None:
+    if not entity.description:
+        return None
+    return await rich_text_converter.to_markdown(entity.description)

notionary/shared/entity/entity_metadata_update_client.py

@@ -0,0 +1,41 @@
+from abc import ABC, abstractmethod
+
+from notionary.shared.entity.schemas import EntityResponseDto, NotionEntityUpdateDto
+from notionary.shared.models.cover import NotionCover
+from notionary.shared.models.icon import EmojiIcon, ExternalIcon
+
+
+class EntityMetadataUpdateClient(ABC):
+    @abstractmethod
+    async def patch_metadata(self, updated_data: NotionEntityUpdateDto) -> EntityResponseDto: ...
+
+    async def patch_emoji_icon(self, emoji: str) -> EntityResponseDto:
+        icon = EmojiIcon(emoji=emoji)
+        update_dto = NotionEntityUpdateDto(icon=icon)
+        return await self.patch_metadata(update_dto)
+
+    async def patch_external_icon(self, icon_url: str) -> EntityResponseDto:
+        icon = ExternalIcon.from_url(icon_url)
+        update_dto = NotionEntityUpdateDto(icon=icon)
+        return await self.patch_metadata(update_dto)
+
+    async def remove_icon(self) -> None:
+        update_dto = NotionEntityUpdateDto(icon=None)
+        return await self.patch_metadata(update_dto)
+
+    async def patch_external_cover(self, cover_url: str) -> EntityResponseDto:
+        cover = NotionCover.from_url(cover_url)
+        update_dto = NotionEntityUpdateDto(cover=cover)
+        return await self.patch_metadata(update_dto)
+
+    async def remove_cover(self) -> None:
+        update_dto = NotionEntityUpdateDto(cover=None)
+        return await self.patch_metadata(update_dto)
+
+    async def move_to_trash(self) -> EntityResponseDto:
+        update_dto = NotionEntityUpdateDto(in_trash=True)
+        return await self.patch_metadata(update_dto)
+
+    async def restore_from_trash(self) -> EntityResponseDto:
+        update_dto = NotionEntityUpdateDto(in_trash=False)
+        return await self.patch_metadata(update_dto)

notionary/shared/entity/schemas.py

@@ -0,0 +1,45 @@
+from enum import StrEnum
+from typing import Protocol
+
+from pydantic import BaseModel
+
+from notionary.blocks.rich_text.models import RichText
+from notionary.shared.models.cover import NotionCover
+from notionary.shared.models.icon import Icon
+from notionary.shared.models.parent import Parent
+from notionary.user.schemas import PartialUserDto
+
+
+class EntityWorkspaceQueryObjectType(StrEnum):
+    PAGE = "page"
+    DATA_SOURCE = "data_source"
+    DATABASE = "database"
+
+
+class EntityResponseDto(BaseModel):
+    object: EntityWorkspaceQueryObjectType
+    id: str
+    created_time: str
+    created_by: PartialUserDto
+    last_edited_time: str
+    last_edited_by: PartialUserDto
+    cover: NotionCover | None = None
+    icon: Icon | None = None
+    parent: Parent
+    in_trash: bool
+    url: str
+    public_url: str | None = None
+
+
+class NotionEntityUpdateDto(BaseModel):
+    icon: Icon | None = None
+    cover: NotionCover | None = None
+    in_trash: bool | None = None
+
+
+class Titled(Protocol):
+    title: list[RichText]
+
+
+class Describable(Protocol):
+    description: list[RichText] | None

notionary/shared/entity/service.py

@@ -0,0 +1,171 @@
+from __future__ import annotations
+
+import random
+from abc import ABC, abstractmethod
+from collections.abc import Sequence
+from typing import TYPE_CHECKING, Self
+
+from notionary.shared.entity.entity_metadata_update_client import EntityMetadataUpdateClient
+from notionary.user.schemas import PartialUserDto
+from notionary.user.service import UserService
+from notionary.utils.mixins.logging import LoggingMixin
+from notionary.utils.uuid_utils import extract_uuid
+
+if TYPE_CHECKING:
+    from notionary.user.base import BaseUser
+
+
+class Entity(LoggingMixin, ABC):
+    def __init__(
+        self,
+        id: str,
+        created_time: str,
+        created_by: PartialUserDto,
+        last_edited_time: str,
+        last_edited_by: PartialUserDto,
+        in_trash: bool,
+        emoji_icon: str | None = None,
+        external_icon_url: str | None = None,
+        cover_image_url: str | None = None,
+        user_service: UserService | None = None,
+    ) -> None:
+        self._id = id
+        self._created_time = created_time
+        self._created_by = created_by
+        self._last_edited_time = last_edited_time
+        self._last_edited_by = last_edited_by
+        self._emoji_icon = emoji_icon
+        self._external_icon_url = external_icon_url
+        self._cover_image_url = cover_image_url
+        self._in_trash = in_trash
+        self._user_service = user_service or UserService()
+
+    @classmethod
+    @abstractmethod
+    async def from_id(cls, id: str) -> Self:
+        pass
+
+    @classmethod
+    @abstractmethod
+    async def from_title(cls, title: str) -> Self:
+        pass
+
+    @classmethod
+    async def from_url(cls, url: str) -> Self:
+        entity_id = extract_uuid(url)
+        if not entity_id:
+            raise ValueError(f"Could not extract entity ID from URL: {url}")
+        return await cls.from_id(entity_id)
+
+    @property
+    @abstractmethod
+    def _entity_metadata_update_client(self) -> EntityMetadataUpdateClient:
+        # functionality for updating properties like title, icon, cover, archive status depends on interface for template like implementation
+        # has to be implementated by inheritants to correctly use the methods below
+        ...
+
+    @property
+    def id(self) -> str:
+        return self._id
+
+    @property
+    def created_time(self) -> str:
+        return self._created_time
+
+    @property
+    def last_edited_time(self) -> str:
+        return self._last_edited_time
+
+    @property
+    def in_trash(self) -> bool:
+        return self._in_trash
+
+    @property
+    def emoji_icon(self) -> str | None:
+        return self._emoji_icon
+
+    @property
+    def external_icon_url(self) -> str | None:
+        return self._external_icon_url
+
+    @property
+    def cover_image_url(self) -> str | None:
+        return self._cover_image_url
+
+    @property
+    def created_by(self) -> PartialUserDto:
+        return self._created_by
+
+    @property
+    def last_edited_by(self) -> PartialUserDto:
+        return self._last_edited_by
+
+    async def get_created_by_user(self) -> BaseUser | None:
+        return await self._user_service.get_user_by_id(self._created_by.id)
+
+    async def get_last_edited_by_user(self) -> BaseUser | None:
+        return await self._user_service.get_user_by_id(self._last_edited_by.id)
+
+    async def set_emoji_icon(self, emoji: str) -> None:
+        entity_response = await self._entity_metadata_update_client.patch_emoji_icon(emoji)
+        self._emoji_icon = entity_response.icon.emoji if entity_response.icon else None
+        self._external_icon_url = None
+
+    async def set_external_icon(self, icon_url: str) -> None:
+        entity_response = await self._entity_metadata_update_client.patch_external_icon(icon_url)
+        self._emoji_icon = None
+        self._external_icon_url = (
+            entity_response.icon.external.url if entity_response.icon and entity_response.icon.external else None
+        )
+
+    async def remove_icon(self) -> None:
+        await self._entity_metadata_update_client.remove_icon()
+        self._emoji_icon = None
+        self._external_icon_url = None
+
+    async def set_cover_image_by_url(self, image_url: str) -> None:
+        entity_response = await self._entity_metadata_update_client.patch_external_cover(image_url)
+        self._cover_image_url = (
+            entity_response.cover.external.url if entity_response.cover and entity_response.cover.external else None
+        )
+
+    async def set_random_gradient_cover(self) -> None:
+        random_cover_url = self._get_random_gradient_cover()
+        await self.set_cover_image_by_url(random_cover_url)
+
+    async def remove_cover_image(self) -> None:
+        await self._entity_metadata_update_client.remove_cover()
+        self._cover_image_url = None
+
+    async def move_to_trash(self) -> None:
+        if self._in_trash:
+            self.logger.warning("Entity is already in trash.")
+            return
+
+        entity_response = await self._entity_metadata_update_client.move_to_trash()
+        self._in_trash = entity_response.in_trash
+
+    async def restore_from_trash(self) -> None:
+        if not self._in_trash:
+            self.logger.warning("Entity is not in trash.")
+            return
+
+        entity_response = await self._entity_metadata_update_client.restore_from_trash()
+        self._in_trash = entity_response.in_trash
+
+    def __repr__(self) -> str:
+        attrs = []
+        for key, value in self.__dict__.items():
+            if key.startswith("_") and not key.startswith("__"):
+                attr_name = key[1:]
+                attrs.append(f"{attr_name}={value!r}")
+
+        attrs_str = ", ".join(attrs)
+        return f"{self.__class__.__name__}({attrs_str})"
+
+    def _get_random_gradient_cover(self) -> str:
+        DEFAULT_NOTION_COVERS: Sequence[str] = [
+            f"https://www.notion.so/images/page-cover/gradients_{i}.png" for i in range(1, 10)
+        ]
+
+        return random.choice(DEFAULT_NOTION_COVERS)

notionary/shared/models/cover.py

@@ -0,0 +1,20 @@
+from enum import StrEnum
+from typing import Literal, Self
+
+from pydantic import BaseModel
+
+from notionary.shared.models.file import ExternalFile
+
+
+class CoverType(StrEnum):
+    EXTERNAL = "external"
+    FILE = "file"
+
+
+class NotionCover(BaseModel):
+    type: Literal[CoverType.EXTERNAL, CoverType.FILE] = CoverType.EXTERNAL
+    external: ExternalFile | None = None
+
+    @classmethod
+    def from_url(cls, url: str) -> Self:
+        return cls(external=ExternalFile(url=url))

notionary/shared/models/file.py

@@ -0,0 +1,21 @@
+from enum import StrEnum
+from typing import Literal, Self
+
+from pydantic import BaseModel
+
+
+class FileType(StrEnum):
+    EXTERNAL = "external"
+
+
+class ExternalFile(BaseModel):
+    url: str
+
+
+class ExternalRessource(BaseModel):
+    type: Literal[FileType.EXTERNAL] = FileType.EXTERNAL
+    external: ExternalFile
+
+    @classmethod
+    def from_url(cls, url: str) -> Self:
+        return cls(external=ExternalFile(url=url))

notionary/shared/models/icon.py

@@ -0,0 +1,28 @@
+from enum import StrEnum
+from typing import Literal, Self
+
+from pydantic import BaseModel
+
+from notionary.shared.models.file import ExternalFile
+
+
+class IconType(StrEnum):
+    EMOJI = "emoji"
+    EXTERNAL = "external"
+
+
+class EmojiIcon(BaseModel):
+    type: Literal[IconType.EMOJI] = IconType.EMOJI
+    emoji: str
+
+
+class ExternalIcon(BaseModel):
+    type: Literal[IconType.EXTERNAL] = IconType.EXTERNAL
+    external: ExternalFile
+
+    @classmethod
+    def from_url(cls, url: str) -> Self:
+        return cls(external=ExternalFile(url=url))
+
+
+Icon = EmojiIcon | ExternalIcon

notionary/shared/models/parent.py

@@ -0,0 +1,41 @@
+from enum import StrEnum
+from typing import Literal
+
+from pydantic import BaseModel
+
+
+class ParentType(StrEnum):
+    DATABASE_ID = "database_id"
+    DATA_SOURCE_ID = "data_source_id"
+    PAGE_ID = "page_id"
+    BLOCK_ID = "block_id"
+    WORKSPACE = "workspace"
+
+
+class DataSourceParent(BaseModel):
+    type: Literal[ParentType.DATA_SOURCE_ID]
+    data_source_id: str
+    database_id: str
+
+
+class PageParent(BaseModel):
+    type: Literal[ParentType.PAGE_ID]
+    page_id: str
+
+
+class BlockParent(BaseModel):
+    type: Literal[ParentType.BLOCK_ID]
+    block_id: str
+
+
+class WorkspaceParent(BaseModel):
+    type: Literal[ParentType.WORKSPACE]
+    workspace: bool
+
+
+class DatabaseParent(BaseModel):
+    type: Literal[ParentType.DATABASE_ID]
+    database_id: str
+
+
+Parent = DataSourceParent | PageParent | BlockParent | WorkspaceParent | DatabaseParent