notionary 0.2.21__py3-none-any.whl → 0.2.23__py3-none-any.whl

notionary/shared/name_to_id_resolver.py

@@ -0,0 +1,203 @@
+from __future__ import annotations
+
+from typing import Optional
+
+from notionary.user.notion_user_manager import NotionUserManager
+from notionary.util import format_uuid
+from notionary.util.fuzzy import find_best_match
+
+
+class NameIdResolver:
+    """
+    Bidirectional resolver for Notion page and database names and IDs.
+    """
+
+    def __init__(
+        self,
+        *,
+        token: Optional[str] = None,
+        search_limit: int = 10,
+    ):
+        """
+        Initialize the resolver with a Notion workspace.
+        """
+        from notionary import NotionWorkspace
+
+        self.workspace = NotionWorkspace(token=token)
+        self.notion_user_manager = NotionUserManager(token=token)
+        self.search_limit = search_limit
+
+    async def resolve_page_id(self, name: str) -> Optional[str]:
+        """
+        Convert a page name to its Notion page ID.
+        Specifically searches only pages, not databases.
+        """
+        if not name:
+            return None
+
+        cleaned_name = name.strip()
+
+        # Return if already a valid Notion ID
+        formatted_uuid = format_uuid(cleaned_name)
+        if formatted_uuid:
+            return formatted_uuid
+
+        # Search for page by name
+        return await self._resolve_page_id(cleaned_name)
+
+    async def resolve_database_id(self, name: str) -> Optional[str]:
+        """
+        Convert a database name to its Notion database ID.
+        Specifically searches only databases, not pages.
+        """
+        if not name:
+            return None
+
+        cleaned_name = name.strip()
+
+        formatted_uuid = format_uuid(cleaned_name)
+        if formatted_uuid:
+            return formatted_uuid
+
+        return await self._resolve_database_id(cleaned_name)
+
+    async def resolve_page_name(self, page_id: str) -> Optional[str]:
+        """
+        Convert a Notion page ID to its human-readable title.
+        """
+        if not page_id:
+            return None
+
+        formatted_id = format_uuid(page_id)
+        if not formatted_id:
+            return None
+
+        try:
+            from notionary import NotionPage
+
+            page = await NotionPage.from_page_id(formatted_id)
+            return page.title if page else None
+        except Exception:
+            return None
+
+    async def resolve_database_name(self, database_id: str) -> Optional[str]:
+        """
+        Convert a Notion database ID to its human-readable title.
+        """
+        if not database_id:
+            return None
+
+        # Validate and format UUID
+        formatted_id = format_uuid(database_id)
+        if not formatted_id:
+            return None
+
+        try:
+            from notionary.database import NotionDatabase
+
+            database = await NotionDatabase.from_database_id(formatted_id)
+            return database.title if database else None
+        except Exception:
+            return None
+
+    async def resolve_user_id(self, name: str) -> Optional[str]:
+        """
+        Convert a user name to its Notion user ID.
+        Specifically searches only users.
+        """
+        if not name:
+            return None
+
+        cleaned_name = name.strip()
+
+        # Return if already a valid Notion ID
+        formatted_uuid = format_uuid(cleaned_name)
+        if formatted_uuid:
+            return formatted_uuid
+
+        # Search for user by name
+        return await self._resolve_user_id(cleaned_name)
+
+    async def resolve_user_name(self, user_id: str) -> Optional[str]:
+        """
+        Convert a Notion user ID to its human-readable name.
+
+        Args:
+            user_id: Notion user ID to resolve
+
+        Returns:
+            User name if found, None if not found or inaccessible
+        """
+        if not user_id:
+            return None
+
+        # Validate and format UUID
+        formatted_id = format_uuid(user_id)
+        if not formatted_id:
+            return None
+
+        try:
+            user = await self.notion_user_manager.get_user_by_id(formatted_id)
+            return user.name if user else None
+        except Exception:
+            return None
+
+    async def _resolve_user_id(self, name: str) -> Optional[str]:
+        """Search for users matching the name."""
+        try:
+            users = await self.notion_user_manager.find_users_by_name(name)
+
+            if not users:
+                return None
+
+            # Use fuzzy matching to find best match
+            best_match = find_best_match(
+                query=name,
+                items=users,
+                text_extractor=lambda user: user.name or "",
+            )
+
+            return best_match.item.id if best_match else None
+        except Exception:
+            return None
+
+    async def _resolve_page_id(self, name: str) -> Optional[str]:
+        """Search for pages matching the name."""
+        search_results = await self.workspace.search_pages(
+            query=name, limit=self.search_limit
+        )
+
+        return self._find_best_fuzzy_match(query=name, candidate_objects=search_results)
+
+    async def _resolve_database_id(self, name: str) -> Optional[str]:
+        """Search for databases matching the name."""
+        search_results = await self.workspace.search_databases(
+            query=name, limit=self.search_limit
+        )
+
+        return self._find_best_fuzzy_match(query=name, candidate_objects=search_results)
+
+    def _find_best_fuzzy_match(
+        self, query: str, candidate_objects: list
+    ) -> Optional[str]:
+        """
+        Find the best fuzzy match among candidate objects using existing fuzzy matching logic.
+
+        Args:
+            query: The search query to match against
+            candidate_objects: Objects (pages or databases) with .id and .title attributes
+
+        Returns:
+            ID of best match, or None if no match meets threshold
+        """
+        if not candidate_objects:
+            return None
+
+        # Use existing fuzzy matching logic
+        best_match = find_best_match(
+            query=query,
+            items=candidate_objects,
+            text_extractor=lambda obj: obj.title,
+        )
+
+        return best_match.item.id if best_match else None

