homesec 1.1.1__py3-none-any.whl → 1.1.2__py3-none-any.whl

homesec/plugins/registry.py

@@ -0,0 +1,160 @@
+"""Unified Plugin Registry for HomeSec.
+
+This module provides the core infrastructure for the Class-Based Plugin Architecture.
+It handles plugin registration, discovery, and strict configuration validation.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Callable
+from enum import Enum
+from typing import Any, Generic, Protocol, TypeVar, cast
+
+from pydantic import BaseModel
+
+logger = logging.getLogger(__name__)
+
+
+class PluginType(str, Enum):
+    """Categorization of plugin types."""
+
+    SOURCE = "source"
+    FILTER = "filter"
+    ANALYZER = "analyzer"
+    STORAGE = "storage"
+    NOTIFIER = "notifier"
+    ALERT_POLICY = "alert_policy"
+
+
+ConfigT = TypeVar("ConfigT", bound=BaseModel)
+PluginInterfaceT = TypeVar("PluginInterfaceT", bound=object, covariant=True)
+
+
+class PluginProtocol(Protocol[ConfigT, PluginInterfaceT]):
+    """Protocol defining the structure of a valid HomeSec plugin class."""
+
+    config_cls: type[ConfigT]
+
+    @classmethod
+    def create(cls, config: ConfigT) -> PluginInterfaceT:
+        """Factory method to create the plugin instance."""
+        ...
+
+
+class PluginRegistry(Generic[ConfigT, PluginInterfaceT]):
+    """Generic registry for a specific type of plugin."""
+
+    def __init__(self, plugin_type: PluginType) -> None:
+        self.plugin_type = plugin_type
+        self._plugins: dict[str, type[PluginProtocol[ConfigT, PluginInterfaceT]]] = {}
+
+    def register(
+        self, name: str, plugin_cls: type[PluginProtocol[ConfigT, PluginInterfaceT]]
+    ) -> None:
+        """Register a plugin class."""
+        if name in self._plugins:
+            raise ValueError(f"{self.plugin_type} plugin '{name}' is already registered.")
+
+        self._plugins[name] = plugin_cls
+        logger.debug("Registered %s plugin: %s", self.plugin_type, name)
+
+    def load(
+        self, name: str, config_dict: dict[str, Any], **runtime_context: Any
+    ) -> PluginInterfaceT:
+        """Load and instantiate a plugin.
+
+        Args:
+            name: The name of the plugin to load.
+            config_dict: Raw configuration dictionary (from YAML/JSON).
+            **runtime_context: Key-value pairs to inject into the config *before* validation.
+                               (e.g. camera_name="front_door")
+
+        Returns:
+            An instantiated and configured plugin object.
+
+        Raises:
+            ValueError: If the plugin name is unknown.
+            ValidationError: If configuration is invalid.
+        """
+        if name not in self._plugins:
+            available = ", ".join(sorted(self._plugins.keys()))
+            raise ValueError(f"Unknown {self.plugin_type} plugin: '{name}'. Available: {available}")
+
+        plugin_cls = self._plugins[name]
+
+        # 1. Inject runtime context into config (if the config model supports those fields)
+        # We merge it into the raw dict so Pydantic can validate it.
+        # This allows injecting "camera_name" into SourceConfig, etc.
+        merged_config = config_dict.copy()
+        merged_config.update(runtime_context)
+
+        # 2. Validate configuration
+        validated_config = plugin_cls.config_cls.model_validate(merged_config)
+
+        # 3. Create instance
+        return plugin_cls.create(validated_config)
+
+    def get_all(self) -> dict[str, type[PluginProtocol[ConfigT, PluginInterfaceT]]]:
+        """Return all registered plugins."""
+        return self._plugins.copy()
+
+
+# Global Registry Storage
+# We keep separate registries per type for strict typing
+_REGISTRIES: dict[PluginType, PluginRegistry[Any, Any]] = {t: PluginRegistry(t) for t in PluginType}
+
+
+def plugin(plugin_type: PluginType, name: str) -> Callable[[type], type]:
+    """Decorator to register a class as a plugin.
+
+    Args:
+        plugin_type: The category of plugin (SOURCE, FILTER, etc.)
+        name: The unique name for this plugin (e.g., "rtsp", "yolo")
+    """
+
+    def decorator(cls: type) -> type:
+        # Runtime verification could happen here, or we trust static analysis/Protocol
+        if not hasattr(cls, "config_cls"):
+            raise TypeError(f"Plugin class {cls.__name__} must define 'config_cls'")
+        if not hasattr(cls, "create"):
+            raise TypeError(f"Plugin class {cls.__name__} must define 'create' classmethod")
+
+        registry = _REGISTRIES[plugin_type]
+        # We cast because the decorator is generic but _REGISTRIES holds specific types
+        registry.register(name, cls)
+
+        # Attach metadata for inspection if needed
+        cast(Any, cls).__plugin_name__ = name
+        cast(Any, cls).__plugin_type__ = plugin_type
+
+        return cls
+
+    return decorator
+
+
+def load_plugin(
+    plugin_type: PluginType, name: str, config: dict[str, Any] | BaseModel, **runtime_context: Any
+) -> Any:
+    """Public API to load any plugin.
+
+    Args:
+        plugin_type: The enum type of plugin to load.
+        name: The plugin name (e.g. "rtsp").
+        config: The raw config dict OR an already-validated BaseModel.
+        runtime_context: Dependencies to inject (camera_name, etc.)
+    """
+    registry = _REGISTRIES[plugin_type]
+
+    # Handle case where config is already a BaseModel (e.g. nested in AppConfig)
+    if isinstance(config, BaseModel):
+        config_dict = config.model_dump()
+    else:
+        config_dict = config
+
+    return registry.load(name, config_dict, **runtime_context)
+
+
+def get_plugin_names(plugin_type: PluginType) -> list[str]:
+    """Get list of registered plugin names for a given type."""
+    return sorted(_REGISTRIES[plugin_type].get_all().keys())

homesec/plugins/sources/__init__.py

@@ -0,0 +1,45 @@
+"""Source plugins and registry."""
+
+from __future__ import annotations
+
+import logging
+from typing import cast
+
+from pydantic import BaseModel
+
+from homesec.interfaces import ClipSource
+from homesec.plugins.registry import PluginType, load_plugin
+
+logger = logging.getLogger(__name__)
+
+
+def load_source_plugin(
+    source_type: str,
+    config: dict[str, object] | BaseModel,
+    camera_name: str,
+) -> ClipSource:
+    """Load and instantiate a source plugin.
+
+    Args:
+        source_type: Name of the source plugin (e.g., "rtsp", "local_folder")
+        config: Raw config dict or validated BaseModel
+        camera_name: Name of the camera (runtime context)
+
+    Returns:
+        Instantiated ClipSource
+
+    Raises:
+        ValueError: If source_type is unknown or config validation fails
+    """
+    return cast(
+        ClipSource,
+        load_plugin(
+            PluginType.SOURCE,
+            source_type,
+            config,
+            camera_name=camera_name,
+        ),
+    )
+
+
+__all__ = ["load_source_plugin"]

homesec/plugins/sources/ftp.py

@@ -0,0 +1,25 @@
+"""FTP source plugin."""
+
+from __future__ import annotations
+
+from homesec.interfaces import ClipSource
+from homesec.models.source import FtpSourceConfig
+from homesec.plugins.registry import PluginType, plugin
+
+# Import the actual implementation from sources module
+from homesec.sources.ftp import FtpSource as FtpSourceImpl
+
+
+@plugin(plugin_type=PluginType.SOURCE, name="ftp")
+class FtpPluginSource(FtpSourceImpl):
+    """FTP source plugin wrapper."""
+
+    config_cls = FtpSourceConfig
+
+    @classmethod
+    def create(cls, config: FtpSourceConfig) -> ClipSource:
+        # FtpSourceImpl expects config and camera_name
+        # config.camera_name is populated by registry
+        if config.camera_name is None:
+            raise ValueError("camera_name is required for FtpSource")
+        return cls(config=config, camera_name=config.camera_name)

homesec/plugins/sources/local_folder.py

@@ -0,0 +1,30 @@
+"""Local folder source plugin."""
+
+from __future__ import annotations
+
+from homesec.interfaces import ClipSource
+from homesec.models.source import LocalFolderSourceConfig
+from homesec.plugins.registry import PluginType, plugin
+from homesec.sources.local_folder import LocalFolderSource as LocalFolderSourceImpl
+
+
+@plugin(plugin_type=PluginType.SOURCE, name="local_folder")
+class LocalFolderPlugin(LocalFolderSourceImpl):
+    """Register local_folder source plugin."""
+
+    config_cls = LocalFolderSourceConfig
+
+    @classmethod
+    def create(cls, config: LocalFolderSourceConfig) -> ClipSource:
+        # Note: LocalFolderSourceImpl takes (config) in __init__?
+        # Let's check LocalFolderSourceImpl signature.
+        # It inherits from ClipSource.
+        # Wait, usually implementation classes take specific args, not the config object?
+        # I need to check src/homesec/sources/local_folder.py.
+        # But assuming refactor, I should match what create does.
+        # Old create: LocalFolderSourceImpl(config=config, camera_name=context.camera_name)
+        # config now has camera_name injected.
+        return cls(config=config, camera_name=config.camera_name)
+
+
+__all__ = ["LocalFolderPlugin"]

homesec/plugins/sources/rtsp.py

@@ -0,0 +1,27 @@
+"""RTSP source plugin."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from homesec.interfaces import ClipSource
+from homesec.models.source import RTSPSourceConfig
+from homesec.plugins.registry import PluginType, plugin
+from homesec.sources.rtsp import RTSPSource as RTSPSourceImpl
+
+if TYPE_CHECKING:
+    pass
+
+
+@plugin(plugin_type=PluginType.SOURCE, name="rtsp")
+class RTSPPluginSource(RTSPSourceImpl):
+    """RTSP source plugin wrapper."""
+
+    config_cls = RTSPSourceConfig
+
+    @classmethod
+    def create(cls, config: RTSPSourceConfig) -> ClipSource:
+        # RTSPSourceImpl expects config and camera_name
+        if config.camera_name is None:
+            raise ValueError("camera_name is required for RTSPSource")
+        return cls(config=config, camera_name=config.camera_name)

