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

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/async_retry.py

@@ -0,0 +1,39 @@
+import asyncio
+import functools
+from collections.abc import Callable
+from typing import Any
+
+
+def async_retry(
+    max_retries: int = 3,
+    initial_delay: float = 1.0,
+    backoff_factor: float = 2.0,
+    retry_on_exceptions: tuple[type[Exception], ...] | None = None,
+):
+    def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
+        @functools.wraps(func)
+        async def wrapper(*args: Any, **kwargs: Any) -> Any:
+            delay = initial_delay
+            last_exception = None
+
+            for attempt in range(max_retries + 1):
+                try:
+                    return await func(*args, **kwargs)
+                except Exception as e:
+                    last_exception = e
+
+                    # If specific exceptions are defined, only retry those
+                    if retry_on_exceptions is not None and not isinstance(e, retry_on_exceptions):
+                        raise
+
+                    if attempt == max_retries:
+                        raise
+
+                    await asyncio.sleep(delay)
+                    delay *= backoff_factor
+
+            raise last_exception
+
+        return wrapper
+
+    return decorator

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)

notionary/utils/fuzzy.py

@@ -0,0 +1,56 @@
+import difflib
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any, Generic, TypeVar
+
+T = TypeVar("T")
+
+
+@dataclass(frozen=True)
+class _MatchResult(Generic[T]):
+    item: Any
+    similarity: float
+
+
+def find_best_match(
+    query: str,
+    items: list[T],
+    text_extractor: Callable[[T], str],
+    min_similarity: float | None = 0.0,
+) -> T | None:
+    min_similarity = 0.0 if min_similarity is None else min_similarity
+
+    matches = _find_best_matches(query, items, text_extractor, min_similarity, limit=1)
+    return matches[0].item if matches else None
+
+
+def _find_best_matches(
+    query: str,
+    items: list[T],
+    text_extractor: Callable[[T], str],
+    min_similarity: float = 0.0,
+    limit: int | None = None,
+) -> list[_MatchResult[T]]:
+    results = []
+
+    for item in items:
+        text = text_extractor(item)
+        similarity = _calculate_similarity(query, text)
+
+        if similarity >= min_similarity:
+            results.append(_MatchResult(item=item, similarity=similarity))
+
+    results = _sort_by_highest_similarity_first(results)
+
+    if limit:
+        return results[:limit]
+
+    return results
+
+
+def _sort_by_highest_similarity_first(results: list[_MatchResult]) -> list[_MatchResult]:
+    return sorted(results, key=lambda x: x.similarity, reverse=True)
+
+
+def _calculate_similarity(query: str, target: str) -> float:
+    return difflib.SequenceMatcher(None, query.lower().strip(), target.lower().strip()).ratio()

notionary/{util/logging_mixin.py → utils/mixins/logging.py}

@@ -1,16 +1,9 @@
 import logging
 import os
-from typing import ClassVar, Optional
+from typing import ClassVar
 
-from dotenv import load_dotenv
 
