click-extended 1.0.0__py3-none-any.whl → 1.0.1__py3-none-any.whl

click_extended/core/nodes/child_validation_node.py

@@ -0,0 +1,100 @@
+"""
+Child validation node module for nodes that can
+act as both child and validation nodes.
+"""
+
+from abc import ABC
+from functools import wraps
+from typing import TYPE_CHECKING, Any, Callable, ParamSpec, TypeVar
+
+from click_extended.core.nodes.child_node import ChildNode
+from click_extended.core.nodes.validation_node import ValidationNode
+from click_extended.utils.casing import Casing
+
+if TYPE_CHECKING:
+    from click_extended.types import Decorator
+
+
+P = ParamSpec("P")
+T = TypeVar("T")
+
+
+class ChildValidationNode(ChildNode, ValidationNode, ABC):
+    """
+    Base class for nodes acting as both ChildNode and ValidationNode.
+
+    ChildValidationNodes adapt their behavior based on
+    decorator placement:
+
+    - **Child Mode**: When attached to a parent node (option, argument,
+      env) or tag, the node acts as a ChildNode and processes values
+      using handler methods (handle_str, handle_int, handle_all, etc.).
+
+    - **Validation Mode**: When used standalone (not attached to a
+      parent), the node acts as a ValidationNode and runs lifecycle
+      hooks (on_init, on_finalize) at the tree level with access to
+      all parent values via context.
+
+    Example:
+        ```python
+        class RequiresAdmin(HybridNode):
+            def handle_all(self, value: Any, context: Context) -> Any:
+                # Called when attached to parent (child mode)
+                if not context.get("is_admin"):
+                    raise ValueError("Admin access required")
+                return value
+
+            def on_finalize(self, context: Context) -> None:
+                # Called when standalone (validation mode)
+                if not context.get("is_admin"):
+                    raise ValueError("Admin access required")
+
+        # Child mode - processes 'username' value
+        @command()
+        @option("username", type=str)
+        @RequiresAdmin.as_decorator()
+        def cmd1(username: str): pass
+
+        # Validation mode - runs after all processing
+        @command()
+        @option("username", type=str)
+        @RequiresAdmin.as_decorator()
+        def cmd2(username: str): pass
+        ```
+    """
+
+    @classmethod
+    def as_decorator(cls, *args: Any, **kwargs: Any) -> "Decorator":
+        """
+        Return a decorator representation of the child validation node.
+
+        Args:
+            *args (Any):
+                Positional arguments to pass to handler/lifecycle
+                methods.
+            **kwargs (Any):
+                Keyword arguments to pass to handler/lifecycle methods.
+
+        Returns:
+            Decorator:
+                A decorator function that registers the child
+                validation node.
+        """
+        from click_extended.core.other._tree import Tree
+
+        def decorator(func: Callable[P, T]) -> Callable[P, T]:
+            """The actual decorator that wraps the function."""
+            name = Casing.to_snake_case(cls.__name__)
+            instance = cls(name=name, process_args=args, process_kwargs=kwargs)
+            Tree.queue_child_validation(instance)
+
+            @wraps(func)
+            def wrapper(*call_args: P.args, **call_kwargs: P.kwargs) -> T:
+                return func(*call_args, **call_kwargs)
+
+            return wrapper
+
+        return decorator
+
+
+__all__ = ["ChildValidationNode"]

click_extended/core/nodes/node.py

@@ -0,0 +1,55 @@
+"""Base Node class for all nodes in the tree structure."""
+
+from abc import ABC
+
+
+class Node(ABC):
+    """Base node class for all nodes in the tree structure."""
+
+    def __init__(
+        self, name: str, children: dict[str | int, "Node"] | None = None
+    ) -> None:
+        """
+        Initialize a new `Node` instance.
+
+        Args:
+            name (str):
+                The name of the node.
+            children (dict[str | int, Node] | None, optional):
+                Optional dictionary mapping child identifiers to child nodes.
+        """
+        self.name = name
+        self._children = children if children is not None else {}
+
+    @property
+    def children(self) -> dict[str | int, "Node"]:
+        """Get the children of this node."""
+        return self._children
+
+    @children.setter
+    def children(self, value: dict[str | int, "Node"] | None) -> None:
+        """Set the children of this node."""
+        self._children = value if value is not None else {}
+
+    def __getitem__(self, key: str | int) -> "Node":
+        """Get a child node by key."""
+        return self._children[key]
+
+    def __setitem__(self, key: str | int, value: "Node") -> None:
+        """Set a child node by key."""
+        self._children[key] = value
+
+    def __len__(self) -> int:
+        """Get the number of children."""
+        return len(self._children)
+
+    def __str__(self) -> str:
+        return repr(self)
+
+    def __repr__(self) -> str:
+        class_name = self.__class__.__name__
+        custom_name = self.name
+        return f"<{class_name} name='{custom_name}'>"
+
+
+__all__ = ["Node"]

