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

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/shared/typings.py

@@ -0,0 +1,3 @@
+from typing import Any
+
+type JsonDict = dict[str, Any]

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,138 @@
+from __future__ import annotations
+
+from abc import abstractmethod
+from typing import TYPE_CHECKING, Self
+
+from notionary.exceptions.search import NoUsersInWorkspace, UserNotFound
+from notionary.user.client import UserHttpClient
+from notionary.user.schemas import UserResponseDto, UserType
+from notionary.utils.fuzzy import find_all_matches
+
+if TYPE_CHECKING:
+    from notionary.user.bot import BotUser
+    from notionary.user.person import PersonUser
+
+
+class BaseUser:
+    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_auto(
+        cls,
+        user_id: str,
+        http_client: UserHttpClient | None = None,
+    ) -> BotUser | PersonUser:
+        from notionary.user.bot import BotUser
+        from notionary.user.person import PersonUser
+
+        client = http_client or UserHttpClient()
+        user_dto = await client.get_user_by_id(user_id)
+
+        if user_dto.type == UserType.BOT:
+            return BotUser.from_dto(user_dto)
+        elif user_dto.type == UserType.PERSON:
+            return PersonUser.from_dto(user_dto)
+        else:
+            raise ValueError(f"Unknown user type: {user_dto.type}")
+
+    @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)
+
+        user_type = cls._get_expected_user_type().value
+
+        if not all_users:
+            raise NoUsersInWorkspace(user_type)
+
+        exact_match = cls._find_exact_match(all_users, name)
+        if exact_match:
+            return exact_match
+
+        suggestions = cls._get_fuzzy_suggestions(all_users, name)
+        raise UserNotFound(user_type, name, suggestions)
+
+    @classmethod
+    def _find_exact_match(cls, users: list[Self], query: str) -> Self | None:
+        query_lower = query.lower()
+        for user in users:
+            if user.name and user.name.lower() == query_lower:
+                return user
+        return None
+
+    @classmethod
+    def _get_fuzzy_suggestions(cls, users: list[Self], query: str) -> list[str]:
+        sorted_by_similarity = find_all_matches(
+            query=query,
+            items=users,
+            text_extractor=cls._get_name_extractor(),
+            min_similarity=0.6,
+        )
+
+        if sorted_by_similarity:
+            return [user.name for user in sorted_by_similarity[:5] if user.name]
+
+        return [user.name for user in users[:5] if user.name]
+
+    @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})"

notionary/user/schemas.py

@@ -0,0 +1,67 @@
+from enum import StrEnum
+from typing import Annotated, Literal
+
+from pydantic import BaseModel, Field
+
+
+class UserType(StrEnum):
+    PERSON = "person"
+    BOT = "bot"
+
+
+class WorkspaceOwnerType(StrEnum):
+    USER = "user"
+    WORKSPACE = "workspace"
+
+
+class PersonUserDto(BaseModel):
+    email: str | None = None
+
+
+class BotOwnerDto(BaseModel):
+    type: WorkspaceOwnerType
+    workspace: bool | None = None
+
+
+class WorkspaceLimits(BaseModel):
+    max_file_upload_size_in_bytes: int
+
+
+class BotUserDto(BaseModel):
+    owner: BotOwnerDto | None = None
+    workspace_name: str | None = None
+    workspace_limits: WorkspaceLimits | None = None
+
+
+class NotionUserBase(BaseModel):
+    object: Literal["user"] = "user"
+    id: str
+
+    type: UserType
+
+    name: str | None = None
+    avatar_url: str | None = None
+
+
+class PersonUserResponseDto(NotionUserBase):
+    type: Literal[UserType.PERSON] = UserType.PERSON
+    person: PersonUserDto
+
+
+class BotUserResponseDto(NotionUserBase):
+    type: Literal[UserType.BOT] = UserType.BOT
+    bot: BotUserDto
+
+
+UserResponseDto = Annotated[PersonUserResponseDto | BotUserResponseDto, Field(discriminator="type")]
+
+
+class NotionUsersListResponse(BaseModel):
+    results: list[UserResponseDto]
+    next_cursor: str | None = None
+    has_more: bool
+
+
+class PartialUserDto(BaseModel):
+    object: Literal["user"] = "user"
+    id: str