-load_dotenv()
-
-
-def setup_logging():
-    """
-    Sets up logging configuration for the application.
-    """
+def _setup_logging() -> None:
     log_level = os.getenv("LOG_LEVEL", "WARNING").upper()
     logging.basicConfig(
         level=getattr(logging, log_level),
@@ -20,18 +13,13 @@ def setup_logging():
     logging.getLogger("httpx").setLevel(logging.WARNING)
 
 
-setup_logging()
+_setup_logging()
 
 
 class LoggingMixin:
-    # Class attribute with proper typing
     logger: ClassVar[logging.Logger] = None
 
     def __init_subclass__(cls, **kwargs):
-        """
-        This method is called when a class inherits from LoggingMixin.
-        It automatically sets up the logger as a class attribute.
-        """
         super().__init_subclass__(**kwargs)
         cls.logger = logging.getLogger(cls.__name__)
 
@@ -43,7 +31,7 @@ class LoggingMixin:
         return self._logger
 
     @staticmethod
-    def _get_class_name_from_frame(frame) -> Optional[str]:
+    def _get_class_name_from_frame(frame) -> str | None:
         local_vars = frame.f_locals
         if "self" in local_vars:
             return local_vars["self"].__class__.__name__

notionary/utils/pagination.py

@@ -0,0 +1,50 @@
+from collections.abc import AsyncGenerator, Callable, Coroutine
+from typing import Any
+
+from pydantic import BaseModel
+
+
+class PaginatedResponse(BaseModel):
+    results: list[Any]
+    has_more: bool
+    next_cursor: str | None
+
+
+async def _fetch_pages(
+    api_call: Callable[..., Coroutine[Any, Any, PaginatedResponse]],
+    **kwargs,
+) -> AsyncGenerator[PaginatedResponse]:
+    next_cursor = None
+    has_more = True
+
+    while has_more:
+        current_kwargs = kwargs.copy()
+        if next_cursor:
+            current_kwargs["start_cursor"] = next_cursor
+
+        response = await api_call(**current_kwargs)
+        yield response
+
+        has_more = response.has_more
+        next_cursor = response.next_cursor
+
+
+async def paginate_notion_api(
+    api_call: Callable[..., Coroutine[Any, Any, PaginatedResponse]],
+    **kwargs,
+) -> list[Any]:
+    all_results = []
+    async for page in _fetch_pages(api_call, **kwargs):
+        if page.results:
+            all_results.extend(page.results)
+    return all_results
+
+
+async def paginate_notion_api_generator(
+    api_call: Callable[..., Coroutine[Any, Any, PaginatedResponse]],
+    **kwargs,
+) -> AsyncGenerator[Any]:
+    async for page in _fetch_pages(api_call, **kwargs):
+        if page.results:
+            for item in page.results:
+                yield item

notionary/utils/singleton.py

@@ -0,0 +1,13 @@
+from collections.abc import Callable
+from typing import Any
+
+
+def singleton(cls) -> Callable[..., Any]:
+    instances = {}
+
+    def get_instance(*args, **kwargs) -> Any:
+        if cls not in instances:
+            instances[cls] = cls(*args, **kwargs)
+        return instances[cls]
+
+    return get_instance

notionary/utils/uuid_utils.py

@@ -0,0 +1,20 @@
+import re
+
+
+def extract_uuid(source: str) -> str | None:
+    UUID_RAW_PATTERN = r"([a-f0-9]{32})"
+
+    if _is_valid_uuid(source):
+        return source
+
+    match = re.search(UUID_RAW_PATTERN, source.lower())
+    if not match:
+        return None
+
+    uuid_raw = match.group(1)
+    return f"{uuid_raw[0:8]}-{uuid_raw[8:12]}-{uuid_raw[12:16]}-{uuid_raw[16:20]}-{uuid_raw[20:32]}"
+
+
+def _is_valid_uuid(uuid: str) -> bool:
+    UUID_PATTERN = r"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$"
+    return bool(re.match(UUID_PATTERN, uuid.lower()))

notionary/workspace/__init__.py

@@ -0,0 +1,3 @@
+from .service import NotionWorkspace
+
+__all__ = ["NotionWorkspace"]

notionary/workspace/client.py

@@ -0,0 +1,62 @@
+from collections.abc import AsyncGenerator
+from typing import Any
+
+from notionary.data_source.schemas import DataSourceDto
+from notionary.http.client import NotionHttpClient
+from notionary.page.schemas import NotionPageDto
+from notionary.utils.pagination import paginate_notion_api_generator
+from notionary.workspace.query.models import WorkspaceQueryConfig
+from notionary.workspace.schemas import DataSourceSearchResponse, PageSearchResponse
+
+
+class WorkspaceClient:
+    DEFAULT_PAGE_SIZE = 100
+
+    def __init__(self, http_client: NotionHttpClient | None = None) -> None:
+        self._http_client = http_client or NotionHttpClient()
+
+    async def query_pages_stream(
+        self,
+        search_config: WorkspaceQueryConfig,
+    ) -> AsyncGenerator[NotionPageDto]:
+        async for page in paginate_notion_api_generator(
+            self._query_pages,
+            search_config=search_config,
+        ):
+            yield page
+
+    async def query_data_sources_stream(
+        self,
+        search_config: WorkspaceQueryConfig,
+    ) -> AsyncGenerator[DataSourceDto]:
+        async for data_source in paginate_notion_api_generator(
+            self._query_data_sources,
+            search_config=search_config,
+        ):
+            yield data_source
+
+    async def _query_pages(
+        self,
+        search_config: WorkspaceQueryConfig,
+        start_cursor: str | None = None,
+    ) -> PageSearchResponse:
+        if start_cursor:
+            search_config.start_cursor = start_cursor
+
+        response = await self._execute_search(search_config)
+        return PageSearchResponse.model_validate(response)
+
+    async def _query_data_sources(
+        self,
+        search_config: WorkspaceQueryConfig,
+        start_cursor: str | None = None,
+    ) -> DataSourceSearchResponse:
+        if start_cursor:
+            search_config.start_cursor = start_cursor
+
+        response = await self._execute_search(search_config)
+        return DataSourceSearchResponse.model_validate(response)
+
+    async def _execute_search(self, config: WorkspaceQueryConfig) -> dict[str, Any]:
+        serialized_config = config.model_dump(exclude_none=True, by_alias=True)
+        return await self._http_client.post("search", serialized_config)

notionary/workspace/query/builder.py

@@ -0,0 +1,60 @@
+from typing import Self
+
+from notionary.workspace.query.models import (
+    SortDirection,
+    SortTimestamp,
+    WorkspaceQueryConfig,
+    WorkspaceQueryObjectType,
+)
+
+
+class WorkspaceQueryConfigBuilder:
+    def __init__(self, config: WorkspaceQueryConfig = None) -> None:
+        self.config = config or WorkspaceQueryConfig()
+
+    def with_query(self, query: str) -> Self:
+        self.config.query = query
+        return self
+
+    def with_pages_only(self) -> Self:
+        self.config.object_type = WorkspaceQueryObjectType.PAGE
+        return self
+
+    def with_data_sources_only(self) -> Self:
+        self.config.object_type = WorkspaceQueryObjectType.DATA_SOURCE
+        return self
+
+    def with_sort_direction(self, direction: SortDirection) -> Self:
+        self.config.sort_direction = direction
+        return self
+
+    def with_sort_ascending(self) -> Self:
+        return self.with_sort_direction(SortDirection.ASCENDING)
+
+    def with_sort_descending(self) -> Self:
+        return self.with_sort_direction(SortDirection.DESCENDING)
+
+    def with_sort_timestamp(self, timestamp: SortTimestamp) -> Self:
+        self.config.sort_timestamp = timestamp
+        return self
+
+    def with_sort_by_created_time(self) -> Self:
+        return self.with_sort_timestamp(SortTimestamp.CREATED_TIME)
+
+    def with_sort_by_last_edited(self) -> Self:
+        return self.with_sort_timestamp(SortTimestamp.LAST_EDITED_TIME)
+
+    def with_page_size(self, size: int) -> Self:
+        self.config.page_size = min(size, 100)
+        return self
+
+    def with_start_cursor(self, cursor: str | None) -> Self:
+        self.config.start_cursor = cursor
+        return self
+
+    def without_cursor(self) -> Self:
+        self.config.start_cursor = None
+        return self
+
+    def build(self) -> WorkspaceQueryConfig:
+        return self.config

notionary/workspace/query/models.py

@@ -0,0 +1,60 @@
+from enum import StrEnum
+from typing import Any
+
+from pydantic import BaseModel, Field, field_validator, model_serializer
+
+
+class SortDirection(StrEnum):
+    ASCENDING = "ascending"
+    DESCENDING = "descending"
+
+
+class SortTimestamp(StrEnum):
+    LAST_EDITED_TIME = "last_edited_time"
+    CREATED_TIME = "created_time"
+
+
+class WorkspaceQueryObjectType(StrEnum):
+    PAGE = "page"
+    DATA_SOURCE = "data_source"
+
+
+class WorkspaceQueryConfig(BaseModel):
+    query: str | None = None
+    object_type: WorkspaceQueryObjectType | None = None
+    sort_direction: SortDirection = SortDirection.DESCENDING
+    sort_timestamp: SortTimestamp = SortTimestamp.LAST_EDITED_TIME
+    page_size: int = Field(default=100, ge=1, le=100)
+    start_cursor: str | None = None
+
+    @field_validator("query")
+    @classmethod
+    def replace_empty_query_with_none(cls, value: str | None) -> str | None:
+        if value is not None and not value.strip():
+            return None
+        return value
+
+    @model_serializer
+    def serialize_model(self) -> dict[str, Any]:
+        search_dict: dict[str, Any] = {}
+
+        if self.query:
+            search_dict["query"] = self.query
+
+        if self.object_type:
+            search_dict["filter"] = {
+                "property": "object",
+                "value": self.object_type.value,
+            }
+
+        search_dict["sort"] = {
+            "direction": self.sort_direction.value,
+            "timestamp": self.sort_timestamp.value,
+        }
+
+        search_dict["page_size"] = self.page_size
+
+        if self.start_cursor:
+            search_dict["start_cursor"] = self.start_cursor
+
+        return search_dict