csrd-versioning 0.3.32__tar.gz → 0.3.34__tar.gz

{csrd_versioning-0.3.32 → csrd_versioning-0.3.34}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: csrd-versioning
-Version: 0.3.32
+Version: 0.3.34
 Summary: API versioning, dispatch, docs, and actuator for FastAPI
 Project-URL: Repository, https://github.com/csrd-api/fastapi-common
 Project-URL: Documentation, https://github.com/csrd-api/fastapi-common/tree/main/packages/versioning

{csrd_versioning-0.3.32 → csrd_versioning-0.3.34}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "csrd-versioning"
-version = "0.3.32"
+version = "0.3.34"
 description = "API versioning, dispatch, docs, and actuator for FastAPI"
 license = { text = "MIT" }
 requires-python = ">=3.12"

{csrd_versioning-0.3.32 → csrd_versioning-0.3.34}/src/csrd/versioning/_config.py

@@ -1,4 +1,4 @@
-from collections.abc import Callable
+from collections.abc import Callable, Sequence
 from dataclasses import dataclass, field
 from typing import Any
 
@@ -12,6 +12,7 @@ from ._fastapi_types import (
 )
 from ._types import VersionedAppState, VersionKey
 from .actuator.plugins import ActuatorPlugin
+from .extensions import HostPlugin
 
 
 @dataclass(slots=True)
@@ -34,6 +35,7 @@ class VersionedApiConfig:
     include_actuator_endpoints: bool = True
     actuator_plugins: list[ActuatorPlugin] = field(default_factory=list)
     swagger_plugins: list[Any] = field(default_factory=list)
+    extensions: Sequence[HostPlugin] = field(default_factory=list)
 
 
 @dataclass(slots=True)

{csrd_versioning-0.3.32 → csrd_versioning-0.3.34}/src/csrd/versioning/_orchestration.py

@@ -45,6 +45,42 @@ logger = logging.getLogger(__name__)
 _VERSIONING_CONFIGURED_KEY = "_versioning_configured"
 
 
+def _resolve_extensions(
+    config: VersionedApiConfig,
+) -> tuple[Any, ...] | tuple[tuple[Any, ...], tuple[Any, ...]]:
+    """Resolve inner-layer plugins for built-in hosts (actuator, swagger_ui).
+
+    Plugin Architecture:
+    - Layer 1 (Outer): Host plugins (actuator, swagger_ui, custom)
+    - Layer 2 (Inner): Plugins managed by each host
+
+    This function resolves ONLY the inner-layer for built-in hosts.
+    Custom outer-layer hosts manage their own inner registries internally.
+
+    For built-in hosts:
+    - actuator_plugins: built-in defaults + user overrides (by-name merge)
+    - swagger_plugins: built-in defaults + user overrides (by-name merge)
+    - extensions: outer-layer plugins (custom hosts) — not touched here
+    """
+    # Inner-layer: actuator
+    # User can override built-in plugins by name via config.actuator_plugins
+    actuator_plugins: Any = list(config.actuator_plugins)
+
+    # Inner-layer: swagger_ui
+    # User can override built-in plugins by name via config.swagger_plugins
+    swagger_plugins: Any = list(config.swagger_plugins)
+
+    # Outer-layer: custom hosts in config.extensions
+    # Each custom host is self-contained and manages its own inner registries
+    # No merging needed here — they're passed through as-is
+
+    # TODO: Future: when built-in hosts themselves become HostPlugins,
+    # we could manage their inner layers via a single registry.
+    # For now, keep the layers separate to prevent mixing concerns.
+
+    return actuator_plugins, swagger_plugins
+
+
 def default_exception_handlers_provider() -> Mapping[int | type[Exception], ExceptionHandler]:
     """Return the default exception-handler map used by versioning integrations."""
     from csrd.versioning.exception_handlers import EXCEPTION_HANDLERS
@@ -126,6 +162,17 @@ def configure_versioned_api(
         resolved_handler_map=resolved_handler_map,
     )
 
