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

click_extended/core/decorators/option.py

@@ -0,0 +1,347 @@
+"""`ParentNode` that represents a Click option."""
+
+# pylint: disable=too-many-arguments
+# pylint: disable=too-many-positional-arguments
+# pylint: disable=too-many-locals
+# pylint: disable=too-many-branches
+# pylint: disable=redefined-builtin
+
+import asyncio
+from builtins import type as builtins_type
+from functools import wraps
+from typing import Any, Callable, ParamSpec, Type, TypeVar, cast
+
+from click_extended.core.nodes.option_node import OptionNode
+from click_extended.core.other.context import Context
+from click_extended.utils.humanize import humanize_type
+from click_extended.utils.naming import (
+    is_long_flag,
+    is_short_flag,
+    is_valid_name,
+    validate_name,
+)
+
+P = ParamSpec("P")
+T = TypeVar("T")
+
+SUPPORTED_TYPES = (str, int, float, bool)
+
+
+class Option(OptionNode):
+    """`OptionNode` that represents a Click option."""
+
+    def __init__(
+        self,
+        name: str,
+        *flags: str,
+        param: str | None = None,
+        is_flag: bool = False,
+        type: Any = 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 `Option` instance.
+
+        Args:
+            name (str):
+                The option name (parameter name) in snake_case,
+                SCREAMING_SNAKE_CASE, or kebab-case. Examples: \"config_file\",
+                \"CONFIG_FILE\", \"config-file\"
+            *flags (str):
+                Optional flags for the option. Can include any number of short
+                flags (e.g., \"-p\", \"-P\") and long flags (e.g., \"--port\",
+                \"--p\"). If no long flags provided, auto-generates
+                "--kebab-case(name)".
+            param (str, optional):
+                Custom parameter name for the function.
+                If not provided, uses the name directly.
+            is_flag (bool):
+                Whether this is a boolean flag (no value needed).
+                Defaults to `False`.
+            type (Any, optional):
+                The type to convert the value to (int, str, float, etc.).
+            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 Click option parameters.
+        """
+        if name.startswith("--"):
+            if is_long_flag(name):
+                derived_name = name[2:]
+                if not is_valid_name(derived_name):
+                    raise ValueError(
+                        f"Invalid option name '{name}'. When using a long "
+                        "flag as name, it must be snake_case after removing "
+                        f"'--'. Use '{name.replace('-', '_')}' or provide an "
+                        "explicit snake_case name parameter."
+                    )
+                if not flags or not any(f.startswith("--") for f in flags):
+                    flags = (name,) + flags
+            else:
+                raise ValueError(
+                    f"Invalid option name '{name}'. "
+                    f"Must be snake_case (e.g., my_option, config_file)"
+                )
+        else:
+            validate_name(name, "option name")
+            derived_name = name
+
+        short_flags_list: list[str] = []
+        long_flags_list: list[str] = []
+
+        for flag in flags:
+            if not flag.startswith("-"):
+                raise ValueError(
+                    f"Invalid flag '{flag}'. Flags must start with '-' or '--'."
+                )
+
+            if flag.startswith("--"):
+                if not is_long_flag(flag):
+                    raise ValueError(
+                        f"Invalid long flag '{flag}'. "
+                        "Must be format: --word "
+                        "(lowercase, hyphens allowed, e.g., --port, "
+                        "--config-file)"
+                    )
+                long_flags_list.append(flag)
+            else:
+                if not is_short_flag(flag):
+                    raise ValueError(
+                        f"Invalid short flag '{flag}'. Must be format: -X "
+                        f"(single letter, e.g., -p, -v, -h)"
+                    )
+                short_flags_list.append(flag)
+
+        param_name = param if param is not None else derived_name
+
+        validate_name(param_name, "parameter name")
+
+        if is_flag and type is not None and type != bool:
+            raise ValueError(
+                f"Cannot specify both is_flag=True and "
+                f"type={type.__name__ if hasattr(type, '__name__') else type}. "
+                f"Flags are always boolean."
+            )
+
+        if is_flag and default is None:
+            default = False
+
+        if type is None:
+            if is_flag:
+                type = bool
+            elif default is not None and not (multiple and default == ()):
+                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"Option '{derived_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, ...)."
+            )
+
+        if multiple and default is None:
+            default = ()
+
+        super().__init__(
+            name=derived_name,
+            param=param_name,
+            short_flags=short_flags_list,
+            long_flags=long_flags_list,
+            is_flag=is_flag,
+            type=type,
+            nargs=nargs,
+            multiple=multiple,
+            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 first long flag if available, otherwise the first flag.
+        """
+        if self.long_flags:
+            return self.long_flags[0]
+        if self.short_flags:
+            return self.short_flags[0]
+        return self.name
+
+    def load(
+        self,
+        value: str | int | float | bool | None,
+        context: Context,
+        *args: Any,
+        **kwargs: Any,
+    ) -> Any:
+        """
+        Load and return the CLI option value.
+
+        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 option value to inject into the function.
+        """
+        return value
+
+
+def option(
+    name: str,
+    *flags: str,
+    param: str | None = None,
+    is_flag: bool = False,
+    type: Type[str | int | float | bool] | 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]]:
+    """
+    A `ParentNode` decorator to create a Click option with value injection.
+
+    Args:
+        name (str):
+            The option name (parameter name) in snake_case.
+            Examples: "verbose", "config_file"
+        *flags (str):
+            Optional flags for the option. Can include any number of short flags
+            (e.g., "-v", "-V") and long flags (e.g., "--verbose", "--verb").
+            If no long flags provided, auto-generates "--kebab-case(name)".
+            Examples:
+                @option("verbose", "-v")
+                @option("config", "-c", "--cfg", "--config")
+                @option("verbose", "-v", "-V", "--verbose", "--verb")
+        param (str, optional):
+            Custom parameter name for the function.
+            If not provided, uses the name directly.
+        is_flag (bool):
+            Whether this is a boolean flag (no value needed).
+            Defaults to `False`.
+        type (Type[str | int | float | bool] | None, optional):
+            The type to convert the value to.
+        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 Click option parameters.
+
+    Returns:
+        Callable:
+            A decorator function that registers the option parent node.
+
+    Examples:
+
+        ```python
+        # Simple: name only (auto-generates --verbose)
+        @option("verbose", is_flag=True)
+        def my_func(verbose):
+            print(f"Verbose: {verbose}")
+
+        # Name with short flag
+        @option("port", "-p", type=int, default=8080)
+        def my_func(port):
+            print(f"Port: {port}")
+
+        # Multiple short and long flags
+        @option("verbose", "-v", "-V", "--verb", is_flag=True)
+        def my_func(verbose):  # Accepts: -v, -V, --verbose, --verb
+            print("Verbose mode")
+
+        # Custom parameter name
+        @option("configuration_file", "-c", param="cfg")
+        def my_func(cfg):  # param: cfg, CLI: -c, --configuration-file
+            print(f"Config: {cfg}")
+        ```
+    """
+
+    def decorator(func: Callable[P, T]) -> Callable[P, T]:
+        """The actual decorator that wraps the function."""
+        from click_extended.core.other._tree import Tree
+
+        instance = Option(
+            name,
+            *flags,
+            param=param,
+            is_flag=is_flag,
+            type=type,
+            nargs=nargs,
+            multiple=multiple,
+            help=help,
+            required=required,
+            default=default,
+            tags=tags,
+            **kwargs,
+        )
+        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

click_extended/core/decorators/prompt.py

@@ -0,0 +1,69 @@
+"""Parent decorator that prompts the user for a value."""
+
+from getpass import getpass
+from typing import Any
+
+from click_extended.core.nodes.parent_node import ParentNode
+from click_extended.core.other.context import Context
+from click_extended.types import Decorator
+
+
+class Prompt(ParentNode):
+    """Parent decorator that prompts the user for a value."""
+
+    def get_input(self, text: str, hide: bool) -> str:
+        """
+        Get input from the user.
+
+        Args:
+            text (str):
+                The prompt.
+            hide (bool):
+                Whether to hide the user input.
+
+        Returns:
+            str:
+                The value provided from the user.
+        """
+        if hide:
+            return getpass(text)
+        return input(text)
+
+    def load(
+        self,
+        context: Context,
+        *args: Any,
+        **kwargs: Any,
+    ) -> str:
+        while True:
+            answer = self.get_input(kwargs["text"], kwargs["hide"])
+            if answer or kwargs["allow_empty"]:
+                return answer
+
+
+def prompt(
+    name: str, text: str = "", hide: bool = False, allow_empty: bool = False
+) -> Decorator:
+    """
+    A `ParentNode` decorator to prompt the user for input.
+
+    Args:
+        name (str):
+            The name of the parent node.
+        text (str):
+            The text to show.
+        hide (bool):
+            Whether to hide the input, defaults to `False`.
+        allow_empty (bool):
+            Whether to allow the input to be empty, defaults to `False`.
+
+    Returns:
+        Decorator:
+            The decorator function.
+    """
+    return Prompt.as_decorator(
+        name=name,
+        text=text,
+        hide=hide,
+        allow_empty=allow_empty,
+    )

click_extended/core/decorators/selection.py

@@ -0,0 +1,155 @@
+"""Choose one or more options from a list of selections."""
+
+# pylint: disable=too-many-arguments
+# pylint: disable=too-many-positional-arguments
+# pylint: disable=redefined-builtin
+
+from typing import Any
+
+from click_extended.core.nodes.parent_node import ParentNode
+from click_extended.core.other.context import Context
+from click_extended.types import Decorator
+from click_extended.utils.selection import selection as fn
+
+
+class Selection(ParentNode):
+    """Choose one or more options from a list of selections."""
+
+    def load(
+        self, context: Context, *args: Any, **kwargs: Any
+    ) -> str | list[str]:
+        """
+        Load the selection value by prompting the user.
+
+        Args:
+            context (Context):
+                The current context.
+            *args (Any):
+                Additional positional arguments.
+            **kwargs (Any):
+                Additional keyword arguments
+
+        Returns:
+            str|list[str]:
+                Selected value(s). `str` for single mode, `list[str]`
+                for multiple.
+
+        Raises:
+            ValueError:
+                If selections is empty or invalid.
+        """
+        return fn(
+            selections=kwargs.get("selections", []),
+            prompt=kwargs.get("prompt", "Select an option"),
+            multiple=kwargs.get("multiple", False),
+            default=kwargs.get("default"),
+            min_selections=kwargs.get("min_selections", 0),
+            max_selections=kwargs.get("max_selections"),
+            cursor_style=kwargs.get("cursor_style", ">"),
+            checkbox_style=kwargs.get("checkbox_style", ("◯", "◉")),
+            show_count=kwargs.get("show_count", False),
+        )
+
+
+def selection(
+    name: str,
+    selections: list[str | tuple[str, str]],
+    multiple: bool = False,
+    default: str | list[str] | None = None,
+    prompt: str = "Select an option:",
+    min_selections: int = 0,
+    max_selections: int | None = None,
+    cursor_style: str = ">",
+    checkbox_style: tuple[str, str] = ("◯", "◉"),
+    show_count: bool = False,
+    param: str | None = None,
+    help: str | None = None,
+    required: bool = False,
+    tags: str | list[str] | None = None,
+) -> Decorator:
+    """
+    A `ParentNode` decorator for an interactive selection prompt
+    with arrow key navigation.
+
+    Creates an interactive terminal prompt that allows users to select one or
+    more options using arrow keys (or j/k vim-style keys). The list wraps around
+    (carousel behavior) when scrolling past the first or last item.
+
+    Args:
+        name (str):
+            The name of the parameter for injection.
+        selections (list[str | tuple[str, str]]):
+            List of options. Each item can be:
+            - str: Used as both display text and value
+            - tuple[str, str]: (display_text, value)
+        multiple (bool):
+            If `True`, allows multiple selections with checkboxes.
+            If `False`, allows single selection only. Defaults to `False`.
+        default (str | list[str] | None):
+            Default selection(s). Should be a string for single mode,
+            or list of strings for multiple mode. Defaults to `None`.
+        prompt (str):
+            Text to display above the selection list.
+            Defaults to "Select an option:".
+        min_selections (int):
+            Minimum number of selections required (multiple mode only).
+            Defaults to `0`. User cannot confirm until minimum is met.
+        max_selections (int | None):
+            Maximum number of selections allowed (multiple mode only).
+            Defaults to `None` (unlimited). Prevents selecting more than max.
+        cursor_style (str):
+            The cursor indicator string. Defaults to ">".
+            Examples: ">", "→", "▶", "•"
+        checkbox_style (tuple[str, str]):
+            Tuple of (unselected, selected) checkbox indicators.
+            Defaults to ("◯", "◉").
+            Examples: ("☐", "☑"), ("○", "●"), ("[ ]", "[x]")
+        show_count (bool):
+            Whether to show selection count in the prompt.
+            Defaults to `False`. Shows "(X/Y selected)" when enabled.
+        param (str | None):
+            The parameter name to inject into the function.
+            If not provided, uses name.
+        help (str | None):
+            Help text for this parameter.
+        required (bool):
+            Whether this parameter is required. Defaults to `False`.
+        tags (str | list[str] | None):
+            Tag(s) to associate with this parameter for grouping.
+
+    Returns:
+        Decorator:
+            The decorator function.
+
+    Examples:
+        >>> @command()
+        >>> @selection("framework", ["React", "Vue", "Angular"])
+        >>> def setup(framework: str):
+        ...     print(f"Setting up {framework}...")
+
+        >>> @command()
+        >>> @selection(
+        ...     "features",
+        ...     [("TypeScript", "ts"), ("ESLint", "eslint")],
+        ...     multiple=True,
+        ...     default=["eslint"]
+        ... )
+        >>> def configure(features: list[str]):
+        ...     print(f"Enabled: {features}")
+    """
+    return Selection.as_decorator(
+        name=name,
+        param=param,
+        help=help,
+        required=required,
+        default=default,
+        tags=tags,
+        selections=selections,
+        multiple=multiple,
+        prompt=prompt,
+        min_selections=min_selections,
+        max_selections=max_selections,
+        cursor_style=cursor_style,
+        checkbox_style=checkbox_style,
+        show_count=show_count,
+    )

click_extended/core/decorators/tag.py

@@ -0,0 +1,109 @@
+"""Tag implementation for the `click_extended` library."""
+
+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
+
+if TYPE_CHECKING:
+    from click_extended.core.nodes.parent_node import ParentNode
+
+P = ParamSpec("P")
+T = TypeVar("T")
+
+
+class Tag(Node):
+    """Tag class for grouping multiple ParentNodes together."""
+
+    def __init__(self, name: str):
+        """
+        Initialize a new `Tag` instance.
+
+        Args:
+            name (str):
+                The name of the tag for grouping ParentNodes.
+        """
+        super().__init__(name=name, children={})
+        self.parent_nodes: list["ParentNode"] = []
+
+    def get_provided_values(self) -> list[str]:
+        """
+        Get the names of all ParentNodes in this tag
+        that were provided by the user.
+
+        Returns:
+            list[str]:
+                List of parameter names that were provided.
+        """
+        return [node.name for node in self.parent_nodes if node.was_provided]
+
+    def get_value(self) -> dict[str, Any]:
+        """
+        Get a dictionary of values from all parent nodes.
+
+        Returns a dictionary mapping parameter names to their values from all
+        parent nodes that reference this tag. Each key is the parent
+        node's name, and the value is `None` if not provided.
+
+        Returns:
+            dict[str, Any]:
+                Dictionary mapping parameter names to values.
+        """
+        return {
+            parent_node.name: parent_node.get_value()
+            for parent_node in self.parent_nodes
+        }
+
+    @classmethod
+    def as_decorator(
+        cls, name: str
+    ) -> Callable[[Callable[P, T]], Callable[P, T]]:
+        """
+        Return a decorator representation of the tag.
+
+        Args:
+            name (str):
+                The name of the tag.
+
+        Returns:
+            Callable:
+                A decorator function that registers the tag.
+        """
+
+        def decorator(func: Callable[P, T]) -> Callable[P, T]:
+            """The actual decorator that registers the tag."""
+            instance = cls(name=name)
+            Tree.queue_tag(instance)
+            return func
+
+        return decorator
+
+
+def tag(name: str) -> Callable[[Callable[P, T]], Callable[P, T]]:
+    """
+    A special `Tag` decorator to create a tag for grouping parent nodes.
+
+    Tags allow you to apply child nodes to multiple parent nodes at once
+    and perform cross-node validation.
+
+    Args:
+        name (str):
+            The name of the tag.
+
+    Returns:
+        Callable:
+            A decorator function that registers the tag.
+
+    Examples:
+
+        ```python
+        @command()
+        @option("--api-key", tags="api-config")
+        @option("--api-url", tags="api-config")
+        @tag("api-config")
+        @at_least(1)
+        def my_function(api_key: str, api_url: str):
+            print(f"API Key: {api_key}, URL: {api_url}")
+        ```
+    """
+    return Tag.as_decorator(name=name)

click_extended/core/nodes/__init__.py

@@ -0,0 +1,21 @@
+"""Initialization file for the `click_extended.core.nodes` module."""
+
+from click_extended.core.nodes._root_node import RootNode
+from click_extended.core.nodes.argument_node import ArgumentNode
+from click_extended.core.nodes.child_node import ChildNode
+from click_extended.core.nodes.child_validation_node import ChildValidationNode
+from click_extended.core.nodes.node import Node
+from click_extended.core.nodes.option_node import OptionNode
+from click_extended.core.nodes.parent_node import ParentNode
+from click_extended.core.nodes.validation_node import ValidationNode
+
+__all__ = [
+    "RootNode",
+    "ArgumentNode",
+    "ChildNode",
+    "ChildValidationNode",
+    "Node",
+    "OptionNode",
+    "ParentNode",
+    "ValidationNode",
+]