notionary/telemetry/service.py

@@ -1,7 +1,6 @@
 import os
 import uuid
 from pathlib import Path
-from typing import Any, Dict, Optional
 
 from dotenv import load_dotenv
 from posthog import Posthog

notionary/user/notion_user_manager.py

@@ -1,7 +1,6 @@
-from typing import Any, Dict, List, Optional
+from typing import Optional
 
 from notionary.user.client import NotionUserClient
-from notionary.user.models import NotionUsersListResponse
 from notionary.user.notion_user import NotionUser
 from notionary.util import LoggingMixin
 
@@ -18,72 +17,52 @@ class NotionUserManager(LoggingMixin):
         """Initialize the user manager."""
         self.client = NotionUserClient(token=token)
 
-    async def get_current_bot_user(self) -> Optional[NotionUser]:
-        """
-        Get the current bot user from the API token.
-        """
-        return await NotionUser.current_bot_user(token=self.client.token)
-
     async def get_user_by_id(self, user_id: str) -> Optional[NotionUser]:
         """
         Get a specific user by their ID.
         """
         return await NotionUser.from_user_id(user_id, token=self.client.token)
 
-    async def list_users(
-        self, page_size: int = 100, start_cursor: Optional[str] = None
-    ) -> Optional[NotionUsersListResponse]:
-        """
-        List users in the workspace (paginated).
-
-        Note: Guests are not included in the response.
-        """
-        try:
-            response = await self.client.list_users(page_size, start_cursor)
-            if response is None:
-                self.logger.error("Failed to list users")
-                return None
-
-            self.logger.info(
-                "Retrieved %d users (has_more: %s)",
-                len(response.results),
-                response.has_more,
-            )
-            return response
-
-        except Exception as e:
-            self.logger.error("Error listing users: %s", str(e))
-            return None
-
-    async def get_all_users(self) -> List[NotionUser]:
+    async def get_all_users(self) -> list[NotionUser]:
         """
         Get all users in the workspace as NotionUser objects.
         Automatically handles pagination and converts responses to NotionUser instances.
+        Only returns person users, excludes bots and integrations.
         """
         try:
             # Get raw user responses
             user_responses = await self.client.get_all_users()
 
-            # Convert to NotionUser objects
+            # Filter for person users only and convert to NotionUser objects
             notion_users = []
             for user_response in user_responses:
+                # Skip bot users and integrations
+                if user_response.type != "person":
+                    self.logger.debug(
+                        "Skipping non-person user %s (type: %s)",
+                        user_response.id,
+                        user_response.type,
+                    )
+                    continue
+
                 try:
                     # Use the internal creation method to convert response to NotionUser
