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

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

@@ -0,0 +1,68 @@
+import difflib
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Generic, TypeVar
+
+T = TypeVar("T")
+
+
+@dataclass(frozen=True)
+class _MatchResult(Generic[T]):
+    item: T
+    similarity: float
+
+
+def find_best_match(
+    query: str,
+    items: list[T],
+    text_extractor: Callable[[T], str],
+    min_similarity: float,
+) -> T | None:
+    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],
+    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(
+        isjunk=None,
+        a=query.lower().strip(),
+        b=target.lower().strip(),
+    ).ratio()

notionary/utils/mixins/logging.py

@@ -0,0 +1,58 @@
+import logging
+import os
+from typing import ClassVar
+
+from dotenv import load_dotenv
+
+load_dotenv(override=True)
+
+logger = logging.getLogger("notionary")
+logger.addHandler(logging.NullHandler())
+
+
+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:
+    logger: ClassVar[logging.Logger] = None
+
+    def __init_subclass__(cls, **kwargs):
+        super().__init_subclass__(**kwargs)
+        cls.logger = logging.getLogger(f"notionary.{cls.__name__}")
+
+    @property
+    def instance_logger(self) -> logging.Logger:
+        if not hasattr(self, "_logger"):
+            self._logger = logging.getLogger(f"notionary.{self.__class__.__name__}")
+        return self._logger

notionary/utils/pagination.py

@@ -0,0 +1,100 @@
+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_data(
+    api_call: Callable[..., Coroutine[Any, Any, PaginatedResponse]],
+    page_size: int | None = None,
+    **kwargs,
+) -> AsyncGenerator[PaginatedResponse]:
+    next_cursor = None
+    has_more = True
+    total_fetched = 0
+
+    while has_more and _should_continue_fetching(page_size, total_fetched):
+        request_params = _build_request_params(kwargs, next_cursor, page_size)
+        response = await api_call(**request_params)
+
+        limited_results = _apply_result_limit(response.results, page_size, total_fetched)
+        total_fetched += len(limited_results)
+
+        yield _create_limited_response(response, limited_results)
+
+        if _has_reached_limit(page_size, total_fetched):
+            break
+
+        has_more = response.has_more
+        next_cursor = response.next_cursor
+
+
+def _should_continue_fetching(page_size: int | None, total_fetched: int) -> bool:
+    if page_size is None:
+        return True
+    return total_fetched < page_size
+
+
+def _build_request_params(
+    base_kwargs: dict[str, Any],
+    cursor: str | None,
+    page_size: int | None,
+) -> dict[str, Any]:
+    params = base_kwargs.copy()
+
+    if cursor:
+        params["start_cursor"] = cursor
+
+    if page_size:
+        params["page_size"] = page_size
+
+    return params
+
+
+def _apply_result_limit(results: list[Any], page_size: int | None, total_fetched: int) -> list[Any]:
+    if page_size is None:
+        return results
+
+    remaining = page_size - total_fetched
+    return results[:remaining]
+
+
+def _has_reached_limit(page_size: int | None, total_fetched: int) -> bool:
+    if page_size is None:
+        return False
+    return total_fetched >= page_size
+
+
+def _create_limited_response(original: PaginatedResponse, limited_results: list[Any]) -> PaginatedResponse:
+    return PaginatedResponse(
+        results=limited_results,
+        has_more=original.has_more and len(limited_results) == len(original.results),
+        next_cursor=original.next_cursor,
+    )
+
+
+async def paginate_notion_api(
+    api_call: Callable[..., Coroutine[Any, Any, PaginatedResponse]],
+    page_size: int | None = None,
+    **kwargs,
+) -> list[Any]:
+    all_results = []
+    async for page in _fetch_data(api_call, page_size=page_size, **kwargs):
+        all_results.extend(page.results)
+    return all_results
+
+
+async def paginate_notion_api_generator(
+    api_call: Callable[..., Coroutine[Any, Any, PaginatedResponse]],
+    page_size: int | None = None,
+    **kwargs,
+) -> AsyncGenerator[Any]:
+    async for page in _fetch_data(api_call, page_size=page_size, **kwargs):
+        for item in page.results:
+            yield item

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,4 @@
+from .query import WorkspaceQueryConfigBuilder
+from .service import NotionWorkspace
+
+__all__ = ["NotionWorkspace", "WorkspaceQueryConfigBuilder"]

notionary/workspace/client.py

@@ -0,0 +1,62 @@
+from collections.abc import AsyncGenerator
+
+from notionary.data_source.schemas import DataSourceDto
+from notionary.http.client import NotionHttpClient
+from notionary.page.schemas import NotionPageDto
+from notionary.shared.typings import JsonDict
+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) -> JsonDict:
+        serialized_config = config.model_dump(exclude_none=True, by_alias=True)
+        return await self._http_client.post("search", serialized_config)

notionary/workspace/query/__init__.py

@@ -0,0 +1,3 @@
+from .builder import WorkspaceQueryConfigBuilder
+
+__all__ = ["WorkspaceQueryConfigBuilder"]

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,61 @@
+from enum import StrEnum
+
+from pydantic import BaseModel, Field, field_validator, model_serializer
+
+from notionary.shared.typings import JsonDict
+
+
+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) -> JsonDict:
+        search_dict: JsonDict = {}
+
+        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

