better-notion 1.0.0__tar.gz → 1.1.0__tar.gz

{better_notion-1.0.0 → better_notion-1.1.0}/.gitignore

@@ -1,131 +1,131 @@
-# Byte-compiled / optimized / DLL files
-__pycache__/
-*.py[cod]
-*$py.class
-
-# C extensions
-*.so
-
-# Distribution / packaging
-.Python
-build/
-develop-eggs/
-dist/
-downloads/
-eggs/
-.eggs/
-lib/
-lib64/
-parts/
-sdist/
-var/
-wheels/
-share/python-wheels/
-*.egg-info/
-.installed.cfg
-*.egg
-MANIFEST
-
-# PyInstaller
-*.manifest
-*.spec
-
-# Installer logs
-pip-log.txt
-pip-delete-this-directory.txt
-
-# Unit test / coverage reports
-htmlcov/
-.tox/
-.nox/
-.coverage
-.coverage.*
-.cache
-nosetests.xml
-coverage.xml
-*.cover
-*.py,cover
-.hypothesis/
-.pytest_cache/
-cover/
-
-# Translations
-*.mo
-*.pot
-
-# Environments
-.env
-.venv
-env/
-venv/
-ENV/
-env.bak/
-venv.bak/
-
-# IDEs
-.vscode/
-.idea/
-*.swp
-*.swo
-*~
-.DS_Store
-
-# mypy
-.mypy_cache/
-.dmypy.json
-dmypy.json
-
-# ruff
-.ruff_cache/
-
-# uv
-.uv-cache/
-
-# Jupyter Notebook
-.ipynb_checkpoints
-
-# pyenv
-.python-version
-
-# celery beat schedule file
-celerybeat-schedule
-celerybeat.pid
-
-# SageMath parsed files
-*.sage.py
-
-# Spyder project settings
-.spyderproject
-.spyproject
-
-# Rope project settings
-.ropeproject
-
-# mkdocs documentation
-/site
-
-# pyre static type checker
-.pyre/
-
-# pytype static type checker
-.pytype/
-
-# Cython debug symbols
-cython_debug/
-
-# PyCharm
-.idea/
-
-# macOS
-.DS_Store
-
-# Windows
-Thumbs.db
-ehthumbs.db
-Desktop.ini
-
-# Project specific
-*.log
-.env.local
-.env.*.local
-test_tokens.py
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# ruff
+.ruff_cache/
+
+# uv
+.uv-cache/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# celery beat schedule file
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# pyre static type checker
+.pyre/
+
+# pytype static type checker
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+.idea/
+
+# macOS
+.DS_Store
+
+# Windows
+Thumbs.db
+ehthumbs.db
+Desktop.ini
+
+# Project specific
+*.log
+.env.local
+.env.*.local
+test_tokens.py

