notionary 0.2.19__py3-none-any.whl → 0.2.22__py3-none-any.whl

notionary/user/notion_user_manager.py

@@ -1,7 +1,7 @@
-from typing import Any, Dict, Optional, List
+from typing import Optional
+
 from notionary.user.client import NotionUserClient
 from notionary.user.notion_user import NotionUser
-from notionary.user.models import NotionUsersListResponse
 from notionary.util import LoggingMixin
 
 
@@ -17,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
 
@@ -90,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()
 
@@ -162,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/util/__init__.py

@@ -1,13 +1,14 @@
+from .factory_only import factory_only
 from .logging_mixin import LoggingMixin
+from .page_id_utils import extract_uuid, format_uuid
 from .singleton import singleton
-from .page_id_utils import format_uuid
-from .factory_only import factory_only
 from .singleton_metaclass import SingletonMetaClass
 
 __all__ = [
     "LoggingMixin",
     "singleton",
     "format_uuid",
+    "extract_uuid",
     "factory_only",
     "singleton",
     "SingletonMetaClass",

notionary/util/fuzzy.py

@@ -1,7 +1,8 @@
 from __future__ import annotations
+
 import difflib
-from typing import List, Any, TypeVar, Callable, Optional
 from dataclasses import dataclass
+from typing import Any, Callable, List, Optional, TypeVar
 
 T = TypeVar("T")
 

notionary/util/logging_mixin.py

@@ -1,7 +1,7 @@
 import logging
-from typing import Optional, ClassVar
-
 import os
+from typing import ClassVar, Optional
+
 from dotenv import load_dotenv
 
 load_dotenv()

notionary/util/singleton_metaclass.py

@@ -1,4 +1,4 @@
-from typing import TypeVar, Dict, Any, Type, cast
+from typing import Any, Dict, Type, TypeVar, cast
 
 T = TypeVar("T")
 

notionary/workspace.py

@@ -1,6 +1,7 @@
 import asyncio
-from typing import Optional, List
-from notionary import NotionPage, NotionDatabase
+from typing import Optional
+
+from notionary import NotionDatabase, NotionPage
 from notionary.database.client import NotionDatabaseClient
 from notionary.page.client import NotionPageClient
 from notionary.user import NotionUser, NotionUserManager
@@ -23,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.
         """
@@ -34,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.
         """
@@ -57,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.22.dist-info/METADATA

@@ -0,0 +1,237 @@
+Metadata-Version: 2.3
+Name: notionary
+Version: 0.2.22
+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: aiofiles (>=24.1.0,<25.0.0)
+Requires-Dist: httpx (>=0.28.0)
+Requires-Dist: isort (>=6.0.1,<7.0.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>
+