-                    notion_user = NotionUser.from_notion_user_response(
+                    notion_user = NotionUser.from_user_response(
                         user_response, self.client.token
                     )
                     notion_users.append(notion_user)
                 except Exception as e:
                     self.logger.warning(
-                        "Failed to convert user %s to NotionUser: %s",
+                        "Failed to convert person user %s to NotionUser: %s",
                         user_response.id,
                         str(e),
                     )
                     continue
 
             self.logger.info(
-                "Successfully converted %d users to NotionUser objects",
+                "Successfully converted %d person users to NotionUser objects (skipped %d non-person users)",
                 len(notion_users),
+                len(user_responses) - len(notion_users),
             )
             return notion_users
 
@@ -91,68 +70,16 @@ class NotionUserManager(LoggingMixin):
             self.logger.error("Error getting all users: %s", str(e))
             return []
 
-    async def get_users_by_type(self, user_type: str = "person") -> List[NotionUser]:
-        """
-        Get all users of a specific type (person or bot).
-        """
-        try:
-            all_users = await self.get_all_users()
-            filtered_users = [user for user in all_users if user.user_type == user_type]
-
-            self.logger.info(
-                "Found %d users of type '%s' out of %d total users",
-                len(filtered_users),
-                user_type,
-                len(all_users),
-            )
-            return filtered_users
-
-        except Exception as e:
-            self.logger.error("Error filtering users by type: %s", str(e))
-            return []
-
-    # TODO: Type this
-    async def get_workspace_info(self) -> Optional[Dict[str, Any]]:
-        """
-        Get available workspace information from the bot user.
-        """
-        bot_user = await self.get_current_bot_user()
-        if bot_user is None:
-            self.logger.error("Failed to get bot user for workspace info")
-            return None
-
-        workspace_info = {
-            "workspace_name": bot_user.workspace_name,
-            "bot_user_id": bot_user.id,
-            "bot_user_name": bot_user.name,
-            "bot_user_type": bot_user.user_type,
-        }
-
-        # Add workspace limits if available
-        if bot_user.is_bot:
-            limits = await bot_user.get_workspace_limits()
-            if limits:
-                workspace_info["workspace_limits"] = limits
-
-        # Add user count statistics
-        try:
-            all_users = await self.get_all_users()
-            workspace_info["total_users"] = len(all_users)
-            workspace_info["person_users"] = len([u for u in all_users if u.is_person])
-            workspace_info["bot_users"] = len([u for u in all_users if u.is_bot])
-        except Exception as e:
-            self.logger.warning("Could not get user statistics: %s", str(e))
-
-        return workspace_info
-
-    async def find_users_by_name(self, name_pattern: str) -> List[NotionUser]:
+    async def find_users_by_name(self, name_pattern: str) -> list[NotionUser]:
         """
-        Find users by name pattern (case-insensitive partial match).
+        Find person users by name pattern (case-insensitive partial match).
+        Only returns person users, excludes bots and integrations.
 
         Note: The API doesn't support server-side filtering, so this fetches all users
         and filters client-side.
         """
         try:
+            # get_all_users() already filters for person users only
             all_users = await self.get_all_users()
             pattern_lower = name_pattern.lower()
 
@@ -163,7 +90,7 @@ class NotionUserManager(LoggingMixin):
             ]
 
             self.logger.info(
-                "Found %d users matching pattern '%s'",
+                "Found %d person users matching pattern '%s'",
                 len(matching_users),
                 name_pattern,
             )

notionary/workspace.py

@@ -1,5 +1,5 @@
 import asyncio
-from typing import List, Optional
+from typing import Optional
 
 from notionary import NotionDatabase, NotionPage
 from notionary.database.client import NotionDatabaseClient
@@ -24,7 +24,7 @@ class NotionWorkspace(LoggingMixin):
         self.page_client = NotionPageClient(token=token)
         self.user_manager = NotionUserManager(token=token)
 
-    async def search_pages(self, query: str, limit=100) -> List[NotionPage]:
+    async def search_pages(self, query: str, limit=100) -> list[NotionPage]:
         """
         Search for pages globally across Notion workspace.
         """
@@ -35,7 +35,7 @@ class NotionWorkspace(LoggingMixin):
 
     async def search_databases(
         self, query: str, limit: int = 100
-    ) -> List[NotionDatabase]:
+    ) -> list[NotionDatabase]:
         """
         Search for databases globally across the Notion workspace.
         """