homesec/plugins/storage/__init__.py

@@ -3,78 +3,17 @@
 from __future__ import annotations
 
 import logging
-from collections.abc import Callable
-from dataclasses import dataclass
-from typing import TypeVar
-
-from pydantic import BaseModel
+from typing import cast
 
 from homesec.interfaces import StorageBackend
 from homesec.models.config import StorageConfig
+from homesec.plugins.registry import PluginType, load_plugin
 
 logger = logging.getLogger(__name__)
 
-# Type alias for clarity
-StorageFactory = Callable[[BaseModel], StorageBackend]
-
-
-@dataclass(frozen=True)
-class StoragePlugin:
-    """Metadata for a storage backend plugin."""
-
-    name: str
-    config_model: type[BaseModel]
-    factory: StorageFactory
-
-
-STORAGE_REGISTRY: dict[str, StoragePlugin] = {}
-
-
-def register_storage(plugin: StoragePlugin) -> None:
-    """Register a storage plugin with collision detection.
-
-    Args:
-        plugin: Storage plugin to register
-
-    Raises:
-        ValueError: If a plugin with the same name is already registered
-    """
-    if plugin.name in STORAGE_REGISTRY:
-        raise ValueError(
-            f"Storage plugin '{plugin.name}' is already registered. "
-            f"Plugin names must be unique across all storage plugins."
-        )
-    STORAGE_REGISTRY[plugin.name] = plugin
-
 