click_extended/core/nodes/option_node.py

@@ -0,0 +1,205 @@
+"""OptionNode abstract base class for CLI option nodes."""
+
+# pylint: disable=too-many-arguments
+# pylint: disable=too-many-positional-arguments
+# pylint: disable=redefined-builtin
+# pylint: disable=arguments-differ
+# pylint: disable=line-too-long
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING, Any, Callable, ParamSpec, Type, TypeVar
+
+from click_extended.core.nodes.parent_node import ParentNode
+from click_extended.utils.casing import Casing
+
+if TYPE_CHECKING:
+    from click_extended.core.other.context import Context
+
+P = ParamSpec("P")
+T = TypeVar("T")
+
+
+class OptionNode(ParentNode, ABC):
+    """
+    Abstract base class for nodes that receive CLI option values.
+
+    OptionNode extends ParentNode to handle command-line options (flags).
+    The key difference is that the `load()` method receives a `value`
+    parameter containing the parsed CLI option value.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        param: str | None = None,
+        short_flags: list[str] | None = None,
+        long_flags: list[str] | None = None,
+        is_flag: bool = False,
+        type: Type[Any] | None = None,
+        nargs: int = 1,
+        multiple: bool = False,
+        help: str | None = None,
+        required: bool = False,
+        default: Any = None,
+        tags: str | list[str] | None = None,
+        **kwargs: Any,
+    ):
+        """
+        Initialize a new `OptionNode` instance.
+
+        Args:
+            name (str):
+                The option name (parameter name for injection).
+            param (str, optional):
+                Custom parameter name for the function.
+                If not provided, uses `name`.
+            short_flags (list[str], optional):
+                Short flags for the option (e.g., ["-p", "-P"]).
+            long_flags (list[str], optional):
+                Long flags for the option (e.g., ["--port", "--p"]).
+                If not provided, auto-generates ["--kebab-case(name)"].
+            is_flag (bool):
+                Whether this is a boolean flag (no value needed).
+                Defaults to `False`.
+            type (Type[Any], optional):
+                The type to convert the value to (`int`, `str`, `float`, `bool`).
+            nargs (int):
+                Number of arguments each occurrence accepts. Defaults to `1`.
+            multiple (bool):
+                Whether the option can be provided multiple times.
+                Defaults to `False`.
+            help (str, optional):
+                Help text for this option.
+            required (bool):
+                Whether this option is required. Defaults to `False`.
+            default (Any):
+                Default value if not provided. Defaults to `None`.
+            tags (str | list[str], optional):
+                Tag(s) to associate with this option for grouping.
+            **kwargs (Any):
+                Additional keyword arguments passed to parent class.
+        """
+        super().__init__(
+            name=param if param is not None else name,
+            param=param,
+            help=help,
+            required=required,
+            default=default,
+            tags=tags,
+            **kwargs,
+        )
+        self.short_flags = short_flags if short_flags is not None else []
+        self.long_flags = (
+            long_flags
+            if long_flags is not None and len(long_flags) > 0
+            else [f"--{Casing.to_kebab_case(name)}"]
+        )
+        self.is_flag = is_flag
+        self.type = type
+        self.nargs = nargs
+        self.multiple = multiple
+
+    @abstractmethod
+    def load(
+        self,
+        value: str | int | float | bool | None,
+        context: "Context",
+        *args: Any,
+        **kwargs: Any,
+    ) -> Any:
+        """
+        Load and process the CLI option value.
+
+        This method is called with the parsed CLI option value and should
+        return the processed value to be injected into the function.
+
+        Args:
+            value (str | int | float | bool | None):
+                The parsed CLI option value from Click.
+            context (Context):
+                The current context instance.
+            *args (Any):
+                Optional positional arguments.
+            **kwargs (Any):
+                Optional keyword arguments.
+
+        Returns:
+            Any:
+                The processed value to inject into the function.
+        """
+        raise NotImplementedError
+
+    @classmethod
+    def as_decorator(
+        cls,
+        *,
+        name: str,
+        param: str | None = None,
+        short_flags: list[str] | None = None,
+        long_flags: list[str] | None = None,
+        is_flag: bool = False,
+        type: Type[Any] | None = None,
+        nargs: int = 1,
+        multiple: bool = False,
+        help: str | None = None,
+        required: bool = False,
+        default: Any = None,
+        tags: str | list[str] | None = None,
+        **kwargs: Any,
+    ) -> Callable[[Callable[P, T]], Callable[P, T]]:
+        """
+        Return a decorator representation of the option node.
+
+        Args:
+            name (str):
+                The option name (parameter name for injection).
+            param (str, optional):
+                Custom parameter name for the function.
+                If not provided, uses `name`.
+            short_flags (list[str], optional):
+                Short flags for the option (e.g., ["-p", "-P"]).
+            long_flags (list[str], optional):
+                Long flags for the option (e.g., ["--port", "--p"]).
+            is_flag (bool):
+                Whether this is a boolean flag (no value needed).
+                Defaults to `False`.
+            type (Type[Any], optional):
+                The type to convert the value to (`int`, `str`, `float`, `bool`).
+            nargs (int):
+                Number of arguments each occurrence accepts. Defaults to `1`.
+            multiple (bool):
+                Whether the option can be provided multiple times.
+                Defaults to `False`.
+            help (str, optional):
+                Help text for this option.
+            required (bool):
+                Whether this option is required. Defaults to `False`.
+            default (Any):
+                Default value if not provided. Defaults to `None`.
+            tags (str | list[str], optional):
+                Tag(s) to associate with this option for grouping.
+            **kwargs (Any):
+                Additional keyword arguments passed to __init__ and load().
+
+        Returns:
+            Callable:
+                A decorator function that registers the option node.
+        """
+        return super().as_decorator(
+            name=name,
+            param=param,
+            short_flags=short_flags,
+            long_flags=long_flags,
+            is_flag=is_flag,
+            type=type,
+            nargs=nargs,
+            multiple=multiple,
+            help=help,
+            required=required,
+            default=default,
+            tags=tags,
+            **kwargs,
+        )
+
+
+__all__ = ["OptionNode"]

click_extended/core/nodes/parent_node.py

@@ -0,0 +1,220 @@
+"""ParentNode class for parameter nodes (Option, Argument, Env)."""
+
+# pylint: disable=too-many-instance-attributes
+# pylint: disable=too-many-arguments
+# pylint: disable=too-many-positional-arguments
+# pylint: disable=redefined-builtin
+
+import asyncio
+from abc import ABC, abstractmethod
+from functools import wraps
+from typing import TYPE_CHECKING, Any, Callable, ParamSpec, TypeVar, cast
+
+from click_extended.core.nodes.node import Node
+from click_extended.core.other._tree import Tree
+
+if TYPE_CHECKING:
+    from click_extended.core.nodes._root_node import RootNode
+    from click_extended.core.other.context import Context
+
+P = ParamSpec("P")
+T = TypeVar("T")
+
+
+class ParentNode(Node, ABC):
+    """
+    Abstract base class for nodes that manage child nodes and inject values.
+    """
+
+    parent: "RootNode"
+
+    def __init__(
+        self,
+        name: str,
+        param: str | None = None,
+        help: str | None = None,
+        required: bool = False,
+        default: Any = None,
+        tags: str | list[str] | None = None,
+        **kwargs: Any,
+    ):
+        """
+        Initialize a new `ParentNode` instance.
+
+        Args:
+            name (str):
+                The name of the node (parameter name for injection).
+            param (str, optional):
+                The parameter name to inject into the function.
+                If not provided, uses name.
+            help (str, optional):
+                Help text for this parameter. If not provided,
+                may use function's docstring.
+            required (bool):
+                Whether this parameter is required. Defaults to False.
+            default (Any):
+                Default value if not provided. Defaults to `None`.
+            tags (str | list[str], optional):
+                Tag(s) to associate with this parameter for grouping.
+                Can be a single string or list of strings.
+            **kwargs (Any):
+                Additional keyword arguments (ignored in base class,
+                subclasses can use them if they override __init__).
+        """
+        super().__init__(name=name, children={})
+        self.param = param if param is not None else name
+        self.help = help
+        self.required = required
+        self.default = default
+
+        if tags is None:
+            self.tags: list[str] = []
+        elif isinstance(tags, str):
+            self.tags = [tags]
+        else:
+            self.tags = list(tags)
+
+        self.was_provided: bool = False
+        self.raw_value: Any = None
+        self.cached_value: Any = None
+        self._value_computed: bool = False
+        self.decorator_kwargs: dict[str, Any] = {}
+
+    @abstractmethod
+    def load(self, context: "Context", *args: Any, **kwargs: Any) -> Any:
+        """
+        Load and return the value for this node.
+
+        This method must be implemented by all ParentNode subclasses to define
+        how values are obtained. The method can be either synchronous or
+        asynchronous.
+
+        For self-sourcing nodes (e.g., @env), this method retrieves the value
+        from its source (environment variables, config files, etc.).
+
+        For CLI-sourcing nodes (ArgumentNode, OptionNode), subclasses override
+        this signature to include a `value` parameter with the parsed CLI input.
+
+        Args:
+            context (Context):
+                The current context instance containing node data and state.
+            *args (Any):
+                Optional positional arguments.
+            **kwargs (Any):
+                Optional keyword arguments.
+
+        Returns:
+            Any:
+                The loaded value to inject into the function. Can return `None`
+                if that's a valid value for this node.
+        """
+        raise NotImplementedError
+
+    @classmethod
+    def as_decorator(
+        cls,
+        *,
+        name: str,
+        param: str | None = None,
+        help: str | None = None,
+        required: bool = False,
+        default: Any = None,
+        tags: str | list[str] | None = None,
+        **kwargs: Any,
+    ) -> Callable[[Callable[P, T]], Callable[P, T]]:
+        """
+        Return a decorator representation of the parent node.
+
+        All configuration parameters are stored and passed to the load() method.
+        Subclasses can override __init__ to accept additional parameters.
+
+        Args:
+            name (str):
+                The name of the node (parameter name for injection).
+            param (str, optional):
+                The parameter name to inject into the function.
+                If not provided, uses name.
+            help (str, optional):
+                Help text for this parameter.
+            required (bool):
+                Whether this parameter is required. Defaults to False.
+            default (Any):
+                Default value if not provided. Defaults to `None`.
+            tags (str | list[str], optional):
+                Tag(s) to associate with this parameter for grouping.
+            **kwargs (Any):
+                Additional keyword arguments specific to the subclass.
+                These are passed to both __init__ and load().
+
+        Returns:
+            Callable:
+                A decorator function that registers the parent node.
+        """
+        config = {
+            "name": name,
+            "param": param,
+            "help": help,
+            "required": required,
+            "default": default,
+            "tags": tags,
+            **kwargs,
+        }
+
+        def decorator(func: Callable[P, T]) -> Callable[P, T]:
+            """The actual decorator that wraps the function."""
+            instance = cls(**config)  # type: ignore
+            instance.decorator_kwargs = config
+            Tree.queue_parent(instance)
+
+            if asyncio.iscoroutinefunction(func):
+
+                @wraps(func)
+                async def async_wrapper(
+                    *call_args: P.args, **call_kwargs: P.kwargs
+                ) -> T:
+                    """Async wrapper that preserves the original function."""
+                    result = await func(*call_args, **call_kwargs)
+                    return cast(T, result)
+
+                return cast(Callable[P, T], async_wrapper)
+
+            @wraps(func)
+            def wrapper(*call_args: P.args, **call_kwargs: P.kwargs) -> T:
+                """Wrapper that preserves the original function."""
+                return func(*call_args, **call_kwargs)
+
+            return wrapper
+
+        return decorator
+
+    def get_value(self) -> Any:
+        """
+        Get the cached value of the `ParentNode`.
+
+        Returns the cached value that was set after calling load() and
+        processing through any child nodes.
+
+        Returns:
+            Any:
+                The cached processed value.
+        """
+        return self.cached_value
+
+    def get_display_name(self) -> str:
+        """
+        Get a formatted display name for error messages.
+
+        Returns:
+            str:
+                The formatted name for display in error messages.
+                Base implementation returns the name as-is.
+        """
+        return self.name
+
+    def __repr__(self) -> str:
+        """Return a detailed representation of the parent node."""
+        class_name = self.__class__.__name__
+        return f"<{class_name} name='{self.name}'>"
+
+
+__all__ = ["ParentNode"]

click_extended/core/nodes/validation_node.py

@@ -0,0 +1,124 @@
+"""ValidationNode class for global validation logic."""
+
+from abc import ABC
+from functools import wraps
+from typing import TYPE_CHECKING, Any, Callable, ParamSpec, TypeVar
+
+from click_extended.core.nodes.node import Node
+from click_extended.core.other._tree import Tree
+from click_extended.utils.casing import Casing
+
+if TYPE_CHECKING:
+    from click_extended.core.other.context import Context
+    from click_extended.types import Decorator
+
+P = ParamSpec("P")
+T = TypeVar("T")
+
+
+class ValidationNode(Node, ABC):
+    """
+    Base class for validation nodes that run at specific lifecycle points.
+
+    Unlike ChildNodes which validate individual parent values, ValidationNodes
+    operate at the tree level and can access all parents through the context.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        process_args: tuple[Any, ...] | None = None,
+        process_kwargs: dict[str, Any] | None = None,
+        **kwargs: Any,
+    ) -> None:
+        """
+        Initialize a new `ValidationNode` instance.
+
+        Args:
+            name (str):
+                The name of the validation node.
+            process_args (tuple):
+                Positional arguments to pass to lifecycle methods.
+            process_kwargs (dict[str, Any]):
+                Keyword arguments to pass to lifecycle methods.
+            **kwargs (Any):
+                Additional keyword arguments.
+        """
+        children = kwargs.pop("children", None)
+        super().__init__(name=name, children=children, **kwargs)
+        self.process_args = process_args or ()
+        self.process_kwargs = process_kwargs or {}
+
+    def on_init(self, context: "Context", *args: Any, **kwargs: Any) -> None:
+        """
+        Run before any parent nodes are processed.
+
+        This hook is called after tree validation (Phase 3) but before
+        any parent node values are loaded.
+
+        Args:
+            context (Context):
+                The current context with access to all nodes.
+            *args (Any):
+                Additional positional arguments from decorator.
+            **kwargs (Any):
+                Additional keyword arguments from decorator.
+
+        Raises:
+            Any exception to abort command execution.
+        """
+
+    def on_finalize(
+        self, context: "Context", *args: Any, **kwargs: Any
+    ) -> None:
+        """
+        Run after all parent nodes are processed.
+
+        This hook is called after all parent and tag processing is complete,
+        but before the decorated function is called.
+
+        Args:
+            context (Context):
+                The current context with access to all processed values.
+            *args (Any):
+                Additional positional arguments from decorator.
+            **kwargs (Any):
+                Additional keyword arguments from decorator.
+
+        Raises:
+            Any exception to abort command execution.
+        """
+
+    @classmethod
+    def as_decorator(cls, *args: Any, **kwargs: Any) -> "Decorator":
+        """
+        Return a decorator representation of the validation node.
+
+        Args:
+            *args (Any):
+                Positional arguments to pass to lifecycle methods.
+            **kwargs (Any):
+                Keyword arguments to pass to lifecycle methods.
+
+        Returns:
+            Decorator:
+                A decorator function that registers the validation node.
+        """
+
+        def decorator(func: Callable[P, T]) -> Callable[P, T]:
+            """The actual decorator that wraps the function."""
+            name = Casing.to_snake_case(cls.__name__)
+            instance = cls(name=name, process_args=args, process_kwargs=kwargs)
+            Tree.queue_validation(instance)
+
+            @wraps(func)
+            def wrapper(*call_args: P.args, **call_kwargs: P.kwargs) -> T:
+                """Wrapper that preserves the original function."""
+                return func(*call_args, **call_kwargs)
+
+            return wrapper
+
+        return decorator
+
+
+__all__ = ["ValidationNode"]