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

notionary/utils/pagination.py

@@ -12,89 +12,93 @@ class PaginatedResponse(BaseModel):
 
 async def _fetch_data(
     api_call: Callable[..., Coroutine[Any, Any, PaginatedResponse]],
-    page_size: int | None = None,
+    total_results_limit: int | None = None,
     **kwargs,
 ) -> AsyncGenerator[PaginatedResponse]:
-    next_cursor = None
-    has_more = True
-    total_fetched = 0
+    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 and _should_continue_fetching(page_size, total_fetched):
-        request_params = _build_request_params(kwargs, next_cursor, page_size)
+    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)
 
-        limited_results = _apply_result_limit(response.results, page_size, total_fetched)
+        limited_results = _apply_result_limit(response.results, total_results_limit, total_fetched)
         total_fetched += len(limited_results)
 
-        yield _create_limited_response(response, limited_results)
+        yield _create_limited_response(response, limited_results, api_page_size)
 
-        if _has_reached_limit(page_size, total_fetched):
+        if _has_reached_limit(total_results_limit, 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:
+def _should_continue_fetching(total_limit: int | None, total_fetched: int) -> bool:
+    if total_limit is None:
         return True
-    return total_fetched < page_size
+    return total_fetched < total_limit
 
 
 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:
+def _apply_result_limit(results: list[Any], total_limit: int | None, total_fetched: int) -> list[Any]:
+    if total_limit is None:
         return results
 
-    remaining = page_size - total_fetched
-    return results[:remaining]
+    remaining_space = total_limit - total_fetched
+    return results[:remaining_space]
 
 
-def _has_reached_limit(page_size: int | None, total_fetched: int) -> bool:
-    if page_size is None:
+def _has_reached_limit(total_limit: int | None, total_fetched: int) -> bool:
+    if total_limit is None:
         return False
-    return total_fetched >= page_size
+    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
 
-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,
+        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]],
-    page_size: int | None = None,
+    total_results_limit: int | None = None,
     **kwargs,
 ) -> list[Any]:
     all_results = []
-    async for page in _fetch_data(api_call, page_size=page_size, **kwargs):
+    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]],
-    page_size: int | None = None,
+    total_results_limit: int | None = None,
     **kwargs,
 ) -> AsyncGenerator[Any]:
-    async for page in _fetch_data(api_call, page_size=page_size, **kwargs):
+    async for page in _fetch_data(api_call, total_results_limit, **kwargs):
         for item in page.results:
             yield item

notionary/workspace/__init__.py

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

notionary/workspace/client.py

@@ -22,6 +22,7 @@ class WorkspaceClient:
         async for page in paginate_notion_api_generator(
             self._query_pages,
             search_config=search_config,
+            total_results_limit=search_config.total_results_limit,
         ):
             yield page
 
@@ -32,6 +33,7 @@ class WorkspaceClient:
         async for data_source in paginate_notion_api_generator(
             self._query_data_sources,
             search_config=search_config,
+            total_results_limit=search_config.total_results_limit,
         ):
             yield data_source
 

notionary/workspace/query/__init__.py

@@ -1,3 +1,4 @@
-from .builder import WorkspaceQueryConfigBuilder
+from .builder import NotionWorkspaceQueryConfigBuilder
+from .models import WorkspaceQueryConfig
 
-__all__ = ["WorkspaceQueryConfigBuilder"]
+__all__ = ["NotionWorkspaceQueryConfigBuilder", "WorkspaceQueryConfig"]

notionary/workspace/query/builder.py

@@ -8,7 +8,7 @@ from notionary.workspace.query.models import (
 )
 
 
-class WorkspaceQueryConfigBuilder:
+class NotionWorkspaceQueryConfigBuilder:
     def __init__(self, config: WorkspaceQueryConfig = None) -> None:
         self.config = config or WorkspaceQueryConfig()
 
@@ -16,6 +16,10 @@ class WorkspaceQueryConfigBuilder:
         self.config.query = query
         return self
 
