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

notionary/workspace/client.py

@@ -1,9 +1,9 @@
 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.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
@@ -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
 
@@ -57,6 +59,6 @@ class WorkspaceClient:
         response = await self._execute_search(search_config)
         return DataSourceSearchResponse.model_validate(response)
 
-    async def _execute_search(self, config: WorkspaceQueryConfig) -> dict[str, Any]:
+    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 NotionWorkspaceQueryConfigBuilder
+
+__all__ = ["NotionWorkspaceQueryConfigBuilder"]

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,8 +1,14 @@
 from enum import StrEnum
-from typing import Any
+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"
@@ -24,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:
@@ -35,8 +44,8 @@ class WorkspaceQueryConfig(BaseModel):
         return value
 
     @model_serializer
-    def serialize_model(self) -> dict[str, Any]:
-        search_dict: dict[str, Any] = {}
+    def to_api_params(self) -> JsonDict:
+        search_dict: JsonDict = {}
 
         if self.query:
             search_dict["query"] = 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_best_match
+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()
@@ -48,46 +44,75 @@ class WorkspaceQueryService:
         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, min_similarity: float = 0.6) -> NotionDataSource:
-        config = WorkspaceQueryConfigBuilder().with_query(query).with_data_sources_only().with_page_size(5).build()
+    async def find_data_source(self, query: str) -> NotionDataSource:
+        config = (
+            NotionWorkspaceQueryConfigBuilder()
+            .with_query(query)
+            .with_data_sources_only()
+            .with_page_size(100)
+            .build()
+        )
         data_sources = await self.get_data_sources(config)
-
-        return self._get_best_match(
-            data_sources, query, exception_class=DataSourceNotFound, min_similarity=min_similarity
+        return self._find_exact_match(data_sources, query, DataSourceNotFound)
+
+    async def find_page(self, query: str) -> NotionPage:
+        config = (
+            NotionWorkspaceQueryConfigBuilder()
+            .with_query(query)
+            .with_pages_only()
+            .with_page_size(100)
+            .build()
         )
-
-    async def find_page(self, query: str, min_similarity: float = 0.6) -> NotionPage:
-        config = WorkspaceQueryConfigBuilder().with_query(query).with_pages_only().with_page_size(5).build()
         pages = await self.get_pages(config)
-
-        return self._get_best_match(pages, query, exception_class=PageNotFound, min_similarity=min_similarity)
-
-    async def find_database(self, query: str = "") -> NotionDatabase:
-        config = WorkspaceQueryConfigBuilder().with_query(query).with_data_sources_only().with_page_size(100).build()
+        return self._find_exact_match(pages, query, PageNotFound)
+
+    async def find_database(self, query: str) -> NotionDatabase:
+        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]
 
-        return self._get_best_match(potential_databases, query, exception_class=DatabaseNotFound)
+        return self._find_exact_match(potential_databases, query, DatabaseNotFound)
 
-    def _get_best_match(
+    def _find_exact_match(
         self,
         search_results: list[SearchableEntity],
         query: str,
         exception_class: type[Exception],
-        min_similarity: float | None = None,
     ) -> SearchableEntity:
-        best_match = find_best_match(
+        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 searchable_entity: searchable_entity.title,
-            min_similarity=min_similarity,
+            text_extractor=lambda entity: entity.title,
+            min_similarity=0.6,
         )
 
-        if not best_match:
-            available_titles = [result.title for result in search_results[:5]]
-            raise exception_class(query, available_titles)
+        if sorted_by_similarity:
+            return [result.title for result in sorted_by_similarity[:5]]
 
-        return best_match
+        return [result.title for result in search_results[:5]]

notionary/workspace/service.py

@@ -4,7 +4,7 @@ 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
 
@@ -13,7 +13,9 @@ if TYPE_CHECKING:
     from notionary.page.service import NotionPage
     from notionary.user import BotUser, PersonUser
 
-type _QueryConfigInput = WorkspaceQueryConfig | Callable[[WorkspaceQueryConfigBuilder], WorkspaceQueryConfigBuilder]
+type _QueryConfigInput = (
+    WorkspaceQueryConfig | Callable[[NotionWorkspaceQueryConfigBuilder], NotionWorkspaceQueryConfigBuilder]
+)
 
 
 class NotionWorkspace:
@@ -43,14 +45,14 @@ class NotionWorkspace:
         self,
         config: _QueryConfigInput | None = None,
     ) -> list[NotionPage]:
-        query_config = self._resolve_config(config, default_object_type_to_query=WorkspaceQueryObjectType.PAGE)
+        query_config = self._resolve_config(config, WorkspaceQueryObjectType.PAGE)
         return await self._query_service.get_pages(query_config)
 
     async def get_pages_stream(
         self,
         config: _QueryConfigInput | None = None,
     ) -> AsyncIterator[NotionPage]:
-        query_config = self._resolve_config(config, default_object_type_to_query=WorkspaceQueryObjectType.PAGE)
+        query_config = self._resolve_config(config, WorkspaceQueryObjectType.PAGE)
         async for page in self._query_service.get_pages_stream(query_config):
             yield page
 
@@ -58,41 +60,49 @@ class NotionWorkspace:
         self,
         config: _QueryConfigInput | None = None,
     ) -> list[NotionDataSource]:
-        query_config = self._resolve_config(config, default_object_type_to_query=WorkspaceQueryObjectType.DATA_SOURCE)
+        query_config = self._resolve_config(config, WorkspaceQueryObjectType.DATA_SOURCE)
         return await self._query_service.get_data_sources(query_config)
 
     async def get_data_sources_stream(
         self,
         config: _QueryConfigInput | None = None,
     ) -> AsyncIterator[NotionDataSource]:
-        query_config = self._resolve_config(config, default_object_type_to_query=WorkspaceQueryObjectType.DATA_SOURCE)
+        query_config = self._resolve_config(config, WorkspaceQueryObjectType.DATA_SOURCE)
         async for data_source in self._query_service.get_data_sources_stream(query_config):
             yield data_source
 
     def _resolve_config(
         self,
         config: _QueryConfigInput | None,
-        default_object_type_to_query: WorkspaceQueryObjectType,
+        expected_object_type: WorkspaceQueryObjectType,
     ) -> WorkspaceQueryConfig:
-        if isinstance(config, WorkspaceQueryConfig):
-            return config
-
-        builder = self._create_builder_with_defaults(default_object_type_to_query)
+        if config is None:
+            return self._create_default_config(expected_object_type)
 
-        if callable(config):
-            config(builder)
+        if isinstance(config, WorkspaceQueryConfig):
+            return self._ensure_correct_object_type(config, expected_object_type)
 
-        return builder.build()
+        return self._build_config_from_callable(config, expected_object_type)
 
-    def _create_builder_with_defaults(self, object_type: WorkspaceQueryObjectType) -> WorkspaceQueryConfigBuilder:
-        builder = WorkspaceQueryConfigBuilder()
+    def _create_default_config(self, object_type: WorkspaceQueryObjectType) -> WorkspaceQueryConfig:
+        return WorkspaceQueryConfig(object_type=object_type)
 
-        if object_type == WorkspaceQueryObjectType.PAGE:
-            builder.with_pages_only()
-        else:
-            builder.with_data_sources_only()
+    def _build_config_from_callable(
+        self,
+        config_callable: Callable[[NotionWorkspaceQueryConfigBuilder], NotionWorkspaceQueryConfigBuilder],
+        expected_object_type: WorkspaceQueryObjectType,
+    ) -> WorkspaceQueryConfig:
+        builder = NotionWorkspaceQueryConfigBuilder()
+        config_callable(builder)
+        return self._ensure_correct_object_type(builder.build(), expected_object_type)
 
-        return builder
+    def _ensure_correct_object_type(
+        self,
+        config: WorkspaceQueryConfig,
+        expected_object_type: WorkspaceQueryObjectType,
+    ) -> WorkspaceQueryConfig:
+        config.object_type = expected_object_type
+        return config
 
     async def get_users(self) -> list[PersonUser]:
         return [user async for user in self._user_service.list_users_stream()]

{notionary-0.2.28.dist-info → notionary-0.3.1.dist-info}/METADATA

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: notionary
-Version: 0.2.28
+Version: 0.3.1
 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.
@@ -61,17 +65,9 @@ export NOTION_SECRET=your_integration_key
 
 ## See It in Action
 
-### Creating Rich Database Entries
-
 https://github.com/user-attachments/assets/da8b4691-bee4-4b0f-801e-dccacb630398
 
-_Create styled project pages with properties, content, and rich formatting_
-
-### Local File Uploads (Videos & Images)
-
-https://github.com/user-attachments/assets/a079ec01-bb56-4c65-8260-7b1fca42ac68
-
-_Upload videos and images using simple markdown syntax - files are automatically uploaded to Notion_
+_Create rich database entries with properties, content, and beautiful formatting_
 
 ---
 