-T = TypeVar("T", bound=Callable[[], StoragePlugin])
-
-
-def storage_plugin(name: str) -> Callable[[T], T]:
-    """Decorator to register a storage backend plugin.
-
-    Usage:
-        @storage_plugin(name="my_storage")
-        def my_storage_plugin() -> StoragePlugin:
-            return StoragePlugin(...)
-
-    Args:
-        name: Plugin name (for validation only - must match plugin.name)
-
-    Returns:
-        Decorator function that registers the plugin
-    """
-
-    def decorator(factory_fn: T) -> T:
-        plugin = factory_fn()
-        register_storage(plugin)
-        return factory_fn
-
-    return decorator
-
-
-def create_storage(config: StorageConfig) -> StorageBackend:
-    """Create storage backend from config using plugin registry.
+def load_storage_plugin(config: StorageConfig) -> StorageBackend:
+    """Load and instantiate a storage backend plugin.
 
     Args:
         config: Storage configuration with backend name and backend-specific settings
@@ -83,33 +22,24 @@ def create_storage(config: StorageConfig) -> StorageBackend:
         Instantiated storage backend
 
     Raises:
-        RuntimeError: If backend is unknown or backend-specific config is missing
+        ValueError: If backend is unknown or backend-specific config is missing
     """
-    backend_name = config.backend.lower()
-
-    if backend_name not in STORAGE_REGISTRY:
-        available = ", ".join(sorted(STORAGE_REGISTRY.keys()))
-        raise RuntimeError(f"Unknown storage backend: '{backend_name}'. Available: {available}")
-
-    plugin = STORAGE_REGISTRY[backend_name]
-
     # Extract backend-specific config using attribute access
-    # e.g., config.dropbox, config.local
-    specific_config = getattr(config, backend_name, None)
+    specific_config = getattr(config, config.backend.lower(), None)
     if specific_config is None:
-        raise RuntimeError(
-            f"Missing '{backend_name}' config in storage section. "
-            f"Add 'storage.{backend_name}' to your config."
+        raise ValueError(
+            f"Missing '{config.backend.lower()}' config in storage section. "
+            f"Add 'storage.{config.backend.lower()}' to your config."
         )
 
-    return plugin.factory(specific_config)
+    return cast(
+        StorageBackend,
+        load_plugin(
+            PluginType.STORAGE,
+            config.backend,
+            specific_config,
+        ),
+    )
 
 
-__all__ = [
-    "StoragePlugin",
-    "StorageFactory",
-    "STORAGE_REGISTRY",
-    "register_storage",
-    "storage_plugin",
-    "create_storage",
-]
+__all__ = ["load_storage_plugin"]

homesec/plugins/storage/dropbox.py

@@ -6,19 +6,29 @@ import asyncio
 import logging
 import os
 from pathlib import Path, PurePosixPath
-from typing import BinaryIO
+from typing import Any, BinaryIO
+
+dropbox: Any
+
+try:
+    import dropbox as _dropbox  # type: ignore[import-untyped]
+except Exception:
+    dropbox = None
+else:
+    dropbox = _dropbox
 
-import dropbox  # type: ignore
 
 from homesec.interfaces import StorageBackend
 from homesec.models.config import DropboxStorageConfig
 from homesec.models.storage import StorageUploadResult
+from homesec.plugins.registry import PluginType, plugin
 
 logger = logging.getLogger(__name__)
 
 CHUNK_SIZE = 4 * 1024 * 1024
 
 
+@plugin(plugin_type=PluginType.STORAGE, name="dropbox")
 class DropboxStorage(StorageBackend):
     """Dropbox storage backend.
 
