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

notionary/shared/entity/service.py

@@ -1,45 +1,68 @@
-from __future__ import annotations
-
 import random
 from abc import ABC, abstractmethod
 from collections.abc import Sequence
-from typing import TYPE_CHECKING, Self
+from typing import Self
 
 from notionary.shared.entity.entity_metadata_update_client import EntityMetadataUpdateClient
-from notionary.user.schemas import PartialUserDto
+from notionary.shared.entity.schemas import EntityResponseDto
+from notionary.shared.models.cover import CoverType
+from notionary.shared.models.icon import IconType
+from notionary.shared.models.parent import ParentType
+from notionary.user.base import BaseUser
 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,
+        dto: EntityResponseDto,
         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._id = dto.id
+        self._created_time = dto.created_time
+        self._created_by = dto.created_by
+        self._last_edited_time = dto.last_edited_time
+        self._last_edited_by = dto.last_edited_by
+        self._in_trash = dto.in_trash
+        self._parent = dto.parent
+        self._url = dto.url
+        self._public_url = dto.public_url
+
+        self._emoji_icon = self._extract_emoji_icon(dto)
+        self._external_icon_url = self._extract_external_icon_url(dto)
+        self._cover_image_url = self._extract_cover_image_url(dto)
+
         self._user_service = user_service or UserService()
 
+    @staticmethod
+    def _extract_emoji_icon(dto: EntityResponseDto) -> str | None:
+        if dto.icon is None:
+            return None
+        if dto.icon.type is not IconType.EMOJI:
+            return None
+
+        return dto.icon.emoji
+
+    @staticmethod
+    def _extract_external_icon_url(dto: EntityResponseDto) -> str | None:
+        if dto.icon is None:
+            return None
+        if dto.icon.type is not IconType.EXTERNAL:
+            return None
+
+        return dto.icon.external.url
+
+    @staticmethod
+    def _extract_cover_image_url(dto: EntityResponseDto) -> str | None:
+        if dto.cover is None:
+            return None
+        if dto.cover.type is not CoverType.EXTERNAL:
+            return None
+
+        return dto.cover.external.url
+
     @classmethod
     @abstractmethod
     async def from_id(cls, id: str) -> Self:
@@ -93,12 +116,43 @@ class Entity(LoggingMixin, ABC):
         return self._cover_image_url
 
     @property
-    def created_by(self) -> PartialUserDto:
-        return self._created_by
+    def url(self) -> str:
+        return self._url
 
     @property
-    def last_edited_by(self) -> PartialUserDto:
-        return self._last_edited_by
+    def public_url(self) -> str | None:
+        return self._public_url
+
+    # =========================================================================
+    # Parent ID Getters
+    # =========================================================================
+
+    def get_parent_database_id_if_present(self) -> str | None:
+        if self._parent.type == ParentType.DATABASE_ID:
+            return self._parent.database_id
+        return None
+
+    def get_parent_data_source_id_if_present(self) -> str | None:
+        if self._parent.type == ParentType.DATA_SOURCE_ID:
+            return self._parent.data_source_id
+        return None
+
+    def get_parent_page_id_if_present(self) -> str | None:
+        if self._parent.type == ParentType.PAGE_ID:
+            return self._parent.page_id
+        return None
+
+    def get_parent_block_id_if_present(self) -> str | None:
+        if self._parent.type == ParentType.BLOCK_ID:
+            return self._parent.block_id
+        return None
+
+    def is_workspace_parent(self) -> bool:
+        return self._parent.type == ParentType.WORKSPACE
+
+    # =========================================================================
+    # User Methods
+    # =========================================================================
 
     async def get_created_by_user(self) -> BaseUser | None:
         return await self._user_service.get_user_by_id(self._created_by.id)
@@ -106,17 +160,19 @@ class Entity(LoggingMixin, ABC):
     async def get_last_edited_by_user(self) -> BaseUser | None:
         return await self._user_service.get_user_by_id(self._last_edited_by.id)
 
+    # =========================================================================
+    # Icon & Cover Methods
+    # =========================================================================
+
     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._emoji_icon = self._extract_emoji_icon(entity_response)
         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