{better_notion-1.0.0 → better_notion-1.1.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: better-notion
-Version: 1.0.0
-Summary: A high-level Python SDK for the Notion API with developer experience in mind. Now with AI agents workflow management system!
+Version: 1.1.0
+Summary: A high-level Python SDK for the Notion API with developer experience in mind.
 Project-URL: Homepage, https://github.com/nesalia-inc/better-notion
 Project-URL: Documentation, https://github.com/nesalia-inc/better-notion#readme
 Project-URL: Repository, https://github.com/nesalia-inc/better-notion

{better_notion-1.0.0 → better_notion-1.1.0}/better_notion/_sdk/client.py

@@ -99,6 +99,11 @@ class NotionClient:
         self._comment_cache: Cache[object] = Cache()
         # No cache for Block (too many)
 
+        # Plugin-managed resources (for SDK plugin system)
+        self._plugin_caches: dict[str, Cache[object]] = {}
+        self._plugin_managers: dict[str, object] = {}
+        self._plugin_models: dict[str, type] = {}
+
         # Search cache
         self._search_cache: dict[str, list[object]] = {}
 
@@ -259,10 +264,92 @@ class NotionClient:
 
         return results
 
+    # ===== SDK PLUGIN SYSTEM =====
+
+    def register_sdk_plugin(
+        self,
+        models: dict[str, type] | None = None,
+        caches: dict[str, "Cache"] | None = None,
+        managers: dict[str, object] | None = None,
+    ) -> None:
+        """Register an SDK plugin's resources with the client.
+
+        This method allows plugins to register custom models, caches, and
+        managers without modifying the core SDK.
+
+        Args:
+            models: Dict mapping model names to model classes
+            caches: Dict mapping cache names to Cache instances
+            managers: Dict mapping manager names to manager instances
+
+        Example:
+            >>> client.register_sdk_plugin(
+            ...     models={"Organization": Organization},
+            ...     caches={"organizations": Cache()},
+            ...     managers={"organizations": OrganizationManager(client)},
+            ... )
+        """
+        if models:
+            self._plugin_models.update(models)
+
+        if caches:
+            self._plugin_caches.update(caches)
+
+        if managers:
+            self._plugin_managers.update(managers)
+
+    def plugin_cache(self, name: str) -> "Cache | None":
+        """Access a plugin-registered cache.
+
+        Args:
+            name: Cache name (e.g., "organizations")
+
+        Returns:
+            Cache instance if found, None otherwise
+
+        Example:
+            >>> cache = client.plugin_cache("organizations")
+            >>> if cache and org_id in cache:
+            ...     org = cache[org_id]
+        """
+        return self._plugin_caches.get(name)
+
+    def plugin_manager(self, name: str) -> object | None:
+        """Access a plugin-registered manager.
+
+        Args:
+            name: Manager name (e.g., "organizations")
+
+        Returns:
+            Manager instance if found, None otherwise
+
+        Example:
+            >>> orgs_mgr = client.plugin_manager("organizations")
+            >>> if orgs_mgr:
+            ...     orgs = await orgs_mgr.list()
+        """
+        return self._plugin_managers.get(name)
+
+    def plugin_model(self, name: str) -> type | None:
+        """Access a plugin-registered model class.
+
+        Args:
+            name: Model name (e.g., "Organization")
+
+        Returns:
+            Model class if found, None otherwise
+
+        Example:
+            >>> OrgClass = client.plugin_model("Organization")
+            >>> if OrgClass:
+            ...     org = await OrgClass.get(org_id, client=client)
+        """
+        return self._plugin_models.get(name)
+
     # ===== CACHE MANAGEMENT =====
 
     def clear_all_caches(self) -> None:
-        """Clear all caches.
+        """Clear all caches including plugin caches.
 
         Example:
             >>> client.clear_all_caches()
@@ -272,8 +359,12 @@ class NotionClient:
         self._page_cache.clear()
         self._search_cache.clear()
 
+        # Clear plugin caches
+        for cache in self._plugin_caches.values():
+            cache.clear()
+
     def get_cache_stats(self) -> dict[str, dict[str, Any]]:
-        """Get statistics for all caches.
+        """Get statistics for all caches including plugin caches.
 
         Returns:
             Dict with stats for each cache
@@ -283,10 +374,11 @@ class NotionClient:
             >>> print(stats)
             {
                 'user_cache': {'hits': 100, 'misses': 5, 'size': 50, 'hit_rate': 0.95},
+                'plugin:organizations': {'hits': 50, 'misses': 2, 'size': 10, 'hit_rate': 0.96},
                 ...
             }
         """
-        return {
+        stats = {
             "user_cache": {
                 "hits": self._user_cache.stats.hits,
                 "misses": self._user_cache.stats.misses,
@@ -310,6 +402,17 @@ class NotionClient:
             }
         }
 
+        # Add plugin cache stats
+        for cache_name, cache in self._plugin_caches.items():
+            stats[f"plugin:{cache_name}"] = {
+                "hits": cache.stats.hits,
+                "misses": cache.stats.misses,
+                "size": cache.stats.size,
+                "hit_rate": cache.stats.hit_rate
+            }
+
+        return stats
+
     # ===== CONTEXT MANAGER =====
 
     async def __aenter__(self):

better_notion-1.1.0/better_notion/_sdk/plugins.py

@@ -0,0 +1,180 @@
+"""SDK Plugin System for extending NotionClient functionality.
+
+This module provides the protocol interface for SDK-level plugins that need to:
+- Register custom model classes
+- Add dedicated caches to NotionClient
+- Create custom managers
+- Initialize plugin-specific resources
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Protocol
+
+if TYPE_CHECKING:
+    from better_notion._sdk.cache import Cache
+    from better_notion._sdk.client import NotionClient
+    from better_notion._sdk.base.entity import BaseEntity
+
+
+class SDKPluginInterface(Protocol):
+    """
+    Protocol for SDK-level plugins that extend NotionClient functionality.
+
+    SDK plugins can register custom models, caches, and managers with the
+    NotionClient, enabling domain-specific extensions without modifying
+    the core SDK.
+
+    Example:
+        >>> class AgentsSDKPlugin:
+        ...     def register_models(self) -> dict[str, type[BaseEntity]]:
+        ...         return {"Organization": Organization}
+        ...
+        ...     def register_caches(self, client: NotionClient) -> dict[str, Cache]:
+        ...         return {"organizations": Cache()}
+        ...
+        ...     def register_managers(self, client: NotionClient) -> dict[str, Any]:
+        ...         return {"organizations": OrganizationManager(client)}
+    """
+
+    def register_models(self) -> dict[str, type[BaseEntity]]:
+        """Register custom model classes.
+
+        Model classes should inherit from BaseEntity and follow the
+        autonomous entity pattern (get, create, update methods).
+
+        Returns:
+            Dictionary mapping model names to model classes
+
+        Example:
+            >>> def register_models(self) -> dict[str, type[BaseEntity]]:
+            ...     return {
+            ...         "Organization": Organization,
+            ...         "Project": Project,
+            ...         "Task": Task,
+            ...     }
+        """
+        ...
+
+    def register_caches(self, client: "NotionClient") -> dict[str, "Cache"]:
+        """Register custom caches with the client.
+
+        Caches are stored in the client and accessible via
+        client.plugin_cache(name). Each cache should have a unique name
+        to avoid collisions with other plugins.
+
+        Args:
+            client: NotionClient instance to register caches with
+
+        Returns:
+            Dictionary mapping cache names to Cache instances
+
+        Example:
+            >>> def register_caches(self, client) -> dict[str, Cache]:
+            ...     return {
+            ...         "organizations": Cache(),
+            ...         "projects": Cache(),
+            ...         "tasks": Cache(),
+            ...     }
+        """
+        ...
+
+    def register_managers(self, client: "NotionClient") -> dict[str, Any]:
+        """Register custom managers with the client.
+
+        Managers are accessible via client.plugin_manager(name).
+        They typically provide convenience methods for working with
+        the plugin's models.
+
+        Args:
+            client: NotionClient instance
+
+        Returns:
+            Dictionary mapping manager names to manager instances
+
+        Example:
+            >>> def register_managers(self, client) -> dict[str, Any]:
+            ...     return {
+            ...         "organizations": OrganizationManager(client),
+            ...         "projects": ProjectManager(client),
+            ...     }
+        """
+        ...
+
+    def initialize(self, client: "NotionClient") -> None:
+        """Initialize plugin-specific resources.
+
+        Called after all registrations (models, caches, managers) are
+        complete. Use this for setup tasks like loading configuration,
+        validating resources, or establishing connections.
+
+        Args:
+            client: NotionClient instance
+
+        Example:
+            >>> def initialize(self, client) -> None:
+            ...     # Load database IDs from config
+            ...     db_ids = load_workspace_config()
+            ...     client._workspace_config = db_ids
+        """
+        ...
+
+    def get_info(self) -> dict[str, Any]:
+        """Return plugin metadata.
+
+        Returns:
+            Dictionary with plugin information
+
+        Example:
+            >>> def get_info(self) -> dict[str, Any]:
+            ...     return {
+            ...         "name": "agents-sdk",
+            ...         "version": "1.0.0",
+            ...         "description": "SDK extensions for agents workflow",
+            ...     }
+        """
+        ...
+
+
+class CombinedPluginInterface(Protocol):
+    """
+    Protocol for plugins that extend both CLI and SDK.
+
+    This allows a single plugin class to provide:
+    - CLI commands (via register_commands)
+    - SDK extensions (via register_models, register_caches, etc.)
+
+    Example:
+        >>> class AgentsPlugin(CombinedPluginInterface):
+        ...     def register_commands(self, app: typer.Typer) -> None:
+        ...         # Register CLI commands
+        ...         pass
+        ...
+        ...     def register_models(self) -> dict[str, type[BaseEntity]]:
+        ...         # Register SDK models
+        ...         return {"Organization": Organization}
+    """
+
+    def register_commands(self, app: Any) -> None:
+        """Register CLI commands with Typer app."""
+        ...
+
+    def register_models(self) -> dict[str, type[BaseEntity]]:
+        """Register custom model classes."""
+        ...
+
+    def register_caches(self, client: "NotionClient") -> dict[str, "Cache"]:
+        """Register custom caches."""
+        ...
+
+    def register_managers(self, client: "NotionClient") -> dict[str, Any]:
+        """Register custom managers."""
+        ...
+
+    def initialize(self, client: "NotionClient") -> None:
+        """Initialize plugin resources."""
+        ...
+
+    def get_info(self) -> dict[str, Any]:
+        """Return plugin metadata."""
+        ...