@@ -30,6 +40,12 @@ class DropboxStorage(StorageBackend):
     2. Refresh token flow: Set DROPBOX_APP_KEY, DROPBOX_APP_SECRET, DROPBOX_REFRESH_TOKEN
     """
 
+    config_cls = DropboxStorageConfig
+
+    @classmethod
+    def create(cls, config: DropboxStorageConfig) -> StorageBackend:
+        return cls(config)
+
     def __init__(self, config: DropboxStorageConfig) -> None:
         """Initialize Dropbox storage with config validation.
 
@@ -47,6 +63,8 @@ class DropboxStorage(StorageBackend):
         self.web_url_prefix = str(config.web_url_prefix)
 
         # Initialize Dropbox client using env vars
+        if dropbox is None:
+            raise RuntimeError("Missing dependency: dropbox. Install with: uv pip install dropbox")
         self.client = self._create_client(config)
         self._shutdown_called = False
 
@@ -57,12 +75,16 @@ class DropboxStorage(StorageBackend):
 
         Tries simple token first, then falls back to refresh token flow.
         """
+        if dropbox is None:
+            raise RuntimeError("Missing dependency: dropbox. Install with: uv pip install dropbox")
+        dbx = dropbox
+
         # Try simple token auth first
         token_var = str(config.token_env)
         token = os.getenv(token_var)
         if token:
             logger.info("Using Dropbox simple token auth")
-            return dropbox.Dropbox(token)
+            return dbx.Dropbox(token)
 
         # Try refresh token flow
         app_key_var = str(config.app_key_env)
@@ -75,7 +97,7 @@ class DropboxStorage(StorageBackend):
 
         if app_key and app_secret and refresh_token:
             logger.info("Using Dropbox refresh token auth")
-            return dropbox.Dropbox(
+            return dbx.Dropbox(
                 app_key=app_key,
                 app_secret=app_secret,
                 oauth2_refresh_token=refresh_token,
@@ -110,13 +132,16 @@ class DropboxStorage(StorageBackend):
 
     def _upload_file(self, local_path: Path, dest_path: str) -> None:
         """Upload file (blocking operation)."""
+        if dropbox is None:
+            raise RuntimeError("Missing dependency: dropbox. Install with: uv pip install dropbox")
+        dbx = dropbox
         file_size = local_path.stat().st_size
         with open(local_path, "rb") as f:
             if file_size <= CHUNK_SIZE:
                 self.client.files_upload(
                     f.read(),
                     dest_path,
-                    mode=dropbox.files.WriteMode.overwrite,
+                    mode=dbx.files.WriteMode.overwrite,
                 )
             else:
                 self._upload_file_chunked(f, dest_path, file_size)
@@ -129,13 +154,16 @@ class DropboxStorage(StorageBackend):
             raise ValueError("Cannot upload empty file")
 
         session = self.client.files_upload_session_start(chunk)
-        cursor = dropbox.files.UploadSessionCursor(
+        if dropbox is None:
+            raise RuntimeError("Missing dependency: dropbox. Install with: uv pip install dropbox")
+        dbx = dropbox
+        cursor = dbx.files.UploadSessionCursor(
             session_id=session.session_id,
             offset=file_handle.tell(),
         )
-        commit = dropbox.files.CommitInfo(
+        commit = dbx.files.CommitInfo(
             path=dest_path,
-            mode=dropbox.files.WriteMode.overwrite,
+            mode=dbx.files.WriteMode.overwrite,
         )
 
         while file_handle.tell() < file_size:
@@ -244,32 +272,3 @@ class DropboxStorage(StorageBackend):
         if path.is_absolute() or ".." in path.parts:
             raise ValueError(f"Invalid dest_path: {dest_path}")
         return f"{self.root}/{path}"
-
-
-# Plugin registration
-from typing import cast
-
-from pydantic import BaseModel
-
-from homesec.interfaces import StorageBackend
-from homesec.plugins.storage import StoragePlugin, storage_plugin
-
-
-@storage_plugin(name="dropbox")
-def dropbox_storage_plugin() -> StoragePlugin:
-    """Dropbox storage plugin factory.
-
-    Returns:
-        StoragePlugin for Dropbox cloud storage
-    """
-    from homesec.models.config import DropboxStorageConfig
-
-    def factory(cfg: BaseModel) -> StorageBackend:
-        # Config is already validated by pydantic when loaded
-        return DropboxStorage(cast(DropboxStorageConfig, cfg))
-
-    return StoragePlugin(
-        name="dropbox",
-        config_model=DropboxStorageConfig,
-        factory=factory,
-    )

homesec/plugins/storage/local.py

@@ -10,13 +10,21 @@ from pathlib import Path, PurePosixPath
 from homesec.interfaces import StorageBackend
 from homesec.models.config import LocalStorageConfig
 from homesec.models.storage import StorageUploadResult
+from homesec.plugins.registry import PluginType, plugin
 
 logger = logging.getLogger(__name__)
 
 
+@plugin(plugin_type=PluginType.STORAGE, name="local")
 class LocalStorage(StorageBackend):
     """Local storage backend for development and tests."""
 
+    config_cls = LocalStorageConfig
+
+    @classmethod
+    def create(cls, config: LocalStorageConfig) -> StorageBackend:
+        return cls(config)
+
     def __init__(self, config: LocalStorageConfig) -> None:
         self.root = Path(config.root).expanduser().resolve()
         self.root.mkdir(parents=True, exist_ok=True)
@@ -79,32 +87,3 @@ class LocalStorage(StorageBackend):
         if path.is_absolute() or ".." in path.parts:
             raise ValueError(f"Invalid dest_path: {dest_path}")
         return self.root.joinpath(*path.parts)
-
-
-# Plugin registration
-from typing import cast
-
-from pydantic import BaseModel
-
-from homesec.interfaces import StorageBackend
-from homesec.plugins.storage import StoragePlugin, storage_plugin
-
-
-@storage_plugin(name="local")
-def local_storage_plugin() -> StoragePlugin:
-    """Local storage plugin factory.
-
-    Returns:
-        StoragePlugin for local filesystem storage
-    """
-    from homesec.models.config import LocalStorageConfig
-
-    def factory(cfg: BaseModel) -> StorageBackend:
-        # Config is already validated by pydantic when loaded
-        return LocalStorage(cast(LocalStorageConfig, cfg))
-
-    return StoragePlugin(
-        name="local",
-        config_model=LocalStorageConfig,
-        factory=factory,
-    )

homesec/plugins/utils.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 from collections.abc import Iterable
 from importlib import metadata
-from typing import TypeVar, cast
+from typing import TypeVar
 
 PluginT = TypeVar("PluginT")
 
@@ -20,10 +20,14 @@ def iter_entry_points(group: str) -> Iterable[metadata.EntryPoint]:
     """
     entry_points = metadata.entry_points()
     if hasattr(entry_points, "select"):
-        # Python 3.10+ API
+        # Python 3.10+ API - SelectableGroups with .select() method
         return entry_points.select(group=group)
-    # Python 3.9 API
-    return cast(dict[str, list[metadata.EntryPoint]], entry_points).get(group, [])
+    # Python 3.9 API - dict[str, list[EntryPoint]]
+    # Type validated at runtime: entry_points is dict-like in Python 3.9
+    if isinstance(entry_points, dict):
+        return entry_points.get(group, [])
+    # Fallback for unexpected types - return empty
+    return []
 
 
 def load_plugin_from_entry_point(