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

click_extended/__init__.py

@@ -2,6 +2,7 @@
 
 from click_extended.core.decorators.argument import argument
 from click_extended.core.decorators.command import command
+from click_extended.core.decorators.context import context
 from click_extended.core.decorators.env import env
 from click_extended.core.decorators.group import group
 from click_extended.core.decorators.option import option
@@ -12,6 +13,7 @@ from click_extended.core.decorators.tag import tag
 __all__ = [
     "argument",
     "command",
+    "context",
     "env",
     "group",
     "option",

click_extended/core/__init__.py

@@ -0,0 +1,10 @@
+"""Initialization file for the 'click_extended.core' module."""
+
+from click_extended.core.decorators import *
+from click_extended.core.decorators import __all__ as decorators_all
+from click_extended.core.nodes import *
+from click_extended.core.nodes import __all__ as nodes_all
+from click_extended.core.other import *
+from click_extended.core.other import __all__ as other_all
+
+__all__ = [*decorators_all, *nodes_all, *other_all]  # type: ignore

click_extended/core/decorators/__init__.py

@@ -0,0 +1,21 @@
+"""Initialization file for the `click_extended.core.decorators` module."""
+
+from click_extended.core.decorators.argument import Argument
+from click_extended.core.decorators.command import Command
+from click_extended.core.decorators.env import Env
+from click_extended.core.decorators.group import Group
+from click_extended.core.decorators.option import Option
+from click_extended.core.decorators.prompt import Prompt
+from click_extended.core.decorators.selection import Selection
+from click_extended.core.decorators.tag import Tag
+
+__all__ = [
+    "Argument",
+    "Command",
+    "Env",
+    "Group",
+    "Option",
+    "Prompt",
+    "Selection",
+    "Tag",
+]

click_extended/core/decorators/argument.py

@@ -0,0 +1,227 @@
+"""Class to support arguments in the command line interface."""
+
+# pylint: disable=too-many-arguments
+# pylint: disable=too-many-positional-arguments
+# pylint: disable=redefined-builtin
+
+from builtins import type as builtins_type
+from typing import Any, Type, cast
+
+from click_extended.core.nodes.argument_node import ArgumentNode
+from click_extended.core.other.context import Context
+from click_extended.types import Decorator
+from click_extended.utils.casing import Casing
+from click_extended.utils.humanize import humanize_type
+from click_extended.utils.naming import validate_name
+
+_MISSING = object()
+SUPPORTED_TYPES = (str, int, float, bool)
+
+
+class Argument(ArgumentNode):
+    """`ArgumentNode` that represents a Click argument."""
+
+    def __init__(
+        self,
+        name: str,
+        param: str | None = None,
+        nargs: int = 1,
+        type: Type[Any] | Any = None,
+        help: str | None = None,
+        required: bool = True,
+        default: Any = _MISSING,
+        tags: str | list[str] | None = None,
+        **kwargs: Any,
+    ):
+        """
+        Initialize a new `Argument` instance.
+
+        Args:
+            name (str):
+                The argument name in snake_case.
+                Examples: "filename", "input_file"
+            param (str, optional):
+                Custom parameter name for the function.
+                If not provided, uses the name directly.
+            nargs (int):
+                Number of arguments to accept. Use `-1` for unlimited.
+                Defaults to `1`.
+            type (Any, optional):
+                The type to convert the value to (`int`, `str`, `float`, etc.).
+            help (str, optional):
+                Help text for this argument.
+            required (bool):
+                Whether this argument is required. Defaults to `True` unless
+                `default` is provided, which makes it optional automatically.
+            default (Any):
+                Default value if not provided. When set, automatically makes
+                the argument optional (`required=False`). Defaults to `None`.
+            tags (str | list[str], optional):
+                Tag(s) to associate with this argument for grouping.
+            **kwargs (Any):
+                Additional keyword arguments.
+
+        Raises:
+            ValueError: If both `default` is provided and `required=True` is
+                explicitly set (detected via kwargs inspection in decorator).
+        """
+        validate_name(name, "argument name")
+
+        param_name = param if param is not None else name
+
+        validate_name(param_name, "parameter name")
+
+        if default is not _MISSING and required is True:
+            required = False
+
+        if default is _MISSING:
+            default = None
+
+        if type is None:
+            if default is not None:
+                type = cast(Type[Any], builtins_type(default))  # type: ignore
+            else:
+                type = str
+
+        if type not in SUPPORTED_TYPES:
+            types = humanize_type(
+                type.__name__ if hasattr(type, "__name__") else type
+            )
+            raise ValueError(
+                f"Argument '{name}' has unsupported type '{types}'. "
+                "Only basic primitives are supported: str, int, float, bool. "
+                "For complex types, use child decorators (e.g., @to_path, "
+                "@to_datetime, ..)."
+            )
+
+        super().__init__(
+            name=name,
+            param=param if param is not None else name,
+            nargs=nargs,
+            type=type,
+            help=help,
+            required=required,
+            default=default,
+            tags=tags,
+        )
+        self.extra_kwargs = kwargs
+
+    def get_display_name(self) -> str:
+        """
+        Get a formatted display name for error messages.
+
+        Returns:
+            str:
+                The argument name in SCREAMING_SNAKE_CASE.
+        """
+        return Casing.to_screaming_snake_case(self.name)
+
+    def load(
+        self,
+        value: str | int | float | bool | None,
+        context: Context,
+        *args: Any,
+        **kwargs: Any,
+    ) -> Any:
+        """
+        Load and return the CLI argument value.
+
+        Args:
+            value (str | int | float | bool | None):
+                The parsed CLI argument value from Click.
+            context (Context):
+                The current context instance.
+            *args (Any):
+                Optional positional arguments.
+            **kwargs (Any):
+                Optional keyword arguments.
+
+        Returns:
+            Any:
+                The argument value to inject into the function.
+        """
+        return value
+
+
+def argument(
+    name: str,
+    param: str | None = None,
+    nargs: int = 1,
+    type: Type[str | int | float | bool] | None = None,
+    help: str | None = None,
+    required: bool = True,
+    default: Any = _MISSING,
+    tags: str | list[str] | None = None,
+    **kwargs: Any,
+) -> Decorator:
+    """
+    A `ParentNode` decorator to create a Click argument with value injection.
+
+    Args:
+        name (str):
+            The argument name in snake_case.
+            Examples: "filename", "input_file"
+        param (str, optional):
+            Custom parameter name for the function.
+            If not provided, uses the name directly.
+        nargs (int):
+            Number of arguments to accept. Use `-1` for unlimited.
+            Defaults to `1`.
+        type (Type[str | int | float | bool] | None, optional):
+            The type to convert the value to.
+        help (str, optional):
+            Help text for this argument.
+        required (bool):
+            Whether this argument is required. Defaults to `True` unless
+            `default` is provided, which automatically makes it optional.
+        default (Any):
+            Default value if not provided. When set, automatically makes
+            the argument optional (`required=False`). Defaults to `None`.
+        tags (str | list[str], optional):
+            Tag(s) to associate with this argument for grouping.
+        **kwargs (Any):
+            Additional Click argument parameters.
+
+    Returns:
+        Decorator:
+            A decorator function that registers the argument parent node.
+
+    Examples:
+
+        ```python
+        @argument("filename")
+        def my_func(filename):
+            print(f"File: {filename}")
+        ```
+
+        ```python
+        @argument("files", nargs=-1, help="Files to process")
+        def my_func(files):
+            for file in files:
+                print(f"Processing: {file}")
+        ```
+
+        ```python
+        @argument("port", type=int, default=8080)
+        def my_func(port):
+            print(f"Port: {port}")
+        ```
+
+        ```python
+        # Custom parameter name
+        @argument("input_file", param="infile")
+        def my_func(infile):  # param: infile, CLI: INPUT_FILE
+            print(f"Input: {infile}")
+        ```
+    """
+    return Argument.as_decorator(
+        name=name,
+        param=param,
+        nargs=nargs,
+        type=type,
+        help=help,
+        required=required,
+        default=default,
+        tags=tags,
+        **kwargs,
+    )

click_extended/core/decorators/command.py

@@ -0,0 +1,93 @@
+"""Command implementation for the `click_extended` library."""
+
+# pylint: disable=redefined-builtin
+
+from typing import Any, Callable
+
+import click
+
+from click_extended.core.nodes._root_node import RootNode
+from click_extended.core.other._click_command import ClickCommand
+
+
+class Command(RootNode):
+    """Command implementation for the `click_extended` library."""
+
+    @classmethod
+    def _get_click_decorator(cls) -> Callable[..., Any]:
+        """Return the click.command decorator (no longer used)."""
+        return click.command
+
+    @classmethod
+    def _get_click_cls(cls) -> type[click.Command]:  # type: ignore[override]
+        """Return the ClickCommand class."""
+        return ClickCommand
+
+    @classmethod
+    def wrap(
+        cls,
+        wrapped_func: Callable[..., Any],
+        name: str,
+        instance: RootNode,
+        **kwargs: Any,
+    ) -> ClickCommand:
+        """Override to return proper ClickCommand type."""
+        return super().wrap(
+            wrapped_func,
+            name,
+            instance,
+            **kwargs,
+        )  # type: ignore[return-value]
+
+    @classmethod
+    def as_decorator(
+        cls, name: str | None = None, /, **kwargs: Any
+    ) -> Callable[[Callable[..., Any]], ClickCommand]:
+        """Override to return proper ClickCommand type."""
+        return super().as_decorator(
+            name,
+            **kwargs,
+        )  # type: ignore[return-value]
+
+
+def command(
+    name: str | None = None,
+    *,
+    aliases: str | list[str] | None = None,
+    help: str | None = None,
+    **kwargs: Any,
+) -> Callable[[Callable[..., Any]], ClickCommand]:
+    """
+    A `ParentNode` decorator to create a click command with value injection
+    from parent nodes.
+
+    Args:
+        name (str, optional):
+            The name of the command. If `None`, uses the
+            decorated function's name.
+        aliases (str | list[str], optional):
+            Alternative name(s) for the command. Can be a single
+            string or a list of strings.
+        help (str, optional):
+            The help message for the command. If not provided,
+            uses the first line of the function's docstring.
+        **kwargs (Any):
+            Additional arguments to pass to `click.Command`.
+
+    Returns:
+        Callable:
+            A decorator function that returns a Click command.
+    """
+    if aliases is not None:
+        kwargs["aliases"] = aliases
+    if help is not None:
+        kwargs["help"] = help
+
+    def decorator(func: Callable[..., Any]) -> ClickCommand:
+        if help is None and func.__doc__:
+            first_line = func.__doc__.strip().split("\n")[0].strip()
+            if first_line:
+                kwargs["help"] = first_line
+        return Command.as_decorator(name, **kwargs)(func)
+
+    return decorator

click_extended/core/decorators/context.py

@@ -0,0 +1,56 @@
+"""`ParentNode` to inject the context into the function."""
+
+# pylint: disable=redefined-builtin
+# pylint: disable=redefined-outer-name
+
+from typing import Any
+
+from click_extended.core.nodes.parent_node import ParentNode
+from click_extended.core.other.context import Context as Ctx
+from click_extended.types import Decorator
+
+
+class Context(ParentNode):
+    """`ParentNode` to inject the context into the function."""
+
+    def load(self, context: Ctx, *args: Any, **kwargs: Any) -> Ctx:
+        return context
+
+
+def context(
+    name: str = "ctx",
+    param: str | None = None,
+    help: str | None = None,
+    tags: str | list[str] | None = None,
+    **kwargs: Any,
+) -> Decorator:
+    """
+    A `ParentNode` to inject the context into the function.
+
+    Type: `ParentNode`
+
+    Args:
+        name (str, optional):
+            Internal node name (must be snake_case). Defaults
+            to "ctx".
+        param (str, optional):
+            The parameter name to inject into the function.
+            If not provided, uses `name` (or derived name).
+        help (str, optional):
+            Help text for this parameter.
+        tags (str | list[str], optional):
+            Tag(s) to associate with this parameter for grouping.
+        **kwargs (Any):
+            Additional keyword arguments.
+
+    Returns:
+        Callable:
+            A decorator function that registers the context parent node.
+    """
+    return Context.as_decorator(
+        name=name,
+        param=param,
+        help=help,
+        tags=tags,
+        **kwargs,
+    )

click_extended/core/decorators/env.py

@@ -0,0 +1,155 @@
+"""`ParentNode` that loads a value from an environment variable."""
+
+# pylint: disable=too-many-arguments
+# pylint: disable=too-many-positional-arguments
+# pylint: disable=redefined-builtin
+
+import os
+from typing import Any, Callable, ParamSpec, TypeVar, cast
+
+from dotenv import load_dotenv
+
+from click_extended.core.nodes.parent_node import ParentNode
+from click_extended.core.other.context import Context
+from click_extended.utils.casing import Casing
+
+load_dotenv()
+
+P = ParamSpec("P")
+T = TypeVar("T")
+
+
+class Env(ParentNode):
+    """`ParentNode` that loads a value from an environment variable."""
+
+    def load(self, context: Context, *args: Any, **kwargs: Any) -> Any:
+        """
+        Load and return the environment variable value.
+
+        Args:
+            context (Context):
+                The current context instance.
+            *args (Any):
+                Optional positional arguments.
+            **kwargs (Any):
+                Keyword arguments from the decorator, including:
+                - env_name (str): The environment variable name to read.
+
+        Returns:
+            Any:
+                The value of the environment variable, or the default value
+                if not required and not set.
+
+        Raises:
+            ValueError:
+                If the environment variable is required but not set.
+        """
+        env_name = kwargs.get("env_name")
+        if env_name is None:
+            raise ValueError("env_name must be provided")
+
+        value = os.getenv(env_name)
+
+        if value is None:
+            if self.required:
+                raise ValueError(
+                    f"Required environment variable '{env_name}' " "is not set."
+                )
+            value = self.default
+
+        return value
+
+    def get_display_name(self) -> str:
+        """
+        Get a formatted display name for error messages.
+
+        Returns:
+            str:
+                The environment variable name in SCREAMING_SNAKE_CASE.
+        """
+        return Casing.to_screaming_snake_case(self.name)
+
+    def check_required(self) -> str | None:
+        """
+        Check if required environment variable is set.
+
+        Returns:
+            str | None:
+                The name of the missing environment variable if required
+                and not set, otherwise None.
+        """
+        env_name = self.decorator_kwargs.get("env_name")
+        if env_name and self.required and os.getenv(env_name) is None:
+            return cast(str, env_name)
+        return None
+
+
+def env(
+    env_name: str,
+    name: str | None = None,
+    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]]:
+    """
+    A `ParentNode` decorator to inject an environment variable value
+    into a command.
+
+    Type: `ParentNode`
+
+    Args:
+        env_name (str):
+            The name of the environment variable to read (e.g., "API_KEY").
+            Can be in any format, typically SCREAMING_SNAKE_CASE.
+        name (str, optional):
+            Internal node name (must be snake_case). If not provided,
+            uses env_name converted to snake_case.
+        param (str, optional):
+            The parameter name to inject into the function.
+            If not provided, uses name (or derived name).
+        help (str, optional):
+            Help text for this parameter.
+        required (bool):
+            Whether this parameter is required. Defaults to `False`.
+            If `True`, the environment variable must be set, even if
+            a default value is provided. The default is ignored when
+            `required=True`.
+        default (Any):
+            Default value if environment variable is not set and
+            `required=False`. Defaults to `None`.
+        tags (str | list[str], optional):
+            Tag(s) to associate with this parameter for grouping.
+        **kwargs (Any):
+            Additional keyword arguments.
+
+    Returns:
+        Callable:
+            A decorator function that registers the env parent node.
+
+    Examples:
+        >>> @env("API_KEY")
+        ... def my_func(api_key):
+        ...     print(api_key)
+
+        >>> @env("DATABASE_URL", param="db", required=True)
+        ... def my_func(db):
+        ...     print(db)
+
+        >>> @env("MY_ENV", param="api_key")
+        ... def my_func(api_key):
+        ...     print(api_key)
+    """
+    node_name = name if name is not None else Casing.to_snake_case(env_name)
+    return Env.as_decorator(
+        name=node_name,
+        env_name=env_name,
+        param=param,
+        help=help,
+        required=required,
+        default=default,
+        tags=tags,
+        **kwargs,
+    )