notionary/workspace/query/service.py

@@ -0,0 +1,100 @@
+from __future__ import annotations
+
+import asyncio
+from collections.abc import AsyncIterator
+from typing import TYPE_CHECKING, Protocol
+
+from notionary.exceptions.search import DatabaseNotFound, DataSourceNotFound, PageNotFound
+from notionary.utils.fuzzy import find_all_matches
+from notionary.workspace.client import WorkspaceClient
+from notionary.workspace.query.builder import WorkspaceQueryConfigBuilder
+from notionary.workspace.query.models import WorkspaceQueryConfig
+
+if TYPE_CHECKING:
+    from notionary import NotionDatabase, NotionDataSource, NotionPage
+
+
+class SearchableEntity(Protocol):
+    title: str
+
+
+class WorkspaceQueryService:
+    def __init__(self, client: WorkspaceClient | None = None) -> None:
+        self._client = client or WorkspaceClient()
+
+    async def get_pages_stream(self, search_config: WorkspaceQueryConfig) -> AsyncIterator[NotionPage]:
+        from notionary import NotionPage
+
+        async for page_dto in self._client.query_pages_stream(search_config):
+            yield await NotionPage.from_id(page_dto.id)
+
+    async def get_pages(self, search_config: WorkspaceQueryConfig) -> list[NotionPage]:
+        from notionary import NotionPage
+
+        page_dtos = [dto async for dto in self._client.query_pages_stream(search_config)]
+        page_tasks = [NotionPage.from_id(dto.id) for dto in page_dtos]
+        return await asyncio.gather(*page_tasks)
+
+    async def get_data_sources_stream(self, search_config: WorkspaceQueryConfig) -> AsyncIterator[NotionDataSource]:
+        from notionary import NotionDataSource
+
+        async for data_source_dto in self._client.query_data_sources_stream(search_config):
+            yield await NotionDataSource.from_id(data_source_dto.id)
+
+    async def get_data_sources(self, search_config: WorkspaceQueryConfig) -> list[NotionDataSource]:
+        from notionary import NotionDataSource
+
+        data_source_dtos = [dto async for dto in self._client.query_data_sources_stream(search_config)]
+        data_source_tasks = [NotionDataSource.from_id(dto.id) for dto in data_source_dtos]
+        return await asyncio.gather(*data_source_tasks)
+
+    async def find_data_source(self, query: str) -> NotionDataSource:
+        config = WorkspaceQueryConfigBuilder().with_query(query).with_data_sources_only().with_page_size(100).build()
+        data_sources = await self.get_data_sources(config)
+        return self._find_exact_match(data_sources, query, DataSourceNotFound)
+
+    async def find_page(self, query: str) -> NotionPage:
+        config = WorkspaceQueryConfigBuilder().with_query(query).with_pages_only().with_page_size(100).build()
+        pages = await self.get_pages(config)
+        return self._find_exact_match(pages, query, PageNotFound)
+
+    async def find_database(self, query: str) -> NotionDatabase:
+        config = WorkspaceQueryConfigBuilder().with_query(query).with_data_sources_only().with_page_size(100).build()
+        data_sources = await self.get_data_sources(config)
+
+        parent_database_tasks = [data_source.get_parent_database() for data_source in data_sources]
+        parent_databases = await asyncio.gather(*parent_database_tasks)
+        potential_databases = [database for database in parent_databases if database is not None]
+
+        return self._find_exact_match(potential_databases, query, DatabaseNotFound)
+
+    def _find_exact_match(
+        self,
+        search_results: list[SearchableEntity],
+        query: str,
+        exception_class: type[Exception],
+    ) -> SearchableEntity:
+        if not search_results:
+            raise exception_class(query, [])
+
+        query_lower = query.lower()
+        exact_matches = [result for result in search_results if result.title.lower() == query_lower]
+
+        if exact_matches:
+            return exact_matches[0]
+
+        suggestions = self._get_fuzzy_suggestions(search_results, query)
+        raise exception_class(query, suggestions)
+
+    def _get_fuzzy_suggestions(self, search_results: list[SearchableEntity], query: str) -> list[str]:
+        sorted_by_similarity = find_all_matches(
+            query=query,
+            items=search_results,
+            text_extractor=lambda entity: entity.title,
+            min_similarity=0.6,
+        )
+
+        if sorted_by_similarity:
+            return [result.title for result in sorted_by_similarity[:5]]
+
+        return [result.title for result in search_results[:5]]

notionary/workspace/schemas.py

@@ -0,0 +1,21 @@
+from typing import Generic, Literal, TypeVar
+
+from pydantic import BaseModel
+
+from notionary.data_source.schemas import DataSourceDto
+from notionary.page.schemas import NotionPageDto
+
+T = TypeVar("T", bound=BaseModel)
+
+PageOrDataSource = DataSourceDto | NotionPageDto
+
+
+class SearchResponse(BaseModel, Generic[T]):
+    results: list[T]
+    next_cursor: str | None = None
+    has_more: bool
+    type: Literal["page_or_data_source"]
+
+
+PageSearchResponse = SearchResponse[NotionPageDto]
+DataSourceSearchResponse = SearchResponse[DataSourceDto]