@@ -80,50 +76,30 @@ _Upload videos and images using simple markdown syntax - files are automatically
 ### Find → Create → Update Flow
 
 ```python
-import asyncio
-from notionary import NotionPage, NotionDatabase
-
-async def main():
-    # Find pages by name - fuzzy matching included!
-    page = await NotionPage.from_title("Meeting Notes")
-
-    # Option 1: Direct Extended Markdown
-    await page.append_markdown("""
-    ## Action Items
-    - [x] Review project proposal
-    - [ ] Schedule team meeting
-    - [ ] Update documentation
-
-    [callout](Meeting decisions require follow-up "💡")
-
-    +++ Details
-    Additional context and next steps...
-    +++
-    """)
-
-    # Option 2: Type-Safe Builder (maps to same markdown internally)
-    await page.append_markdown(lambda builder: (
-        builder
-        .h2("Project Status")
-        .callout("Milestone reached!", "🎉")
-        .columns(
-            lambda col: col.h3("Completed").bulleted_list([
-                "API design", "Database setup", "Authentication"
-            ]),
-            lambda col: col.h3("In Progress").bulleted_list([
-                "Frontend UI", "Testing", "Documentation"
-            ]),
-            width_ratios=[0.6, 0.4]
-        )
-        .toggle("Budget Details", lambda t: t
-            .table(["Item", "Cost", "Status"], [
-                ["Development", "$15,000", "Paid"],
-                ["Design", "$8,000", "Pending"]
-            ])
-        )
-    ))
-
-asyncio.run(main())
+from notionary import NotionPage
+
+# Find pages by name with fuzzy matching
+page = await NotionPage.from_title("Meeting Notes")
+
+# Define rich content with extended markdown
+content = """
+## Action Items
+- [x] Review proposal
+- [ ] Schedule meeting
+
+[callout](Key decision made! "💡")
+
+| Task | Owner | Deadline |
+|------|-------|----------|
+| Design Review | Alice | 2024-03-15 |
+| Implementation | Bob | 2024-03-22 |
+
++++ Budget Details
+See attached spreadsheet...
++++
+"""
+
+await page.append_markdown(content)
 ```
 
 ### Complete Block Support
@@ -132,36 +108,13 @@ Every Notion block type with extended syntax:
 
 | Block Type    | Markdown Syntax                              | Use Case                     |
 | ------------- | -------------------------------------------- | ---------------------------- |
-| **Callouts**  | `[callout](Text "🔥")`                       | Highlighting key information |
 | **Toggles**   | `+++ Title\nContent\n+++`                    | Collapsible sections         |
 | **Columns**   | `::: columns\n::: column\nContent\n:::\n:::` | Side-by-side layouts         |
 | **Tables**    | Standard markdown tables                     | Structured data              |
 | **Media**     | `[video](./file.mp4)(caption:Description)`   | Auto-uploading files         |
 | **Code**      | Standard code fences with captions           | Code snippets                |
 | **Equations** | `$LaTeX$`                                    | Mathematical expressions     |
-| **TOC**       | `[toc](blue_background)`                     | Auto-generated navigation    |
-
----
-
-## What You Can Build 💡
-
-### **AI Content Systems**
-
-- **Report Generation**: AI agents that create structured reports, documentation, and analysis
-- **Content Pipelines**: Automated workflows that process data and generate Notion pages
-- **Knowledge Management**: AI-powered documentation systems with smart categorization
-
-### **Workflow Automation**
-
-- **Project Management**: Sync project status, update timelines, generate progress reports
-- **Data Integration**: Connect external APIs and databases to Notion workspaces
-- **Template Systems**: Dynamic page generation from templates and data sources
-
-### **Content Management**
-
-- **Bulk Operations**: Mass page updates, content migration, and database management
-- **Media Handling**: Automated image/video uploads with proper organization
-- **Cross-Platform**: Sync content between Notion and other platforms
+| **TOC**       | `[toc]`                     | Auto-generated navigation    |
 
 ---
 
@@ -222,29 +175,6 @@ Every Notion block type with extended syntax:
 
 [**mathisarends.github.io/notionary**](https://mathisarends.github.io/notionary/) - Complete API reference, guides, and tutorials
 
-### Quick Links
-
-- [**Getting Started**](https://mathisarends.github.io/notionary/get-started/) - Setup and first steps
-- [**Page Management**](https://mathisarends.github.io/notionary/page/) - Content and properties
-- [**Database Operations**](https://mathisarends.github.io/notionary/database/) - Queries and management
-- [**Block Types Reference**](https://mathisarends.github.io/notionary/blocks/) - Complete syntax guide
-
-### Hands-On Examples
-
-**Core Functionality:**
-
-- [Page Management](examples/page_example.py) - Create, update, and manage pages
-- [Database Operations](examples/database.py) - Connect and query databases
-- [Workspace Discovery](examples/workspace_discovery.py) - Explore your workspace
-
-**Extended Markdown:**
-
-- [Basic Formatting](examples/markdown/basic.py) - Text, lists, and links
-- [Callouts & Highlights](examples/markdown/callout.py) - Information boxes
-- [Toggle Sections](examples/markdown/toggle.py) - Collapsible content
-- [Multi-Column Layouts](examples/markdown/columns.py) - Side-by-side design
-- [Tables & Data](examples/markdown/table.py) - Structured presentations
-
 ---
 
 ## Contributing