provide-foundation 0.0.0.dev0__py3-none-any.whl

provide/foundation/hub/decorators.py

@@ -0,0 +1,244 @@
+"""Command registration decorators."""
+
+from collections.abc import Callable
+from typing import Any, TypeVar, overload
+
+try:
+    import click
+
+    _HAS_CLICK = True
+except ImportError:
+    click = None
+    _HAS_CLICK = False
+
+
+# Defer click_builder import to avoid circular dependency
+def _get_ensure_parent_groups():
+    if not _HAS_CLICK:
+        return None
+    from provide.foundation.hub.click_builder import ensure_parent_groups
+
+    return ensure_parent_groups
+
+
+from provide.foundation.hub.info import CommandInfo
+from provide.foundation.hub.registry import Registry, get_command_registry
+from provide.foundation.logger import get_logger
+
+log = get_logger(__name__)
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+@overload
+def register_command(
+    name: str | None = None,
+    *,
+    description: str | None = None,
+    aliases: list[str] | None = None,
+    hidden: bool = False,
+    category: str | None = None,
+    group: bool = False,
+    replace: bool = False,
+    registry: Registry | None = None,
+) -> Callable[[F], F]: ...
+
+
+@overload
+def register_command(
+    func: F,
+    /,
+) -> F: ...
+
+
+def register_command(
+    name_or_func: str | F | None = None,
+    *,
+    description: str | None = None,
+    aliases: list[str] | None = None,
+    hidden: bool = False,
+    category: str | None = None,
+    group: bool = False,
+    replace: bool = False,
+    registry: Registry | None = None,
+    **metadata: Any,
+) -> Any:
+    """
+    Register a CLI command in the hub.
+
+    Can be used as a decorator with or without arguments:
+
+        @register_command
+        def my_command():
+            pass
+
+        @register_command("custom-name", aliases=["cn"], category="utils")
+        def my_command():
+            pass
+
+        # Nested commands using dot notation - groups are auto-created
+        @register_command("container.status")
+        def container_status():
+            pass
+
+        @register_command("container.volumes.backup")
+        def container_volumes_backup():
+            pass
+
+        # Explicit group with custom description (optional)
+        @register_command("container", group=True, description="Container management")
+        def container_group():
+            pass
+
+    Args:
+        name_or_func: Command name using dot notation for nesting (e.g., "container.status")
+        description: Command description (defaults to docstring)
+        aliases: Alternative names for the command
+        hidden: Whether to hide from help listing
+        category: Command category for grouping
+        group: Whether this is a command group (not a command)
+        replace: Whether to replace existing registration
+        registry: Custom registry (defaults to global)
+
+    Returns:
+        Decorator function or decorated function
+    """
+    # Handle @register_command (without parens)
+    if callable(name_or_func) and not isinstance(name_or_func, str):
+        func = name_or_func
+        return _register_command_func(
+            func,
+            name=None,
+            description=description,
+            aliases=aliases,
+            hidden=hidden,
+            category=category,
+            group=group,
+            replace=replace,
+            registry=registry,
+            **metadata,
+        )
+
+    # Handle @register_command(...) (with arguments)
+    def decorator(func: F) -> F:
+        return _register_command_func(
+            func,
+            name=name_or_func,
+            description=description,
+            aliases=aliases,
+            hidden=hidden,
+            category=category,
+            group=group,
+            replace=replace,
+            registry=registry,
+            **metadata,
+        )
+
+    return decorator
+
+
+def _register_command_func(
+    func: F,
+    *,
+    name: str | None = None,
+    description: str | None = None,
+    aliases: list[str] | None = None,
+    hidden: bool = False,
+    category: str | None = None,
+    group: bool = False,
+    replace: bool = False,
+    registry: Registry | None = None,
+    **extra_metadata: Any,
+) -> F:
+    """Internal function to register a command."""
+    reg = registry or get_command_registry()
+
+    # Determine command name and parent from dot notation
+    if name:
+        parts = name.split(".")
+        if len(parts) > 1:
+            # Extract parent path and command name
+            parent = ".".join(parts[:-1])
+            command_name = parts[-1]
+
+            # Auto-create parent groups if they don't exist (click only)
+            if _HAS_CLICK:
+                ensure_parent_groups_fn = _get_ensure_parent_groups()
+                if ensure_parent_groups_fn:
+                    ensure_parent_groups_fn(parent, reg)
+        else:
+            parent = None
+            command_name = name
+    else:
+        # Use function name as command name
+        parent = None
+        command_name = func.__name__
+
+    # Check if it's already a Click command
+    click_cmd = None
+    if isinstance(func, click.Command):
+        click_cmd = func
+        actual_func = func.callback
+    else:
+        actual_func = func
+
+    # Create command info
+    cmd_metadata = {"is_group": group}
+    cmd_metadata.update(extra_metadata)
+
+    info = CommandInfo(
+        name=command_name,
+        func=actual_func,
+        description=description or (actual_func.__doc__ if actual_func else None),
+        aliases=aliases or [],
+        hidden=hidden,
+        category=category,
+        metadata=cmd_metadata,
+        click_command=click_cmd,
+        parent=parent,
+    )
+
+    # Build full registry key
+    full_name = f"{parent}.{command_name}" if parent else command_name
+
+    # Build registry metadata
+    reg_metadata = {
+        "info": info,
+        "description": info.description,
+        "aliases": info.aliases,
+        "hidden": hidden,
+        "category": category,
+        "parent": parent,
+        "is_group": group,
+        "click_command": click_cmd,
+    }
+    reg_metadata.update(extra_metadata)
+
+    # Register in the registry
+    reg.register(
+        name=full_name,
+        value=func,
+        dimension="command",
+        metadata=reg_metadata,
+        aliases=aliases,
+        replace=replace,
+    )
+
+    # Add metadata to the function
+    func.__registry_name__ = command_name
+    func.__registry_dimension__ = "command"
+    func.__registry_info__ = info
+
+    log.info(
+        "Registered command",
+        name=command_name,
+        parent=parent,
+        aliases=aliases,
+        hidden=hidden,
+        category=category,
+    )
+
+    return func
+
+
+__all__ = ["register_command"]