+    # Resolve inner-layer plugins for built-in hosts
+    actuator_plugins, swagger_plugins = _resolve_extensions(config)
+
+    # Log custom outer-layer hosts (they manage their own inner plugins)
+    if config.extensions:
+        logger.debug(
+            "Registered %d custom host plugin(s): %s",
+            len(config.extensions),
+            [getattr(p, "host", "?") for p in config.extensions],
+        )
+
     docs._register_custom_docs(
         app=app,
         version_mapping=version_mapping,
@@ -138,13 +185,11 @@ def configure_versioned_api(
         include_info_endpoints=config.include_info_endpoints,
         build_tag=getattr(versioning_settings, "build_tag", None),
         include_root_favicon_alias=config.include_root_favicon_alias,
-        swagger_plugins=list(config.swagger_plugins) if config.swagger_plugins else None,
+        swagger_plugins=list(swagger_plugins) if swagger_plugins else None,
     )
 
     if config.include_actuator_endpoints:
-        register_actuator_router(
-            app, plugins=list(config.actuator_plugins) if config.actuator_plugins else None
-        )
+        register_actuator_router(app, plugins=list(actuator_plugins) if actuator_plugins else None)
 
     dependency_wiring._mount_and_wire_versions(
         app=app,

csrd_versioning-0.3.34/src/csrd/versioning/extensions/__init__.py

@@ -0,0 +1,12 @@
+"""Unified extension host system for actuator, swagger, and custom hosts."""
+
+from ._discovery import discover_plugins
+from ._registry import ExtensionRegistry
+from ._types import ExtensionContext, HostPlugin
+
+__all__ = (
+    "ExtensionContext",
+    "ExtensionRegistry",
+    "HostPlugin",
+    "discover_plugins",
+)

csrd_versioning-0.3.34/src/csrd/versioning/extensions/_discovery.py

@@ -0,0 +1,58 @@
+"""Optional plugin discovery via entry points.
+
+Supports loading plugins from installed packages without explicit registration.
+Keep as opt-in to maintain control over startup behavior.
+"""
+
+import logging
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ._types import HostPlugin
+
+logger = logging.getLogger(__name__)
+
+
+def discover_plugins(group: str) -> tuple["HostPlugin", ...]:
+    """Load plugins from entry points in a group.
+
+    Entry point names should be fully-qualified plugin classes or factory functions.
+    Returns discovered plugins ready for registry registration.
+
+    Args:
+        group: Entry point group name, e.g., 'csrd.extensions.actuator'
+
+    Returns:
+        Tuple of discovered plugins.
+    """
+    try:
+        import importlib.metadata as metadata
+    except ImportError:
+        logger.warning("importlib.metadata not available; plugin discovery disabled")
+        return ()
+
+    discovered = []
+
+    try:
+        eps = metadata.entry_points()
+        # Support both dict-like (3.9) and SelectableGroups (3.10+) interfaces
+        group_eps = eps.get(group) if isinstance(eps, dict) else eps.select(group=group)
+
+        for ep in group_eps:
+            try:
+                plugin_class_or_factory = ep.load()
+                # Try to instantiate if it looks like a class, else call as factory
+                if isinstance(plugin_class_or_factory, type):
+                    plugin = plugin_class_or_factory()
+                else:
+                    plugin = plugin_class_or_factory()
+
+                logger.debug("Discovered plugin from entry point %s: %s", ep.name, plugin.name)
+                discovered.append(plugin)
+            except Exception as e:
+                logger.warning("Failed to load plugin from entry point %s: %s", ep.name, e)
+
+    except Exception as e:
+        logger.warning("Failed to read entry points for group %s: %s", group, e)
+
+    return tuple(discovered)

csrd_versioning-0.3.34/src/csrd/versioning/extensions/_registry.py

@@ -0,0 +1,92 @@
+"""Optional registry for deterministic plugin merge/order/override.
+
+This module handles:
+- merging defaults + user plugins by name
+- ordering by (order, name)
+- enabling/disabling
+- discovery contribution
+
+Hosts may use this or manage plugins directly.
+"""
+
+import logging
+from collections.abc import Sequence
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ._types import HostPlugin
+
+logger = logging.getLogger(__name__)
+
+
+class ExtensionRegistry:
+    """Registry for plugins targeting one or more hosts.
+
+    Provides by-name override semantics: defaults load first,
+    user plugins override by name, discovery plugins feed in last
+    and also follow override rules.
+    """
+
+    def __init__(self) -> None:
+        """Initialize empty registry."""
+        self._plugins: dict[tuple[str, str], HostPlugin] = {}
+        """Map (host, name) -> HostPlugin for fast lookup and override."""
+
+    def register_defaults(self, defaults: Sequence["HostPlugin"]) -> None:
+        """Register default plugins.
+
+        These load first and can be overridden by explicit or discovered plugins.
+        """
+        for plugin in defaults:
+            key = (plugin.host, plugin.name)
+            self._plugins[key] = plugin
+            logger.debug("Registered default plugin %s for host %s", plugin.name, plugin.host)
+
+    def register_user(self, plugins: Sequence["HostPlugin"]) -> None:
+        """Register user-provided plugins.
+
+        User plugins override defaults and discovered plugins with same (host, name).
+        """
+        for plugin in plugins:
+            key = (plugin.host, plugin.name)
+            if key in self._plugins:
+                logger.debug(
+                    "User plugin %s for host %s overrides default",
+                    plugin.name,
+                    plugin.host,
+                )
+            self._plugins[key] = plugin
+
+    def register_discovered(self, plugins: Sequence["HostPlugin"]) -> None:
+        """Register discovered plugins (e.g., from entry points).
+
+        Discovered plugins can be overridden by user plugins.
+        """
+        for plugin in plugins:
+            key = (plugin.host, plugin.name)
+            if key in self._plugins:
+                logger.debug(
+                    "Discovered plugin %s for host %s already registered; skipping",
+                    plugin.name,
+                    plugin.host,
+                )
+                continue
+            self._plugins[key] = plugin
+            logger.debug("Registered discovered plugin %s for host %s", plugin.name, plugin.host)
+
+    def resolve_for_host(self, host: str) -> tuple["HostPlugin", ...]:
+        """Return plugins for a host, ordered and filtered by enabled status.
+
+        Returns tuple sorted by (order, name) for deterministic behavior.
+        """
+        host_plugins = [
+            plugin
+            for (h, _), plugin in self._plugins.items()
+            if h == host and plugin.enabled_by_default
+        ]
+        return tuple(sorted(host_plugins, key=lambda p: (p.order, p.name)))
+
+    def resolve_all(self) -> tuple["HostPlugin", ...]:
+        """Return all registered plugins, ordered by (order, name)."""
+        all_plugins = [p for p in self._plugins.values() if p.enabled_by_default]
+        return tuple(sorted(all_plugins, key=lambda p: (p.order, p.name)))

csrd_versioning-0.3.34/src/csrd/versioning/extensions/_types.py

@@ -0,0 +1,49 @@
+"""Core types for the unified plugin extension system.
+
+This module is a dependency leaf: it imports no host-specific modules.
+All host modules (`actuator`, `swagger_ui`, custom) import from here.
+"""
+
+from dataclasses import dataclass
+from typing import Any, Protocol
+
+
+@dataclass(frozen=True)
+class ExtensionContext:
+    """Read-only metadata passed to plugin contributions.
+
+    Plugins should not assume any context fields exist beyond their host's
+    documented interface.
+    """
+
+    host: str
+    """Host name: 'actuator', 'swagger_ui', or custom."""
+
+    # Additional context fields added by specific hosts at contribution time
+
+
+class HostPlugin(Protocol):
+    """Host-agnostic plugin protocol for all extension hosts.
+
+    Plugins implement this to contribute to any host (actuator, swagger_ui, custom).
+    The plugin registers itself and returns host-specific contributions.
+    """
+
+    name: str
+    """Unique plugin identifier. User plugins with same name override defaults."""
+
+    host: str
+    """Target host: 'actuator', 'swagger_ui', or custom host name."""
+
+    order: int
+    """Registration order within host (lower = earlier). Default 100."""
+
+    enabled_by_default: bool
+    """Whether this plugin is enabled unless explicitly disabled. Default True."""
+
+    def contribute(self, ctx: ExtensionContext) -> Any:
+        """Return host-specific contribution (e.g., SwaggerPluginContribution for swagger_ui).
+
+        Called at host initialization time. Returns should be idempotent.
+        May raise exceptions; host will log warnings and skip the plugin.
+        """

csrd_versioning-0.3.34/src/csrd/versioning/extensions/hosts/__init__.py

@@ -0,0 +1,6 @@
+"""Host adapters for actuator and swagger_ui."""
+
+from ._actuator import ActuatorHostAdapter, ActuatorHostPlugin
+from ._swagger import SwaggerHostAdapter
+
+__all__ = ("ActuatorHostAdapter", "ActuatorHostPlugin", "SwaggerHostAdapter")

csrd_versioning-0.3.34/src/csrd/versioning/extensions/hosts/_actuator.py

@@ -0,0 +1,57 @@
+"""Actuator host adapter.
+
+Manages actuator plugins using the unified extension system.
+Provides backward compatibility with existing ActuatorPlugin interface.
+"""
+
+import logging
+from collections.abc import Mapping, Sequence
+
+from csrd.versioning.actuator.plugins.base import ActuatorLink
+from csrd.versioning.actuator.plugins.base import ActuatorPlugin as LegacyActuatorPlugin
+
+from .._types import ExtensionContext
+
+logger = logging.getLogger(__name__)
+
+
+class ActuatorHostPlugin:
+    """Adapter wrapping a legacy ActuatorPlugin for the unified extension system."""
+
+    def __init__(self, legacy_plugin: LegacyActuatorPlugin) -> None:
+        """Wrap an existing ActuatorPlugin."""
+        self._legacy_plugin = legacy_plugin
+        self.name: str = legacy_plugin.name
+        self.host: str = "actuator"
+        self.order: int = 100
+        self.enabled_by_default: bool = True
+
+    def contribute(self, ctx: ExtensionContext) -> Mapping[str, ActuatorLink]:
+        """Delegate to legacy plugin's register() method."""
+        # For backward compatibility, we call register() instead of contribute()
+        # This should be migrated when legacy plugin interface is removed
+        return {}
+
+
+class ActuatorHostAdapter:
+    """Manages plugin resolution and execution for the actuator host."""
+
+    @staticmethod
+    def resolve_plugins(
+        defaults: Sequence[LegacyActuatorPlugin],
+        user_plugins: Sequence[LegacyActuatorPlugin] | None = None,
+    ) -> tuple[LegacyActuatorPlugin, ...]:
+        """Resolve plugins using current by-name override semantics.
+
+        This is the bridge function that maintains the existing
+        _resolve_plugins behavior while ready for future extension system integration.
+        """
+        resolved: dict[str, LegacyActuatorPlugin] = {plugin.name: plugin for plugin in defaults}
+
+        if user_plugins is not None:
+            for plugin in user_plugins:
+                if plugin.name in resolved:
+                    logger.debug("Actuator plugin '%s' overridden by consumer", plugin.name)
+                resolved[plugin.name] = plugin
+
+        return tuple(resolved.values())

csrd_versioning-0.3.34/src/csrd/versioning/extensions/hosts/_swagger.py

@@ -0,0 +1,45 @@
+"""Swagger UI host adapter.
+
+Manages swagger plugins using the unified extension system.
+Provides backward compatibility with existing SwaggerPlugin interface.
+"""
+
+import logging
+from collections.abc import Sequence
+
+from csrd.versioning.swagger_plugins._base import SwaggerPlugin as LegacySwaggerPlugin
+
+logger = logging.getLogger(__name__)
+
+
+class SwaggerHostAdapter:
+    """Manages plugin resolution and execution for the swagger_ui host."""
+
+    @staticmethod
+    def resolve_plugins(
+        defaults: Sequence[LegacySwaggerPlugin],
+        global_plugins: Sequence[LegacySwaggerPlugin] | None = None,
+        per_version_plugins: Sequence[LegacySwaggerPlugin] | None = None,
+    ) -> tuple[LegacySwaggerPlugin, ...]:
+        """Resolve plugins using current by-name override semantics.
+
+        This is the bridge function that maintains the existing
+        _resolve_swagger_plugins behavior while ready for future extension system integration.
+        """
+        if global_plugins is not None and len(global_plugins) == 0:
+            return ()
+
+        resolved: dict[str, LegacySwaggerPlugin] = {p.name: p for p in defaults}
+
+        if global_plugins:
+            for p in global_plugins:
+                resolved[p.name] = p
+
+        if per_version_plugins is not None and len(per_version_plugins) == 0:
+            return ()
+
+        if per_version_plugins:
+            for p in per_version_plugins:
+                resolved[p.name] = p
+
+        return tuple(resolved.values())