-        )
+        self._external_icon_url = self._extract_external_icon_url(entity_response)
 
     async def remove_icon(self) -> None:
         await self._entity_metadata_update_client.remove_icon()
@@ -125,9 +181,7 @@ class Entity(LoggingMixin, ABC):
 
     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
-        )
+        self._cover_image_url = self._extract_cover_image_url(entity_response)
 
     async def set_random_gradient_cover(self) -> None:
         random_cover_url = self._get_random_gradient_cover()
@@ -137,6 +191,10 @@ class Entity(LoggingMixin, ABC):
         await self._entity_metadata_update_client.remove_cover()
         self._cover_image_url = None
 
+    # =========================================================================
+    # Trash Methods
+    # =========================================================================
+
     async def move_to_trash(self) -> None:
         if self._in_trash:
             self.logger.warning("Entity is already in trash.")

notionary/shared/models/cover.py

@@ -17,4 +17,4 @@ class NotionCover(BaseModel):
 
     @classmethod
     def from_url(cls, url: str) -> Self:
-        return cls(icon=ExternalFile(url))
+        return cls(external=ExternalFile(url=url))

notionary/shared/typings.py

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

notionary/user/base.py

@@ -1,12 +1,19 @@
-from abc import ABC, abstractmethod
-from typing import Self
+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_best_match
+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(ABC):
+class BaseUser:
     def __init__(
         self,
         id: str,
@@ -17,6 +24,25 @@ class BaseUser(ABC):
         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,
@@ -41,16 +67,39 @@ class BaseUser(ABC):
         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:
-            user_type = cls._get_expected_user_type().value
-            raise ValueError(f"No '{user_type}' users found in the workspace")
+            raise NoUsersInWorkspace(user_type)
 
-        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}'")
+        exact_match = cls._find_exact_match(all_users, name)
+        if exact_match:
+            return exact_match
 
-        return best_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]:

notionary/utils/decorators.py

@@ -0,0 +1,122 @@
+import asyncio
+import functools
+import logging
+import time
+from collections.abc import Callable, Coroutine
+from typing import Any, ParamSpec, TypeVar
+
+P = ParamSpec("P")
+R = TypeVar("R")
+T = TypeVar("T")
+
+type SyncFunc = Callable[P, R]
+type AsyncFunc = Callable[P, Coroutine[Any, Any, R]]
+type SyncDecorator = Callable[[SyncFunc], SyncFunc]
+type AsyncDecorator = Callable[[AsyncFunc], AsyncFunc]
+
+
+def singleton(cls):
+    instance = [None]
+
+    def wrapper(*args, **kwargs):
+        if instance[0] is None:
+            instance[0] = cls(*args, **kwargs)
+        return instance[0]
+
+    return wrapper
+
+
+def time_execution_sync(additional_text: str = "", min_duration_to_log: float = 0.25) -> SyncDecorator:
+    def decorator(func: SyncFunc) -> SyncFunc:
+        @functools.wraps(func)
+        def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+            start_time = time.perf_counter()
+            result = func(*args, **kwargs)
+            execution_time = time.perf_counter() - start_time
+
+            if execution_time > min_duration_to_log:
+                logger = _get_logger_from_context(args, func)
+                function_name = additional_text.strip("-") or func.__name__
+                logger.debug(f"⏳ {function_name}() took {execution_time:.2f}s")
+
+            return result
+
+        return wrapper
+
+    return decorator
+
+
+def time_execution_async(
+    additional_text: str = "",
+    min_duration_to_log: float = 0.25,
+) -> AsyncDecorator:
+    def decorator(func: AsyncFunc) -> AsyncFunc:
+        @functools.wraps(func)
+        async def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+            start_time = time.perf_counter()
+            result = await func(*args, **kwargs)
+            execution_time = time.perf_counter() - start_time
+
+            if execution_time > min_duration_to_log:
+                logger = _get_logger_from_context(args, func)
+                function_name = additional_text.strip("-") or func.__name__
+                logger.debug(f"⏳ {function_name}() took {execution_time:.2f}s")
+
+            return result
+
+        return wrapper
+
+    return decorator
+
+
+def _get_logger_from_context(args: tuple, func: Callable) -> logging.Logger:
+    if _has_instance_logger(args):
+        return _extract_instance_logger(args)
+
+    return _get_module_logger(func)
+
+
+def _has_instance_logger(args: tuple) -> bool:
+    return bool(args) and hasattr(args[0], "logger")
+
+
+def _extract_instance_logger(args: tuple) -> logging.Logger:
+    return args[0].logger
+
+
+def _get_module_logger(func: Callable) -> logging.Logger:
+    return logging.getLogger(func.__module__)
+
+
+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 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/fuzzy.py