provide/foundation/hub/info.py

@@ -0,0 +1,32 @@
+"""Command information and metadata structures."""
+
+from collections.abc import Callable
+from typing import Any
+
+from attrs import define, field
+
+try:
+    import click
+
+    _HAS_CLICK = True
+except ImportError:
+    click = None
+    _HAS_CLICK = False
+
+
+@define(frozen=True, slots=True)
+class CommandInfo:
+    """Information about a registered command."""
+
+    name: str
+    func: Callable[..., Any]
+    description: str | None = None
+    aliases: list[str] = field(factory=lambda: [])
+    hidden: bool = False
+    category: str | None = None
+    metadata: dict[str, Any] = field(factory=lambda: {})
+    click_command: "click.Command | None" = None
+    parent: str | None = None  # Parent path extracted from dot notation
+
+
+__all__ = ["CommandInfo"]

provide/foundation/hub/manager.py

@@ -0,0 +1,446 @@
+"""
+Hub manager - the main coordinator for components and commands.
+
+This module provides the Hub class that coordinates component and command
+registration, discovery, and access.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+import threading
+from typing import Any
+
+try:
+    import click
+
+    _HAS_CLICK = True
+except ImportError:
+    click = None
+    _HAS_CLICK = False
+
+from provide.foundation.context import Context
+from provide.foundation.errors.config import ValidationError
+from provide.foundation.errors.decorators import with_error_handling
+from provide.foundation.errors.resources import AlreadyExistsError
+from provide.foundation.hub.commands import (
+    CommandInfo,
+    get_command_registry,
+)
+from provide.foundation.hub.components import (
+    ComponentInfo,
+    discover_components as _discover_components,
+    get_component_registry,
+)
+from provide.foundation.hub.registry import Registry
+from provide.foundation.logger import get_logger
+
+log = get_logger(__name__)
+
+
+class Hub:
+    """
+    Central hub for managing components and commands.
+
+    The Hub provides a unified interface for:
+    - Registering components and commands
+    - Discovering plugins via entry points
+    - Creating Click CLI applications
+    - Managing component lifecycle
+
+    Example:
+        >>> hub = Hub()
+        >>> hub.add_component(MyResource, "resource")
+        >>> hub.add_command(init_cmd, "init")
+        >>>
+        >>> # Create CLI with all commands
+        >>> cli = hub.create_cli()
+        >>> cli()
+    """
+
+    def __init__(
+        self,
+        context: Context | None = None,
+        component_registry: Registry | None = None,
+        command_registry: Registry | None = None,
+    ) -> None:
+        """
+        Initialize the hub.
+
+        Args:
+            context: Foundation context for configuration
+            component_registry: Custom component registry
+            command_registry: Custom command registry
+        """
+        self.context = context or Context()
+        self._component_registry = component_registry or get_component_registry()
+        self._command_registry = command_registry or get_command_registry()
+        self._cli_group: click.Group | None = None
+
+    # Component Management
+
+    @with_error_handling(
+        context_provider=lambda: {"hub": "add_component"},
+        error_mapper=lambda e: ValidationError(
+            f"Failed to add component: {e}", code="HUB_COMPONENT_ADD_ERROR", cause=e
+        )
+        if not isinstance(e, AlreadyExistsError | ValidationError)
+        else e,
+    )
+    def add_component(
+        self,
+        component_class: type[Any],
+        name: str | None = None,
+        dimension: str = "component",
+        **metadata: Any,
+    ) -> ComponentInfo:
+        """
+        Add a component to the hub.
+
+        Args:
+            component_class: Component class to register
+            name: Optional name (defaults to class name)
+            dimension: Registry dimension
+            **metadata: Additional metadata
+
+        Returns:
+            ComponentInfo for the registered component
+
+        Raises:
+            AlreadyExistsError: If component is already registered
+            ValidationError: If component class is invalid
+        """
+        if not isinstance(component_class, type):
+            raise ValidationError(
+                f"Component must be a class, got {type(component_class).__name__}",
+                code="HUB_INVALID_COMPONENT",
+                component_type=type(component_class).__name__,
+            )
+
+        component_name = name or component_class.__name__
+
+        # Check if already exists
+        if self._component_registry.get_entry(component_name, dimension=dimension):
+            raise AlreadyExistsError(
+                f"Component '{component_name}' already registered in dimension '{dimension}'",
+                code="HUB_COMPONENT_EXISTS",
+                component_name=component_name,
+                dimension=dimension,
+            )
+
+        info = ComponentInfo(
+            name=component_name,
+            component_class=component_class,
+            dimension=dimension,
+            version=metadata.get("version"),
+            description=metadata.get("description", component_class.__doc__),
+            author=metadata.get("author"),
+            tags=metadata.get("tags", []),
+            metadata=metadata,
+        )
+
+        self._component_registry.register(
+            name=component_name,
+            value=component_class,
+            dimension=dimension,
+            metadata={"info": info, **metadata},
+            replace=False,  # Don't allow replacement by default
+        )
+
+        log.info(
+            "Added component to hub",
+            name=component_name,
+            dimension=dimension,
+        )
+
+        return info
+
+    def get_component(
+        self,
+        name: str,
+        dimension: str | None = None,
+    ) -> type[Any] | None:
+        """
+        Get a component by name.
+
+        Args:
+            name: Component name
+            dimension: Optional dimension filter
+
+        Returns:
+            Component class or None
+        """
+        return self._component_registry.get(name, dimension)
+
+    def list_components(
+        self,
+        dimension: str | None = None,
+    ) -> list[str]:
+        """
+        List component names.
+
+        Args:
+            dimension: Optional dimension filter
+
+        Returns:
+            List of component names
+        """
+        if dimension:
+            return self._component_registry.list_dimension(dimension)
+
+        # List all non-command dimensions
+        all_items = self._component_registry.list_all()
+        components = []
+        for dim, names in all_items.items():
+            if dim != "command":
+                components.extend(names)
+        return components
+
+    def discover_components(
+        self,
+        group: str,
+        dimension: str = "component",
+    ) -> dict[str, type[Any]]:
+        """
+        Discover and register components from entry points.
+
+        Args:
+            group: Entry point group name
+            dimension: Dimension to register under
+
+        Returns:
+            Dictionary of discovered components
+        """
+        return _discover_components(group, dimension, self._component_registry)
+
+    # Command Management
+
+    def add_command(
+        self,
+        func: Callable[..., Any] | click.Command,
+        name: str | None = None,
+        **kwargs: Any,
+    ) -> CommandInfo:
+        """
+        Add a CLI command to the hub.
+
+        Args:
+            func: Command function or Click command
+            name: Optional name (defaults to function name)
+            **kwargs: Additional command options
+
+        Returns:
+            CommandInfo for the registered command
+        """
+        if _HAS_CLICK and isinstance(func, click.Command):
+            command_name = name or func.name
+            command_func = func.callback
+            click_command = func
+        else:
+            command_name = name or func.__name__.replace("_", "-")
+            command_func = func
+            click_command = None
+
+        info = CommandInfo(
+            name=command_name,
+            func=command_func,
+            description=kwargs.get("description", getattr(func, "__doc__", None)),
+            aliases=kwargs.get("aliases", []),
+            hidden=kwargs.get("hidden", False),
+            category=kwargs.get("category"),
+            metadata=kwargs,
+            click_command=click_command,
+        )
+
+        self._command_registry.register(
+            name=command_name,
+            value=func,
+            dimension="command",
+            metadata={
+                "info": info,
+                "click_command": click_command,
+                **kwargs,
+            },
+            aliases=info.aliases,
+        )
+
+        # Add to CLI group if it exists
+        if self._cli_group and click_command:
+            self._cli_group.add_command(click_command)
+
+        log.info(
+            "Added command to hub",
+            name=command_name,
+            aliases=info.aliases,
+        )
+
+        return info
+
+    def get_command(self, name: str) -> Callable[..., Any] | None:
+        """
+        Get a command by name.
+
+        Args:
+            name: Command name or alias
+
+        Returns:
+            Command function or None
+        """
+        return self._command_registry.get(name, dimension="command")
+
+    def list_commands(self) -> list[str]:
+        """
+        List all command names.
+
+        Returns:
+            List of command names
+        """
+        return self._command_registry.list_dimension("command")
+
+    # CLI Integration
+
+    def create_cli(
+        self,
+        name: str = "cli",
+        version: str | None = None,
+        **kwargs: Any,
+    ) -> click.Group:
+        """
+        Create a Click CLI with all registered commands.
+
+        Requires click to be installed.
+
+        Args:
+            name: CLI name
+            version: CLI version
+            **kwargs: Additional Click Group options
+
+        Returns:
+            Click Group with registered commands
+
+        Example:
+            >>> hub = get_hub()
+            >>> cli = hub.create_cli("myapp", version="1.0.0")
+            >>>
+            >>> if __name__ == "__main__":
+            >>>     cli()
+        """
+        if not _HAS_CLICK:
+            raise ImportError(
+                "CLI creation requires: pip install 'provide-foundation[cli]'"
+            )
+
+        from provide.foundation.hub.commands import create_command_group
+
+        # Use create_command_group which now handles nested groups
+        cli = create_command_group(name=name, registry=self._command_registry, **kwargs)
+
+        # Add version option if provided
+        if version:
+            cli = click.version_option(version=version)(cli)
+
+        self._cli_group = cli
+        return cli
+
+    def add_cli_group(self, group: click.Group) -> None:
+        """
+        Add an existing Click group to the hub.
+
+        This registers all commands from the group.
+
+        Args:
+            group: Click Group to add
+        """
+        for name, cmd in group.commands.items():
+            self.add_command(cmd, name)
+
+    # Lifecycle Management
+
+    def initialize(self) -> None:
+        """Initialize all components that support initialization."""
+        for entry in self._component_registry:
+            if entry.dimension == "command":
+                continue
+
+            component_class = entry.value
+            if hasattr(component_class, "initialize"):
+                try:
+                    component_class.initialize()
+                    log.debug(f"Initialized component: {entry.name}")
+                except Exception as e:
+                    log.error(f"Failed to initialize {entry.name}: {e}")
+
+    def cleanup(self) -> None:
+        """Cleanup all components that support cleanup."""
+        for entry in self._component_registry:
+            if entry.dimension == "command":
+                continue
+
+            component_class = entry.value
+            if hasattr(component_class, "cleanup"):
+                try:
+                    component_class.cleanup()
+                    log.debug(f"Cleaned up component: {entry.name}")
+                except Exception as e:
+                    log.error(f"Failed to cleanup {entry.name}: {e}")
+
+    def clear(self, dimension: str | None = None) -> None:
+        """
+        Clear registrations.
+
+        Args:
+            dimension: Optional dimension to clear (None = all)
+        """
+        if dimension == "command" or dimension is None:
+            self._command_registry.clear(dimension="command" if dimension else None)
+            self._cli_group = None
+
+        if dimension != "command" or dimension is None:
+            self._component_registry.clear(dimension=dimension)
+
+    def __enter__(self) -> Hub:
+        """Context manager entry."""
+        self.initialize()
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        """Context manager exit."""
+        self.cleanup()
+
+
+# Global hub instance and lock for thread-safe initialization
+_global_hub: Hub | None = None
+_hub_lock = threading.Lock()
+
+
+def get_hub() -> Hub:
+    """
+    Get the global hub instance.
+
+    Thread-safe: Uses double-checked locking pattern for efficient lazy initialization.
+
+    Returns:
+        Global Hub instance (created if needed)
+    """
+    global _global_hub
+
+    # Fast path: hub already initialized
+    if _global_hub is not None:
+        return _global_hub
+
+    # Slow path: need to initialize hub
+    with _hub_lock:
+        # Double-check after acquiring lock
+        if _global_hub is None:
+            _global_hub = Hub()
+
+    return _global_hub
+
+
+def clear_hub() -> None:
+    """Clear the global hub instance."""
+    global _global_hub
+    with _hub_lock:
+        if _global_hub:
+            _global_hub.clear()
+        _global_hub = None