notionary/user/service.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+
+from notionary.user import BotUser, PersonUser
+from notionary.user.client import UserHttpClient
+from notionary.user.schemas import UserType
+
+
+class UserService:
+    def __init__(self, client: UserHttpClient | None = None) -> None:
+        self._client = client or UserHttpClient()
+
+    async def list_users(self) -> list[PersonUser]:
+        all_users = await self._client.get_all_workspace_users()
+        person_users = [user for user in all_users if user.type == UserType.PERSON]
+
+        return [PersonUser.from_dto(user) for user in person_users]
+
+    async def list_users_stream(self) -> AsyncIterator[PersonUser]:
+        all_users = await self._client.get_all_workspace_users()
+        for user in all_users:
+            if user.type == UserType.PERSON:
+                yield PersonUser.from_dto(user)
+
+    async def list_bot_users(self) -> list[BotUser]:
+        all_users = await self._client.get_all_workspace_users()
+        bot_users = [user for user in all_users if user.type == UserType.BOT]
+
+        return [BotUser.from_dto(user) for user in bot_users]
+
+    async def list_bot_users_stream(self) -> AsyncIterator[BotUser]:
+        all_users = await self._client.get_all_workspace_users()
+        for user in all_users:
+            if user.type == UserType.BOT:
+                yield BotUser.from_dto(user)
+
+    async def search_users(self, query: str) -> list[PersonUser]:
+        all_person_users = await self.list_users()
+        query_lower = query.lower()
+
+        return [
+            user
+            for user in all_person_users
+            if query_lower in (user.name or "").lower() or query_lower in (user.email or "").lower()
+        ]
+
+    async def search_users_stream(self, query: str) -> AsyncIterator[PersonUser]:
+        query_lower = query.lower()
+
+        async for user in self.list_users_stream():
+            if query_lower in (user.name or "").lower() or query_lower in (user.email or "").lower():
+                yield user
+
+    async def get_current_bot(self) -> BotUser:
+        bot_dto = await self._client.get_current_integration_bot()
+        return BotUser.from_dto(bot_dto)
+
+    async def get_user_by_id(self, user_id: str) -> PersonUser | BotUser | None:
+        user_dto = await self._client.get_user_by_id(user_id)
+
+        if user_dto.type == UserType.PERSON:
+            return PersonUser.from_dto(user_dto)
+        else:
+            return BotUser.from_dto(user_dto)

notionary/utils/date.py

@@ -0,0 +1,51 @@
+from datetime import datetime
+
+
+def parse_date(date_str: str) -> str:
+    supported_formats = _get_supported_date_formats()
+
+    for date_format in supported_formats:
+        parsed_date = _try_parse_date_with_format(date_str, date_format)
+        if _date_was_successfully_parsed(parsed_date):
+            return _convert_to_iso_format(parsed_date)
+
+    _raise_invalid_date_format_error(date_str)
+
+
+def _get_supported_date_formats() -> list[str]:
+    return [
+        "%Y-%m-%d",  # ISO: 2024-12-31
+        "%d.%m.%Y",  # German: 31.12.2024
+        "%m/%d/%Y",  # US with slash: 12/31/2024
+        "%m-%d-%Y",  # US with dash: 12-31-2024
+        "%d/%m/%Y",  # Day first with slash: 31/12/2024
+        "%d-%m-%Y",  # Day first with dash: 31-12-2024
+        "%d-%b-%Y",  # Short month: 31-Dec-2024
+        "%d %b %Y",  # Short month with space: 31 Dec 2024
+        "%d-%B-%Y",  # Full month: 31-December-2024
+        "%d %B %Y",  # Full month with space: 31 December 2024
+    ]
+
+
+def _try_parse_date_with_format(date_str: str, date_format: str) -> datetime | None:
+    try:
+        return datetime.strptime(date_str, date_format)
+    except ValueError:
+        return None
+
+
+def _date_was_successfully_parsed(parsed_date: datetime | None) -> bool:
+    return parsed_date is not None
+
+
+def _convert_to_iso_format(parsed_date: datetime) -> str:
+    return parsed_date.strftime("%Y-%m-%d")
+
+
+def _raise_invalid_date_format_error(date_str: str) -> None:
+    error_message = (
+        f"Invalid date format: '{date_str}'. "
+        f"Supported formats: YYYY-MM-DD, DD.MM.YYYY, MM/DD/YYYY, DD/MM/YYYY, "
+        f"DD-Mon-YYYY, DD Month YYYY"
+    )
+    raise ValueError(error_message)