@@ -1,14 +1,14 @@
 import difflib
 from collections.abc import Callable
 from dataclasses import dataclass
-from typing import Any, Generic, TypeVar
+from typing import Generic, TypeVar
 
 T = TypeVar("T")
 
 
 @dataclass(frozen=True)
 class _MatchResult(Generic[T]):
-    item: Any
+    item: T
     similarity: float
 
 
@@ -16,14 +16,22 @@ def find_best_match(
     query: str,
     items: list[T],
     text_extractor: Callable[[T], str],
-    min_similarity: float | None = 0.0,
+    min_similarity: float,
 ) -> 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_all_matches(
+    query: str,
+    items: list[T],
+    text_extractor: Callable[[T], str],
+    min_similarity: float,
+) -> list[T]:
+    matches = _find_best_matches(query, items, text_extractor, min_similarity, limit=None)
+    return [match.item for match in matches]
+
+
 def _find_best_matches(
     query: str,
     items: list[T],
@@ -53,4 +61,8 @@ def _sort_by_highest_similarity_first(results: list[_MatchResult]) -> list[_Matc
 
 
 def _calculate_similarity(query: str, target: str) -> float:
-    return difflib.SequenceMatcher(None, query.lower().strip(), target.lower().strip()).ratio()
+    return difflib.SequenceMatcher(
+        isjunk=None,
+        a=query.lower().strip(),
+        b=target.lower().strip(),
+    ).ratio()

notionary/utils/mixins/logging.py

@@ -2,18 +2,46 @@ import logging
 import os
 from typing import ClassVar
 
+from dotenv import load_dotenv
 
-def _setup_logging() -> None:
-    log_level = os.getenv("LOG_LEVEL", "WARNING").upper()
-    logging.basicConfig(
-        level=getattr(logging, log_level),
-        format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
-    )
+load_dotenv(override=True)
 
-    logging.getLogger("httpx").setLevel(logging.WARNING)
+logger = logging.getLogger("notionary")
+logger.addHandler(logging.NullHandler())
 
 
-_setup_logging()
+def configure_library_logging(level: str = "WARNING") -> None:
+    log_level = getattr(logging, level.upper(), logging.WARNING)
+
+    library_logger = logging.getLogger("notionary")
+
+    if library_logger.handlers:
+        library_logger.handlers.clear()
+
+    handler = logging.StreamHandler()
+    handler.setFormatter(logging.Formatter("%(asctime)s - %(name)s - %(levelname)s - %(message)s"))
+
+    library_logger.setLevel(log_level)
+    library_logger.addHandler(handler)
+
+    _suppress_noisy_third_party_loggers()
+
+
+def _suppress_noisy_third_party_loggers() -> None:
+    noisy_loggers = ["httpx", "httpcore", "httpcore.connection", "httpcore.http11"]
+
+    for logger_name in noisy_loggers:
+        logging.getLogger(logger_name).setLevel(logging.WARNING)
+
+
+def _auto_configure_from_environment() -> None:
+    env_log_level = os.getenv("NOTIONARY_LOG_LEVEL")
+
+    if env_log_level:
+        configure_library_logging(env_log_level)
+
+
+_auto_configure_from_environment()
 
 
 class LoggingMixin:
@@ -21,27 +49,10 @@ class LoggingMixin:
 
     def __init_subclass__(cls, **kwargs):
         super().__init_subclass__(**kwargs)
-        cls.logger = logging.getLogger(cls.__name__)
+        cls.logger = logging.getLogger(f"notionary.{cls.__name__}")
 
     @property
     def instance_logger(self) -> logging.Logger:
-        """Instance logger - for instance methods"""
         if not hasattr(self, "_logger"):
-            self._logger = logging.getLogger(self.__class__.__name__)
+            self._logger = logging.getLogger(f"notionary.{self.__class__.__name__}")
         return self._logger
-
-    @staticmethod
-    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__
-
-        if "cls" in local_vars:
-            return local_vars["cls"].__name__
-
-        if "__qualname__" in frame.f_code.co_names:
-            qualname = frame.f_code.co_qualname
-            if "." in qualname:
-                return qualname.split(".")[0]
-
-        return None

notionary/utils/pagination.py

@@ -10,41 +10,95 @@ class PaginatedResponse(BaseModel):
     next_cursor: str | None
 
 
-async def _fetch_pages(
+async def _fetch_data(
     api_call: Callable[..., Coroutine[Any, Any, PaginatedResponse]],
+    total_results_limit: int | None = None,
     **kwargs,
 ) -> AsyncGenerator[PaginatedResponse]:
-    next_cursor = None
-    has_more = True
+    next_cursor: str | None = None
+    has_more: bool = True
+    total_fetched: int = 0
+    api_page_size: int = kwargs.get("page_size", 100)
 
-    while has_more:
-        current_kwargs = kwargs.copy()
-        if next_cursor:
-            current_kwargs["start_cursor"] = next_cursor
+    while has_more and _should_continue_fetching(total_results_limit, total_fetched):
+        request_params = _build_request_params(kwargs, next_cursor)
+        response = await api_call(**request_params)
 
-        response = await api_call(**current_kwargs)
-        yield response
+        limited_results = _apply_result_limit(response.results, total_results_limit, total_fetched)
+        total_fetched += len(limited_results)
+
+        yield _create_limited_response(response, limited_results, api_page_size)
+
+        if _has_reached_limit(total_results_limit, total_fetched):
+            break
 
         has_more = response.has_more
         next_cursor = response.next_cursor
 
 
+def _should_continue_fetching(total_limit: int | None, total_fetched: int) -> bool:
+    if total_limit is None:
+        return True
+    return total_fetched < total_limit
+
+
+def _build_request_params(
+    base_kwargs: dict[str, Any],
+    cursor: str | None,
+) -> dict[str, Any]:
+    params = base_kwargs.copy()
+    if cursor:
+        params["start_cursor"] = cursor
+    return params
+
+
+def _apply_result_limit(results: list[Any], total_limit: int | None, total_fetched: int) -> list[Any]:
+    if total_limit is None:
+        return results
+
+    remaining_space = total_limit - total_fetched
+    return results[:remaining_space]
+
+
+def _has_reached_limit(total_limit: int | None, total_fetched: int) -> bool:
+    if total_limit is None:
+        return False
+    return total_fetched >= total_limit
+
+
+def _create_limited_response(
+    original: PaginatedResponse,
+    limited_results: list[Any],
+    api_page_size: int,
+) -> PaginatedResponse:
+    results_were_limited_by_client = len(limited_results) < len(original.results)
+    api_returned_full_page = len(original.results) == api_page_size
+
+    has_more_after_limit = original.has_more and not results_were_limited_by_client and api_returned_full_page
+
+    return PaginatedResponse(
+        results=limited_results,
+        has_more=has_more_after_limit,
+        next_cursor=original.next_cursor if has_more_after_limit else None,
+    )
+
+
 async def paginate_notion_api(
     api_call: Callable[..., Coroutine[Any, Any, PaginatedResponse]],
+    total_results_limit: int | None = None,
     **kwargs,
 ) -> list[Any]:
     all_results = []
-    async for page in _fetch_pages(api_call, **kwargs):
-        if page.results:
-            all_results.extend(page.results)
+    async for page in _fetch_data(api_call, total_results_limit=total_results_limit, **kwargs):
+        all_results.extend(page.results)
     return all_results
 
 
 async def paginate_notion_api_generator(
     api_call: Callable[..., Coroutine[Any, Any, PaginatedResponse]],
+    total_results_limit: int | None = None,
     **kwargs,
 ) -> AsyncGenerator[Any]:
-    async for page in _fetch_pages(api_call, **kwargs):
-        if page.results:
-            for item in page.results:
-                yield item
+    async for page in _fetch_data(api_call, total_results_limit, **kwargs):
+        for item in page.results:
+            yield item

notionary/workspace/__init__.py

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