+    def with_total_results_limit(self, limit: int) -> Self:
+        self.config.total_results_limit = limit
+        return self
+
     def with_pages_only(self) -> Self:
         self.config.object_type = WorkspaceQueryObjectType.PAGE
         return self
@@ -44,6 +48,26 @@ class WorkspaceQueryConfigBuilder:
     def with_sort_by_last_edited(self) -> Self:
         return self.with_sort_timestamp(SortTimestamp.LAST_EDITED_TIME)
 
+    def with_sort_by_created_time_ascending(self) -> Self:
+        self.config.sort_timestamp = SortTimestamp.CREATED_TIME
+        self.config.sort_direction = SortDirection.ASCENDING
+        return self
+
+    def with_sort_by_created_time_descending(self) -> Self:
+        self.config.sort_timestamp = SortTimestamp.CREATED_TIME
+        self.config.sort_direction = SortDirection.DESCENDING
+        return self
+
+    def with_sort_by_last_edited_ascending(self) -> Self:
+        self.config.sort_timestamp = SortTimestamp.LAST_EDITED_TIME
+        self.config.sort_direction = SortDirection.ASCENDING
+        return self
+
+    def with_sort_by_last_edited_descending(self) -> Self:
+        self.config.sort_timestamp = SortTimestamp.LAST_EDITED_TIME
+        self.config.sort_direction = SortDirection.DESCENDING
+        return self
+
     def with_page_size(self, size: int) -> Self:
         self.config.page_size = min(size, 100)
         return self

notionary/workspace/query/models.py

@@ -1,10 +1,15 @@
 from enum import StrEnum
+from typing import Protocol
 
 from pydantic import BaseModel, Field, field_validator, model_serializer
 
 from notionary.shared.typings import JsonDict
 
 
+class SearchableEntity(Protocol):
+    title: str
+
+
 class SortDirection(StrEnum):
     ASCENDING = "ascending"
     DESCENDING = "descending"
@@ -25,9 +30,12 @@ class WorkspaceQueryConfig(BaseModel):
     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
 
+    total_results_limit: int | None = None
+
     @field_validator("query")
     @classmethod
     def replace_empty_query_with_none(cls, value: str | None) -> str | None:
@@ -36,7 +44,7 @@ class WorkspaceQueryConfig(BaseModel):
         return value
 
     @model_serializer
-    def serialize_model(self) -> JsonDict:
+    def to_api_params(self) -> JsonDict:
         search_dict: JsonDict = {}
 
         if self.query:

notionary/workspace/query/service.py

@@ -2,22 +2,18 @@ from __future__ import annotations
 
 import asyncio
 from collections.abc import AsyncIterator
-from typing import TYPE_CHECKING, Protocol
+from typing import TYPE_CHECKING
 
 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
+from notionary.workspace.query.builder import NotionWorkspaceQueryConfigBuilder
+from notionary.workspace.query.models import SearchableEntity, 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()
@@ -49,20 +45,28 @@ class WorkspaceQueryService:
         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()