@@ -58,7 +58,7 @@ class NotionWorkspace(LoggingMixin):
 
         return databases[0] if databases else None
 
-    async def list_all_databases(self, limit: int = 100) -> List[NotionDatabase]:
+    async def list_all_databases(self, limit: int = 100) -> list[NotionDatabase]:
         """
         List all databases in the workspace.
         Returns a list of NotionDatabase instances.

notionary-0.2.23.dist-info/METADATA

@@ -0,0 +1,235 @@
+Metadata-Version: 2.3
+Name: notionary
+Version: 0.2.23
+Summary: Python library for programmatic Notion workspace management - databases, pages, and content with advanced Markdown support
+License: MIT
+Author: Mathis Arends
+Author-email: mathisarends27@gmail.com
+Requires-Python: >=3.9
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: httpx (>=0.28.0)
+Requires-Dist: posthog (>=6.3.1,<7.0.0)
+Requires-Dist: pydantic (>=2.11.4)
+Requires-Dist: python-dotenv (>=1.1.0)
+Project-URL: Homepage, https://github.com/mathisarends/notionary
+Description-Content-Type: text/markdown
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="./static/notionary-dark.png">
+  <source media="(prefers-color-scheme: light)" srcset="./static/notionary-light.png">
+  <img alt="Notionary logo: dark mode shows a white logo, light mode shows a black logo." src="./static/browser-use.png"  width="full">
+</picture>
+
+<h1 align="center">Notion API simplified for Python developers 🐍</h1>
+
+<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/)
+
+Transform complex Notion API interactions into simple, Pythonic code. Build AI agents, automate workflows, and create dynamic content with ease.
+
+</div>
+
+---
+
+## Why Notionary?
+
+- **Smart Discovery**: Find pages and databases by name—no more hunting for URLs or IDs
+- **Rich Markdown**: Convert extended Markdown (callouts, toggles, columns) directly into beautiful Notion blocks
+- **Async-First**: Built for modern Python with full async/await support and high performance
+- **AI-Ready**: Perfect foundation for AI agents that generate and manage Notion content
+- **Round-Trip**: Read existing content, modify it, and write it back while preserving formatting
+
+---
+
+## Quick Start
+
+```bash
+pip install notionary
+```
+
+Set up your [Notion integration](https://www.notion.so/profile/integrations) and add your token:
+
+```bash
+NOTION_SECRET=your_integration_key
+```
+
+### Simple Flow: Find → Create → Update
+
+```python
+import asyncio
+from notionary import NotionPage, NotionDatabase
+
+async def main():
+    # Work with pages - find by name, no exact match needed!
+    page = await NotionPage.from_page_name("Meeting Notes")
+
+    # Direct Markdown - quick & intuitive
+    await page.append_markdown("""
+    ## Action Items
+    - Review project proposal
+    - Schedule team meeting
+    - Update documentation
+
+    [callout](Important meeting decisions require follow-up "💡")
+    """)
+
+    # Builder Pattern - type-safe & powerful for complex layouts
+    await page.append_markdown(lambda builder: (
+        builder
+        .h2("Project Status")
+        .callout("Project 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"])
+            )
+        )
+        .table(
+            headers=["Task", "Owner", "Due Date"],
+            rows=[
+                ["Launch prep", "Alice", "2024-03-15"],
+                ["Marketing", "Bob", "2024-03-20"]
+            ]
+        )
+    ))
+
+asyncio.run(main())
+```
+
+### Create Rich Database Entries
+
+```python
+# Work with databases - connect and create styled entries
+db = await NotionDatabase.from_database_name("Projects")
+
+# Create new project with full styling
+project = await db.create_blank_page()
+await project.set_title("New Marketing Campaign")
+await project.set_emoji_icon("🚀")
+await project.set_random_gradient_cover()
+
+# Set database properties
+await project.set_property_value_by_name("Status", "Planning")
+await project.set_property_value_by_name("Priority", "High")
+await project.set_property_value_by_name("Team Lead", "sarah@company.com")
+
+# Add rich content to the new page
+await project.replace_content(lambda builder: (
+    builder
+    .h1("Campaign Overview")
+    .callout("New marketing initiative targeting Q2 growth", "🎯")
+    .h2("Goals & Objectives")
+    .numbered_list([
+        "Increase brand awareness by 25%",
+        "Generate 500 qualified leads",
+        "Launch in 3 target markets"
+    ])
+    .h2("Budget Breakdown")
+    .table(
+        headers=["Category", "Allocated", "Spent", "Remaining"],
+        rows=[
+            ["Digital Ads", "$15,000", "$3,200", "$11,800"],
+            ["Content Creation", "$8,000", "$1,500", "$6,500"],
+            ["Events", "$12,000", "$0", "$12,000"]
+        ]
+    )
+    .divider()
+    .toggle("Technical Requirements", lambda toggle: (
+        toggle
+        .paragraph("Platform specifications and integration details.")
+        .bulleted_list([
+            "CRM integration with Salesforce",
+            "Analytics tracking setup",
+            "Landing page development"
+        ])
+    ))
+))
+
+print(f"✅ Created styled project: {project.url}")
+```
+
+### Extended Markdown Syntax
+
+Notionary supports rich formatting with callouts, toggles, multi-column layouts, tables, media embeds, and more. Use either direct markdown syntax or the type-safe builder pattern.
+
+See the complete [Block Types documentation](https://mathisarends.github.io/notionary/blocks/) for all available formatting options and syntax examples.
+
+## What You Can Build
+
+- **AI Content Generation** - Perfect for AI agents that create structured reports and documentation
+- **Workflow Automation** - Update project status, sync data between databases, generate reports
+- **Dynamic Documentation** - Auto-generate team docs, API references, and knowledge bases
+- **Content Management** - Bulk page updates, template generation, and content migration
+
+## Core Features
+
+| Feature              | Description                                            |
+| -------------------- | ------------------------------------------------------ |
+| **Smart Discovery**  | Find pages/databases by name with fuzzy matching       |
+| **Rich Markdown**    | Extended syntax for callouts, toggles, columns, tables |
+| **Async-First**      | Modern Python with full async/await support            |
+| **Round-Trip**       | Read content as markdown, edit, and write back         |
+| **AI-Ready**         | Generate system prompts for AI content creation        |
+| **All Block Types**  | Support for every Notion block type                    |
+| **Type Safety**      | Full type hints for better IDE support                 |
+| **High Performance** | Efficient batch operations and caching                 |
+
+## Examples & Documentation
+
+Explore comprehensive guides and real-world examples:
+
+- **[📖 Full Documentation](https://mathisarends.github.io/notionary/)** - Complete API reference and guides
+- **[Getting Started](https://mathisarends.github.io/notionary/get-started/)** - Quick setup and first steps
+- **[Page Management](https://mathisarends.github.io/notionary/page/)** - Work with page content and properties
+- **[Database Operations](https://mathisarends.github.io/notionary/database/)** - Query and manage databases
+- **[Block Types](https://mathisarends.github.io/notionary/blocks/)** - Complete formatting reference
+
+Check out the `examples/` directory for hands-on tutorials:
+
+### Core Examples
+
+- **[Page Management](examples/page_example.py)** - Create, update, and manage pages
+- **[Database Operations](examples/database.py)** - Connect to and query databases
+- **[Workspace Discovery](examples/workspace_discovery.py)** - Explore your workspace
+
+### Markdown Examples
+
+- **[Basic Formatting](examples/markdown/basic.py)** - Text, lists, and links
+- **[Callouts](examples/markdown/callout.py)** - Eye-catching information boxes
+- **[Toggles](examples/markdown/toggle.py)** - Collapsible content sections
+- **[Multi-Column](examples/markdown/columns.py)** - Side-by-side layouts
+- **[Tables](examples/markdown/table.py)** - Structured data presentation
+
+## Contributing
+
+We'd love your help making Notionary even better!
+
+Whether it's fixing bugs, adding features, improving docs, or sharing examples - all contributions are welcome.
+
+See our [Contributing Guide](https://mathisarends.github.io/notionary/contributing/) to get started.
+
+---
+
+<div align="center">
+
+**Ready to transform your Notion workflow?**
+
+[📖 Read the Docs](https://mathisarends.github.io/notionary/) • [Getting Started](https://mathisarends.github.io/notionary/get-started/) • [Examples](examples/)
+
+Built with ❤️ for the Python community
+
+</div>
+