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

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(icon=ExternalFile(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

notionary/shared/properties/type.py

@@ -0,0 +1,30 @@
+from enum import StrEnum
+
+
+class PropertyType(StrEnum):
+    TITLE = "title"
+    RICH_TEXT = "rich_text"
+    SELECT = "select"
+    MULTI_SELECT = "multi_select"
+    STATUS = "status"
+    NUMBER = "number"
+    DATE = "date"
+    CHECKBOX = "checkbox"
+    URL = "url"
+    EMAIL = "email"
+    PHONE_NUMBER = "phone_number"
+    PEOPLE = "people"
+    CREATED_BY = "created_by"
+    LAST_EDITED_BY = "last_edited_by"
+    CREATED_TIME = "created_time"
+    LAST_EDITED_TIME = "last_edited_time"
+    LAST_VISITED_TIME = "last_visited_time"
+    FORMULA = "formula"
+    ROLLUP = "rollup"
+    FILES = "files"
+    RELATION = "relation"
+    BUTTON = "button"
+    LOCATION = "location"
+    PLACE = "place"
+    VERIFICATION = "verification"
+    UNIQUE_ID = "unique_id"

notionary/user/__init__.py

@@ -1,11 +1,7 @@
-from .client import NotionUserClient
-from .notion_bot_user import NotionBotUser
-from .notion_user import NotionUser
-from .notion_user_manager import NotionUserManager
+from .bot import BotUser
+from .person import PersonUser
 
 __all__ = [
-    "NotionUser",
-    "NotionUserManager",
-    "NotionUserClient",
-    "NotionBotUser",
+    "BotUser",
+    "PersonUser",
 ]

notionary/user/base.py

@@ -0,0 +1,89 @@
+from abc import ABC, abstractmethod
+from typing import Self
+
+from notionary.user.client import UserHttpClient
+from notionary.user.schemas import UserResponseDto, UserType
+from notionary.utils.fuzzy import find_best_match
+
+
+class BaseUser(ABC):
+    def __init__(
+        self,
+        id: str,
+        name: str | None = None,
+        avatar_url: str | None = None,
+    ) -> None:
+        self._id = id
+        self._name = name
+        self._avatar_url = avatar_url
+
+    @classmethod
+    async def from_id(
+        cls,
+        user_id: str,
+        http_client: UserHttpClient | None = None,
+    ) -> Self:
+        client = http_client or UserHttpClient()
+        user_dto = await client.get_user_by_id(user_id)
+
+        expected_type = cls._get_expected_user_type()
+        if user_dto.type != expected_type:
+            raise ValueError(f"User {user_id} is not a '{expected_type.value}', but '{user_dto.type.value}'")
+
+        return cls.from_dto(user_dto)
+
+    @classmethod
+    async def from_name(
+        cls,
+        name: str,
+        http_client: UserHttpClient | None = None,
+    ) -> Self:
+        client = http_client or UserHttpClient()
+        all_users = await cls._get_all_users_of_type(client)
+
+        if not all_users:
+            user_type = cls._get_expected_user_type().value
+            raise ValueError(f"No '{user_type}' users found in the workspace")
+
+        best_match = find_best_match(query=name, items=all_users, text_extractor=cls._get_name_extractor())
+        if not best_match:
+            user_type = cls._get_expected_user_type().value
+            raise ValueError(f"No '{user_type}' user found with name similar to '{name}'")
+
+        return best_match
+
+    @classmethod
+    async def _get_all_users_of_type(cls, http_client: UserHttpClient) -> list[Self]:
+        all_workspace_user_dtos = await http_client.get_all_workspace_users()
+        expected_type = cls._get_expected_user_type()
+        filtered_dtos = [dto for dto in all_workspace_user_dtos if dto.type == expected_type]
+        return [cls.from_dto(dto) for dto in filtered_dtos]
+
+    @classmethod
+    @abstractmethod
+    def _get_expected_user_type(cls) -> UserType:
+        pass
+
+    @classmethod
+    @abstractmethod
+    def from_dto(cls, user_dto: UserResponseDto) -> Self:
+        pass
+
+    @classmethod
+    def _get_name_extractor(cls):
+        return lambda user: user.name or ""
+
+    @property
+    def id(self) -> str:
+        return self._id
+
+    @property
+    def name(self) -> str | None:
+        return self._name
+
+    @property
+    def avatar_url(self) -> str | None:
+        return self._avatar_url
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(id={self._id!r}, name={self._name!r})"

notionary/user/bot.py

@@ -0,0 +1,70 @@
+from typing import Self, cast
+
+from notionary.user.base import BaseUser
+from notionary.user.client import UserHttpClient
+from notionary.user.schemas import BotUserDto, BotUserResponseDto, UserResponseDto, UserType, WorkspaceOwnerType
+
+
+class BotUser(BaseUser):
+    def __init__(
+        self,
+        id: str,
+        workspace_file_upload_limit_in_bytes: int,
+        owner_type: WorkspaceOwnerType | None,
+        name: str | None = None,
+        avatar_url: str | None = None,
+        workspace_name: str | None = None,
+    ) -> None:
+        super().__init__(id=id, name=name, avatar_url=avatar_url)
+        self._workspace_name = workspace_name
+        self._workspace_file_upload_limit_in_bytes = workspace_file_upload_limit_in_bytes
+        self._owner_type = owner_type
+
+    @classmethod
+    def _get_expected_user_type(cls) -> UserType:
+        return UserType.BOT
+
+    @classmethod
+    async def from_current_integration(
+        cls,
+        http_client: UserHttpClient | None = None,
+    ) -> Self:
+        client = http_client or UserHttpClient()
+        user_dto = await client.get_current_integration_bot()
+        return cls.from_dto(user_dto)
+
+    @classmethod
+    def from_dto(cls, user_dto: UserResponseDto) -> Self:
+        bot_dto = cast(BotUserResponseDto, user_dto)
+        bot_data: BotUserDto = bot_dto.bot
+
+        owner_type = bot_data.owner.type if bot_data and bot_data.owner else None
+        workspace_name = bot_data.workspace_name if bot_data else None
+
+        limit = 0
+        if bot_data and bot_data.workspace_limits:
+            limit = bot_data.workspace_limits.max_file_upload_size_in_bytes
+
+        return cls(
+            id=bot_dto.id,
+            name=bot_dto.name,
+            avatar_url=bot_dto.avatar_url,
+            workspace_name=workspace_name,
+            workspace_file_upload_limit_in_bytes=limit,
+            owner_type=owner_type,
+        )
+
+    @property
+    def workspace_name(self) -> str | None:
+        return self._workspace_name
+
+    @property
+    def workspace_file_upload_limit_in_bytes(self) -> int:
+        return self._workspace_file_upload_limit_in_bytes
+
+    @property
+    def owner_type(self) -> WorkspaceOwnerType | None:
+        return self._owner_type
+
+    def __repr__(self) -> str:
+        return f"BotUser(id={self._id!r}, name={self._name!r}, avatar_url={self._avatar_url!r}, workspace_name={self._workspace_name!r}, workspace_file_upload_limit_in_bytes={self._workspace_file_upload_limit_in_bytes!r}, owner_type={self._owner_type!r})"

notionary/user/client.py

@@ -1,128 +1,39 @@
-from typing import List, Optional
+from pydantic import TypeAdapter
 
-from notionary.base_notion_client import BaseNotionClient
-from notionary.user.models import (
-    NotionBotUserResponse,
-    NotionUserResponse,
+from notionary.http.client import NotionHttpClient
+from notionary.user.schemas import (
+    BotUserResponseDto,
     NotionUsersListResponse,
+    UserResponseDto,
 )
+from notionary.utils.pagination import paginate_notion_api
 
 
-class NotionUserClient(BaseNotionClient):
-    """
-    Client for Notion user-specific operations.
-    Inherits base HTTP functionality from BaseNotionClient.
-
-    Note: The Notion API only supports individual user queries and bot user info.
-    List users endpoint is available but only returns workspace members (no guests).
-    """
-
-    async def get_user(self, user_id: str) -> Optional[NotionUserResponse]:
-        """
-        Retrieve a user by their ID.
-        """
+class UserHttpClient(NotionHttpClient):
+    async def get_user_by_id(self, user_id: str) -> UserResponseDto:
         response = await self.get(f"users/{user_id}")
-        if response is None:
-            self.logger.error("Failed to fetch user %s - API returned None", user_id)
-            return None
 
-        try:
-            return NotionUserResponse.model_validate(response)
-        except Exception as e:
-            self.logger.error("Failed to validate user response for %s: %s", user_id, e)
-            return None
-
-    async def get_bot_user(self) -> Optional[NotionBotUserResponse]:
-        """
-        Retrieve your token's bot user information.
-        """
-        response = await self.get("users/me")
-        if response is None:
-            self.logger.error("Failed to fetch bot user - API returned None")
-            return None
+        adapter = TypeAdapter(UserResponseDto)
+        return adapter.validate_python(response)
 
-        try:
-            return NotionBotUserResponse.model_validate(response)
-        except Exception as e:
-            self.logger.error("Failed to validate bot user response: %s", e)
-            return None
+    async def get_all_workspace_users(self) -> list[UserResponseDto]:
+        all_entities = await paginate_notion_api(self._get_workspace_entities, page_size=100)
 
-    async def list_users(
-        self, page_size: int = 100, start_cursor: Optional[str] = None
-    ) -> Optional[NotionUsersListResponse]:
-        """
-        List all users in the workspace (paginated).
+        self.logger.info("Fetched %d total workspace users", len(all_entities))
+        return all_entities
 
-        Note: Guests are not included in the response.
-        """
-        params = {"page_size": min(page_size, 100)}  # API max is 100
+    async def _get_workspace_entities(
+        self, page_size: int = 100, start_cursor: str | None = None
+    ) -> NotionUsersListResponse | None:
+        params = {"page_size": min(page_size, 100)}
         if start_cursor:
             params["start_cursor"] = start_cursor
 
         response = await self.get("users", params=params)
-        if response is None:
-            self.logger.error("Failed to fetch users list - API returned None")
-            return None
-
-        try:
-            return NotionUsersListResponse.model_validate(response)
-        except Exception as e:
-            self.logger.error("Failed to validate users list response: %s", e)
-            return None
-
-    async def get_all_users(self) -> List[NotionUserResponse]:
-        """
-        Get all users in the workspace by handling pagination automatically.
-        """
-        all_users = []
-        start_cursor = None
-
-        while True:
-            try:
-                response = await self.list_users(
-                    page_size=100, start_cursor=start_cursor
-                )
 
-                if not response or not response.results:
-                    break
+        return NotionUsersListResponse.model_validate(response)
 
-                all_users.extend(response.results)
-
-                # Check if there are more pages
-                if not response.has_more or not response.next_cursor:
-                    break
-
-                start_cursor = response.next_cursor
-
-            except Exception as e:
-                self.logger.error("Error fetching all users: %s", str(e))
-                break
-
-        self.logger.info("Retrieved %d total users from workspace", len(all_users))
-        return all_users
-
-    async def get_workspace_name(self) -> Optional[str]:
-        """
-        Get the workspace name from the bot user.
-        """
-        try:
-            bot_user = await self.get_bot_user()
-            if bot_user and bot_user.bot and bot_user.bot.workspace_name:
-                return bot_user.bot.workspace_name
-            return None
-        except Exception as e:
-            self.logger.error("Error fetching workspace name: %s", str(e))
-            return None
+    async def get_current_integration_bot(self) -> BotUserResponseDto:
+        response = await self.get("users/me")
 
-    async def get_workspace_limits(self) -> Optional[dict]:
-        """
-        Get workspace limits from the bot user.
-        """
-        try:
-            bot_user = await self.get_bot_user()
-            if bot_user and bot_user.bot and bot_user.bot.workspace_limits:
-                return bot_user.bot.workspace_limits.model_dump()
-            return None
-        except Exception as e:
-            self.logger.error("Error fetching workspace limits: %s", str(e))
-            return None
+        return BotUserResponseDto.model_validate(response)

notionary/user/person.py

@@ -0,0 +1,41 @@
+from typing import Self, cast
+
+from notionary.user.base import BaseUser
+from notionary.user.schemas import PersonUserResponseDto, UserResponseDto, UserType
+
+
+class PersonUser(BaseUser):
+    def __init__(
+        self,
+        id: str,
+        name: str,
+        avatar_url: str,
+        email: str,
+    ) -> None:
+        super().__init__(id=id, name=name, avatar_url=avatar_url)
+        self._email = email
+
+    @classmethod
+    def _get_expected_user_type(cls) -> UserType:
+        return UserType.PERSON
+
+    @classmethod
+    def from_dto(cls, user_dto: UserResponseDto) -> Self:
+        person_dto = cast(PersonUserResponseDto, user_dto)
+        return cls(
+            id=person_dto.id,
+            name=person_dto.name or "",
+            avatar_url=person_dto.avatar_url,
+            email=person_dto.person.email or "",
+        )
+
+    @property
+    def name(self) -> str:
+        return self._name or ""
+
+    @property
+    def email(self) -> str:
+        return self._email
+
+    def __repr__(self) -> str:
+        return f"PersonUser(id={self._id!r}, name={self._name!r}, email={self._email!r})"