+        config = (
+            NotionWorkspaceQueryConfigBuilder().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()
+        config = NotionWorkspaceQueryConfigBuilder().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()
+        config = (
+            NotionWorkspaceQueryConfigBuilder().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_database_ids = [data_sources.get_parent_database_id_if_present() for data_sources in data_sources]
+        # filter none values which should not happen but for safety
+        parent_database_ids = [id for id in parent_database_ids if id is not None]
+
+        parent_database_tasks = [NotionDatabase.from_id(db_id) for db_id in parent_database_ids]
         parent_databases = await asyncio.gather(*parent_database_tasks)
         potential_databases = [database for database in parent_databases if database is not None]
 

notionary/workspace/service.py

@@ -4,17 +4,14 @@ from collections.abc import AsyncIterator, Callable
 from typing import TYPE_CHECKING, Self
 
 from notionary.user.service import UserService
-from notionary.workspace.query.builder import WorkspaceQueryConfigBuilder
+from notionary.workspace.query.builder import NotionWorkspaceQueryConfigBuilder
 from notionary.workspace.query.models import WorkspaceQueryConfig, WorkspaceQueryObjectType
 from notionary.workspace.query.service import WorkspaceQueryService
 
 if TYPE_CHECKING:
-    from notionary.data_source.service import NotionDataSource
-    from notionary.page.service import NotionPage
+    from notionary import NotionDataSource, NotionPage
     from notionary.user import BotUser, PersonUser
 
-type _QueryConfigInput = WorkspaceQueryConfig | Callable[[WorkspaceQueryConfigBuilder], WorkspaceQueryConfigBuilder]
-
 
 class NotionWorkspace:
     def __init__(
@@ -41,58 +38,71 @@ class NotionWorkspace:
 
     async def get_pages(
         self,
-        config: _QueryConfigInput | None = None,
+        *,
+        filter_fn: Callable[[NotionWorkspaceQueryConfigBuilder], NotionWorkspaceQueryConfigBuilder] | None = None,
+        query_config: WorkspaceQueryConfig | None = None,
     ) -> list[NotionPage]:
-        query_config = self._resolve_config(config, default_object_type_to_query=WorkspaceQueryObjectType.PAGE)
-        return await self._query_service.get_pages(query_config)
+        if filter_fn is not None and query_config is not None:
+            raise ValueError("Use either filter_fn OR query_config, not both")
+
+        resolved_config = self._resolve_query_config(filter_fn, query_config, WorkspaceQueryObjectType.PAGE)
+        return await self._query_service.get_pages(resolved_config)
 
     async def get_pages_stream(
         self,
-        config: _QueryConfigInput | None = None,
+        *,
+        filter_fn: Callable[[NotionWorkspaceQueryConfigBuilder], NotionWorkspaceQueryConfigBuilder] | None = None,
+        query_config: WorkspaceQueryConfig | None = None,
     ) -> AsyncIterator[NotionPage]:
-        query_config = self._resolve_config(config, default_object_type_to_query=WorkspaceQueryObjectType.PAGE)
-        async for page in self._query_service.get_pages_stream(query_config):
+        if filter_fn is not None and query_config is not None:
+            raise ValueError("Use either filter_fn OR query_config, not both")
+
+        resolved_config = self._resolve_query_config(filter_fn, query_config, WorkspaceQueryObjectType.PAGE)
+        async for page in self._query_service.get_pages_stream(resolved_config):
             yield page
 
     async def get_data_sources(
         self,
-        config: _QueryConfigInput | None = None,
+        *,
+        filter_fn: Callable[[NotionWorkspaceQueryConfigBuilder], NotionWorkspaceQueryConfigBuilder] | None = None,
+        query_config: WorkspaceQueryConfig | None = None,
     ) -> list[NotionDataSource]:
-        query_config = self._resolve_config(config, default_object_type_to_query=WorkspaceQueryObjectType.DATA_SOURCE)
-        return await self._query_service.get_data_sources(query_config)
+        if filter_fn is not None and query_config is not None:
+            raise ValueError("Use either filter_fn OR query_config, not both")
+
+        resolved_config = self._resolve_query_config(filter_fn, query_config, WorkspaceQueryObjectType.DATA_SOURCE)
+        return await self._query_service.get_data_sources(resolved_config)
 
     async def get_data_sources_stream(
         self,
-        config: _QueryConfigInput | None = None,
+        *,
+        filter_fn: Callable[[NotionWorkspaceQueryConfigBuilder], NotionWorkspaceQueryConfigBuilder] | None = None,
+        query_config: WorkspaceQueryConfig | None = None,
     ) -> AsyncIterator[NotionDataSource]:
-        query_config = self._resolve_config(config, default_object_type_to_query=WorkspaceQueryObjectType.DATA_SOURCE)
-        async for data_source in self._query_service.get_data_sources_stream(query_config):
+        if filter_fn is not None and query_config is not None:
+            raise ValueError("Use either filter_fn OR query_config, not both")
+
+        resolved_config = self._resolve_query_config(filter_fn, query_config, WorkspaceQueryObjectType.DATA_SOURCE)
+        async for data_source in self._query_service.get_data_sources_stream(resolved_config):
             yield data_source
 
-    def _resolve_config(
+    def _resolve_query_config(
         self,
-        config: _QueryConfigInput | None,
-        default_object_type_to_query: WorkspaceQueryObjectType,
+        filter_fn: Callable[[NotionWorkspaceQueryConfigBuilder], NotionWorkspaceQueryConfigBuilder] | None,
+        query_config: WorkspaceQueryConfig | None,
+        expected_object_type: WorkspaceQueryObjectType,
     ) -> WorkspaceQueryConfig:
-        if isinstance(config, WorkspaceQueryConfig):
-            return config
-
-        builder = self._create_builder_with_defaults(default_object_type_to_query)
-
-        if callable(config):
-            config(builder)
-
-        return builder.build()
-
-    def _create_builder_with_defaults(self, object_type: WorkspaceQueryObjectType) -> WorkspaceQueryConfigBuilder:
-        builder = WorkspaceQueryConfigBuilder()
+        if filter_fn is not None:
+            builder = NotionWorkspaceQueryConfigBuilder()
+            configured_builder = filter_fn(builder)
+            query_config = configured_builder.build()
 
-        if object_type == WorkspaceQueryObjectType.PAGE:
-            builder.with_pages_only()
+        if query_config is None:
+            query_config = WorkspaceQueryConfig(object_type=expected_object_type)
         else:
-            builder.with_data_sources_only()
+            query_config.object_type = expected_object_type
 
-        return builder
+        return query_config
 
     async def get_users(self) -> list[PersonUser]:
         return [user async for user in self._user_service.list_users_stream()]

{notionary-0.3.0.dist-info → notionary-0.4.0.dist-info}/METADATA

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: notionary
-Version: 0.3.0
+Version: 0.4.0
 Summary: Python library for programmatic Notion workspace management - databases, pages, and content with advanced Markdown support
 Project-URL: Homepage, https://github.com/mathisarends/notionary
 Author-email: Mathis Arends <mathisarends27@gmail.com>
 License: MIT
 License-File: LICENSE
-Requires-Python: >=3.11
+Requires-Python: >=3.12
 Requires-Dist: aiofiles<25.0.0,>=24.1.0
 Requires-Dist: httpx>=0.28.0
 Requires-Dist: pydantic>=2.11.4
@@ -23,9 +23,13 @@ Description-Content-Type: text/markdown
 
 <div align="center">
 
-[![Python Version](https://img.shields.io/badge/python-3.8%2B-blue.svg)](https://www.python.org/downloads/)
-[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
-[![Documentation](https://img.shields.io/badge/docs-mathisarends.github.io-blue.svg)](https://mathisarends.github.io/notionary/)
+[![PyPI version](https://badge.fury.io/py/notionary.svg)](https://badge.fury.io/py/notionary)
+[![Python Version](https://img.shields.io/badge/python-3.12%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Coverage](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/mathisarends/fc0568b66a20fbbaa5018205861c0da9/raw/notionary-coverage.json)](https://github.com/mathisarends/notionary)
+[![Downloads](https://img.shields.io/pypi/dm/notionary?color=blue)](https://pypi.org/project/notionary/)
+[![Documentation](https://img.shields.io/badge/docs-notionary-blue?style=flat&logo=readthedocs)](https://mathisarends.github.io/notionary/)
+[![Notion API](https://img.shields.io/badge/Notion%20API-Official-000000?logo=notion&logoColor=white)](https://developers.notion.com/)
 
 **Transform complex Notion API interactions into simple, Pythonic code.**
 Perfect for developers building AI agents, automation workflows, and dynamic content systems.