better-notion 1.0.1__py3-none-any.whl → 1.1.0__py3-none-any.whl

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/_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."""
+        ...

better_notion/plugins/base.py

@@ -5,14 +5,20 @@ Plugins can extend the CLI by:
 1. Adding new commands (CommandPlugin)
 2. Providing data filters/formatters (DataPlugin)
 3. Combining both capabilities
+4. Extending the SDK with models, caches, and managers (SDKPlugin)
 """
 from __future__ import annotations
 
 from abc import ABC, abstractmethod
-from typing import Any, Protocol
+from typing import TYPE_CHECKING, Any, Protocol
 
 import typer
 
+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 CommandPlugin(Protocol):
     """
@@ -148,6 +154,98 @@ class PluginInterface(ABC):
         """
         return {}
 
+    # ===== SDK EXTENSION METHODS (OPTIONAL) =====
+
+    def register_sdk_models(self) -> dict[str, type[BaseEntity]]:
+        """
+        Register custom SDK model classes.
+
+        Plugins can register domain-specific models that extend BaseEntity.
+        These models are accessible via client.plugin_model(name).
+
+        Default implementation returns empty dict.
+
+        Returns:
+            Dictionary mapping model names to model classes
+
+        Example:
+            >>> def register_sdk_models(self) -> dict[str, type[BaseEntity]]:
+            ...     return {
+            ...         "Organization": Organization,
+            ...         "Project": Project,
+            ...     }
+        """
+        return {}
+
+    def register_sdk_caches(self, client: "NotionClient") -> dict[str, "Cache"]:
+        """
+        Register custom SDK caches.
+
+        Plugins can register dedicated caches for their models.
+        These caches are accessible via client.plugin_cache(name).
+
+        Default implementation returns empty dict.
+
+        Args:
+            client: NotionClient instance
+
+        Returns:
+            Dictionary mapping cache names to Cache instances
+
+        Example:
+            >>> def register_sdk_caches(self, client) -> dict[str, Cache]:
+            ...     return {
+            ...         "organizations": Cache(),
+            ...         "projects": Cache(),
+            ...     }
+        """
+        return {}
+
+    def register_sdk_managers(self, client: "NotionClient") -> dict[str, Any]:
+        """
+        Register custom SDK managers.
+
+        Plugins can register managers that provide convenience methods
+        for working with their models. Managers are accessible via
+        client.plugin_manager(name).
+
+        Default implementation returns empty dict.
+
+        Args:
+            client: NotionClient instance
+
+        Returns:
+            Dictionary mapping manager names to manager instances
+
+        Example:
+            >>> def register_sdk_managers(self, client) -> dict[str, Any]:
+            ...     return {
+            ...         "organizations": OrganizationManager(client),
+            ...     }
+        """
+        return {}
+
+    def sdk_initialize(self, client: "NotionClient") -> None:
+        """
+        Initialize SDK plugin resources.
+
+        Called after all registrations are complete. Use this for
+        setup tasks like loading configuration, validating resources,
+        or establishing connections.
+
+        Default implementation does nothing.
+
+        Args:
+            client: NotionClient instance
+
+        Example:
+            >>> def sdk_initialize(self, client) -> None:
+            ...     # Load workspace configuration
+            ...     config = load_workspace_config()
+            ...     client._workspace_config = config
+        """
+        pass
+
     def validate(self) -> tuple[bool, list[str]]:
         """
         Validate the plugin structure and configuration.

better_notion/plugins/loader.py

@@ -13,10 +13,13 @@ import importlib.util
 import json
 import sys
 from pathlib import Path
-from typing import Any
+from typing import TYPE_CHECKING, Any
 
 from better_notion.plugins.base import CommandPlugin
 
+if TYPE_CHECKING:
+    from better_notion._sdk.client import NotionClient
+
 
 class PluginLoader:
     """
@@ -242,3 +245,50 @@ class PluginLoader:
                 return True
 
         return False
+
+    def register_sdk_extensions(self, client: "NotionClient") -> None:
+        """
+        Register SDK extensions from all loaded plugins with a NotionClient.
+
+        This method iterates through all loaded plugins and registers their
+        SDK models, caches, and managers with the provided NotionClient instance.
+
+        Args:
+            client: NotionClient instance to register extensions with
+
+        Example:
+            >>> loader = PluginLoader()
+            >>> loader.discover()  # Load plugins first
+            >>> client = NotionClient(auth="...")
+            >>> loader.register_sdk_extensions(client)
+        """
+        # Get all loaded plugins
+        plugins = list(self.loaded_plugins.values())
+
+        # Also discover plugins if not already loaded
+        if not plugins:
+            plugins = self.discover()
+
+        # Register SDK extensions from each plugin
+        for plugin in plugins:
+            try:
+                # Register models
+                models = plugin.register_sdk_models()
+                if models:
+                    client._plugin_models.update(models)
+
+                # Register caches
+                caches = plugin.register_sdk_caches(client)
+                if caches:
+                    client._plugin_caches.update(caches)
+
+                # Register managers
+                managers = plugin.register_sdk_managers(client)
+                if managers:
+                    client._plugin_managers.update(managers)
+
+                # Initialize plugin
+                plugin.sdk_initialize(client)
+            except Exception:
+                # Continue with other plugins if one fails
+                continue

better_notion/plugins/official/__init__.py

@@ -4,12 +4,10 @@ Official plugins for Better Notion CLI.
 This package contains officially maintained plugins that extend
 the CLI with commonly-needed functionality.
 """
-from better_notion.plugins.official.agents import AgentsPlugin
 from better_notion.plugins.official.productivity import ProductivityPlugin
 
-__all__ = ["AgentsPlugin", "ProductivityPlugin"]
+__all__ = ["ProductivityPlugin"]
 
 OFFICIAL_PLUGINS = [
-    AgentsPlugin,
     ProductivityPlugin,
 ]