click_extended/core/decorators/group.py

@@ -0,0 +1,96 @@
+"""Group implementation for the `click_extended` library."""
+
+# pylint: disable=protected-access
+# pylint: disable=redefined-builtin
+# pylint: disable=too-many-locals
+# pylint: disable=too-many-branches
+
+from typing import Any, Callable
+
+import click
+
+from click_extended.core.nodes._root_node import RootNode
+from click_extended.core.other._click_group import ClickGroup
+
+
+class Group(RootNode):
+    """Group implementation for the `click_extended` library."""
+
+    @classmethod
+    def _get_click_decorator(cls) -> Callable[..., Any]:
+        """Return the click.group decorator (no longer used)."""
+        return click.group
+
+    @classmethod
+    def _get_click_cls(cls) -> type[click.Command]:  # type: ignore[override]
+        """Return the ClickGroup class."""
+        return ClickGroup
+
+    @classmethod
+    def wrap(
+        cls,
+        wrapped_func: Callable[..., Any],
+        name: str,
+        instance: RootNode,
+        **kwargs: Any,
+    ) -> ClickGroup:
+        """Override to return proper ClickGroup type."""
+        return super().wrap(
+            wrapped_func,
+            name,
+            instance,
+            **kwargs,
+        )  # type: ignore[return-value]
+
+    @classmethod
+    def as_decorator(
+        cls, name: str | None = None, /, **kwargs: Any
+    ) -> Callable[[Callable[..., Any]], ClickGroup]:
+        """Override to return proper ClickGroup type."""
+        return super().as_decorator(
+            name,
+            **kwargs,
+        )  # type: ignore[return-value]
+
+
+def group(
+    name: str | None = None,
+    *,
+    aliases: str | list[str] | None = None,
+    help: str | None = None,
+    **kwargs: Any,
+) -> Callable[[Callable[..., Any]], ClickGroup]:
+    """
+    A `RootNode` decorator to create a click group with value injection
+    from parent nodes.
+
+    Args:
+        name (str, optional):
+            The name of the group. If `None`, uses the
+            decorated function's name.
+        aliases (str | list[str], optional):
+            Alternative name(s) for the group. Can be a single
+            string or a list of strings.
+        help (str, optional):
+            The help message for the group. If not provided,
+            uses the first line of the function's docstring.
+        **kwargs (Any):
+            Additional arguments to pass to `click.Group`.
+
+    Returns:
+        Callable:
+            A decorator function that returns a ClickGroup.
+    """
+    if aliases is not None:
+        kwargs["aliases"] = aliases
+    if help is not None:
+        kwargs["help"] = help
+
+    def decorator(func: Callable[..., Any]) -> ClickGroup:
+        if help is None and func.__doc__:
+            first_line = func.__doc__.strip().split("\n")[0].strip()
+            if first_line:
+                kwargs["help"] = first_line
+        return Group.as_decorator(name, **kwargs)(func)
+
+    return decorator