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

click_extended/decorators/misc/choice.py

@@ -0,0 +1,139 @@
+"""Child decorator to validate a value is one of the allowed choices."""
+
+from typing import Any
+
+from click_extended.core.nodes.child_node import ChildNode
+from click_extended.core.other.context import Context
+from click_extended.types import Decorator
+from click_extended.utils.humanize import humanize_iterable
+
+
+class Choice(ChildNode):
+    """Child decorator to validate a value is one of the allowed choices."""
+
+    def handle_str(
+        self, value: str, context: Context, *args: Any, **kwargs: Any
+    ) -> str:
+        values: tuple[str | int | float, ...] = kwargs["values"]
+        case_sensitive: bool = kwargs.get("case_sensitive", True)
+
+        if case_sensitive:
+            if value not in values:
+                choices_str = humanize_iterable(
+                    [str(v) for v in values],
+                    sep="or",
+                    wrap="'",
+                    prefix_plural="one of",
+                    prefix_singular="",
+                )
+                raise ValueError(f"Value must be {choices_str}, got '{value}'.")
+        else:
+            value_lower = value.lower()
+            values_lower = [
+                v.lower() if isinstance(v, str) else v for v in values
+            ]
+            if value_lower not in values_lower:
+                choices_str = humanize_iterable(
+                    [str(v) for v in values],
+                    sep="or",
+                    wrap="'",
+                    prefix_plural="one of",
+                    prefix_singular="",
+                )
+                raise ValueError(f"Value must be {choices_str}, got '{value}'.")
+
+        return value
+
+    def handle_int(
+        self, value: int, context: Context, *args: Any, **kwargs: Any
+    ) -> int:
+        values: tuple[str | int | float, ...] = kwargs["values"]
+
+        if value not in values:
+            choices_str = humanize_iterable(
+                [str(v) for v in values],
+                sep="or",
+                wrap="'",
+                prefix_plural="one of",
+                prefix_singular="",
+            )
+            raise ValueError(f"Value must be {choices_str}, got '{value}'.")
+
+        return value
+
+    def handle_float(
+        self, value: float, context: Context, *args: Any, **kwargs: Any
+    ) -> float:
+        values: tuple[str | int | float, ...] = kwargs["values"]
+
+        if value not in values:
+            choices_str = humanize_iterable(
+                [str(v) for v in values],
+                sep="or",
+                wrap="'",
+                prefix_plural="one of",
+                prefix_singular="",
+            )
+            raise ValueError(f"Value must be {choices_str}, got '{value}'.")
+
+        return value
+
+
+def choice(
+    *values: str | int | float, case_sensitive: bool = True
+) -> Decorator:
+    """
+    Validate that a value is one of the allowed choices.
+
+    Type: `ChildNode`
+
+    Supports: `str`, `int`, `float`
+
+    Args:
+        *values (str | int | float):
+            The allowed values to choose from. Must be strings, integers,
+            or floats.
+        case_sensitive (bool, optional):
+            Whether the comparison should be case-sensitive for strings.
+            Defaults to `True`.
+
+    Returns:
+        Decorator:
+            The decorator function.
+
+    Raises:
+        ValueError:
+            If no values are provided.
+        TypeError:
+            If any value is not a string, integer, or float.
+        ValueError:
+            If the value is not one of the allowed choices.
+
+    Examples:
+        ```python
+        @command()
+        @option("color")
+        @choice("red", "green", "blue")
+        def cmd(color: str) -> None:
+            click.echo(f"Color: {color}")
+        ```
+
+        ```python
+        @command()
+        @option("level")
+        @choice("DEBUG", "INFO", "WARNING", "ERROR", case_sensitive=False)
+        def cmd(level: str) -> None:
+            click.echo(f"Log level: {level}")
+        ```
+    """
+    if not values:
+        raise ValueError("At least one choice must be provided.")
+
+    for value in values:
+        if not isinstance(value, (str, int, float)):
+            raise TypeError(
+                f"All choice values must be str, int, or float, "
+                f"got {type(value).__name__}."
+            )
+
+    return Choice.as_decorator(values=values, case_sensitive=case_sensitive)

click_extended/decorators/misc/confirm_if.py

@@ -0,0 +1,147 @@
+"""Child decorator to conditionally prompt for user confirmation."""
+
+# pylint: disable=too-many-locals
+
+import inspect
+import os
+from typing import Any, Callable
+
+import click
+
+from click_extended.core.nodes.child_node import ChildNode
+from click_extended.core.other.context import Context
+from click_extended.types import Decorator
+
+
+class ConfirmIf(ChildNode):
+    """Child decorator to conditionally prompt for user confirmation."""
+
+    def handle_all(
+        self, value: Any, context: Context, *args: Any, **kwargs: Any
+    ) -> Any:
+        fn: Callable[[Any], bool] | Callable[[Any, Context], bool] = kwargs[
+            "fn"
+        ]
+        prompt_text: str = kwargs["prompt"]
+        truthy: list[str] = kwargs["truthy"]
+
+        sig = inspect.signature(fn)
+        accepts_context = len(sig.parameters) >= 2
+
+        if accepts_context:
+            should_confirm = fn(value, context)  # type: ignore
+        else:
+            should_confirm = fn(value)  # type: ignore
+
+        if not should_confirm:
+            return value
+
+        if os.getenv("CLICK_EXTENDED_TESTING") == "1":
+            return value
+
+        formatted_prompt = prompt_text.format(value=value).strip()
+        formatted_prompt = formatted_prompt.rstrip(":")
+
+        first_truthy = truthy[0] if truthy else "y"
+        formatted_prompt = f"{formatted_prompt} ({first_truthy}/n)"
+
+        response = click.prompt(formatted_prompt, type=str).strip()
+
+        response_lower = response.lower()
+        truthy_lower = [t.lower() for t in truthy]
+
+        if response_lower in truthy_lower:
+            return value
+        raise click.Abort()
+
+
+def confirm_if(
+    prompt: str,
+    fn: Callable[[Any], bool] | Callable[[Any, Context], bool],
+    truthy: list[str] | None = None,
+) -> Decorator:
+    """
+    Conditionally prompt for user confirmation based on a predicate function.
+
+    Type: `ChildNode`
+
+    Supports: `Any`
+
+    The predicate function can accept either just the value `fn(value)` or
+    both the value and context `fn(value, context)`. The decorator automatically
+    detects the function signature and calls it appropriately.
+
+    When the predicate returns `True`, the user is prompted for confirmation.
+    The prompt text can include `{value}` placeholder which will be replaced
+    with the actual value. The prompt is automatically formatted to remove any
+    trailing colon and append ` (y/n):` where `y` is the first truthy value.
+
+    If the environment variable `CLICK_EXTENDED_TESTING=1` is set, confirmation
+    is automatically granted without prompting (useful for automated tests).
+
+    Args:
+        prompt (str):
+            The confirmation prompt text. Can include `{value}` placeholder
+            for the current value (e.g., "Delete {value}"). Trailing colons
+            are automatically removed and ` (first_truthy/n):` is appended.
+        fn (Callable[[Any], bool] | Callable[[Any, Context], bool]):
+            Predicate function that determines whether to prompt. Returns
+            `True` to prompt for confirmation, `False` to skip. Can accept
+            either `fn(value)` or `fn(value, context)`.
+        truthy (list[str] | None, optional):
+            List of accepted confirmation responses. Case-insensitive.
+            Any response not in this list will abort execution. The first
+            value in this list is shown in the prompt hint (e.g., `(ok/n):`).
+            Defaults to `["y", "yes", "ok", "1"]`.
+
+    Raises:
+        click.Abort:
+            If the user provides a non-truthy response.
+
+    Returns:
+        Decorator:
+            The decorator function.
+
+    Examples:
+        Basic usage with value-only predicate:
+
+        ```python
+        @command()
+        @option("count", type=int)
+        @confirm_if("Are you sure?", lambda x: x > 100)
+        def process(count: int) -> None:
+            click.echo(f"Processing {count} items...")
+        ```
+
+        Using context to check other parameters:
+
+        ```python
+        @command()
+        @option("force", is_flag=True)
+        @option("file")
+        @confirm_if(
+            "Delete {value}?",
+            lambda val, ctx: not ctx.get_parent("force").get_value()
+        )
+        def delete(force: bool, file: str) -> None:
+            click.echo(f"Deleted {file}")
+        ```
+
+        Custom truthy values:
+
+        ```python
+        @command()
+        @option("path")
+        @confirm_if(
+            "Overwrite {value}?",
+            lambda x: os.path.exists(x),
+            truthy=["yes", "y", "overwrite", "ok"]
+        )
+        def save(path: str) -> None:
+            click.echo(f"Saved to {path}")
+        ```
+    """
+    if truthy is None:
+        truthy = ["y", "yes", "ok", "1"]
+
+    return ConfirmIf.as_decorator(prompt=prompt, fn=fn, truthy=truthy)

click_extended/decorators/misc/default.py

@@ -0,0 +1,95 @@
+"""Child node to set a default value if a value is not provided."""
+
+import os
+from typing import Any
+
+from click_extended.core.nodes.child_node import ChildNode
+from click_extended.core.other.context import Context
+from click_extended.types import Decorator
+
+
+class Default(ChildNode):
+    """Child node to set a default value if a value is not provided."""
+
+    def handle_all(
+        self, value: Any, context: Context, *args: Any, **kwargs: Any
+    ) -> Any:
+        parent = context.get_current_parent_as_parent()
+
+        if parent.was_provided:
+            return value
+
+        from_value = kwargs.get("from_value")
+        from_env = kwargs.get("from_env")
+        from_param = kwargs.get("from_param")
+
+        if from_value is not None:
+            return from_value
+
+        if from_env is not None:
+            env_value = os.getenv(from_env)
+            if env_value is not None:
+                return env_value
+
+        if from_param is not None:
+            param_parent = context.get_parent(from_param)
+            if param_parent is not None and param_parent.was_provided:
+                return param_parent.get_value()
+
+        return value
+
+
+def default(
+    *,
+    from_value: Any = None,
+    from_env: str | None = None,
+    from_param: str | None = None,
+) -> Decorator:
+    """
+    If a value is not provided, set a default value.
+
+    Type: `ChildNode`
+
+    Supports: `Any`
+
+    Order: `from_value`, `from_env`, `from_param`
+
+    Args:
+        from_value (Any, optional):
+            A value to default to.
+        from_env (str | None, optional):
+            The environment variable to default to.
+        from_param (str | None, optional):
+            The name of the node which value is used to default to.
+
+    Returns:
+        Decorator:
+            The decorated function.
+
+    Raises:
+        ValueError:
+            If more than one source is provided.
+    """
+    sources = [
+        from_value is not None,
+        from_env is not None,
+        from_param is not None,
+    ]
+
+    if sum(sources) > 1:
+        raise ValueError(
+            "Only one of 'from_value', 'from_env', or "
+            "'from_param' can be provided."
+        )
+
+    if sum(sources) == 0:
+        raise ValueError(
+            "At least one of 'from_value', 'from_env', or "
+            "'from_param' must be provided."
+        )
+
+    return Default.as_decorator(
+        from_value=from_value,
+        from_env=from_env,
+        from_param=from_param,
+    )

click_extended/decorators/misc/deprecated.py

@@ -0,0 +1,131 @@
+"""Show a deprecation warning for a parent node."""
+
+from typing import Any
+
+from click import echo
+
+from click_extended.core.nodes.child_node import ChildNode
+from click_extended.core.other.context import Context
+from click_extended.types import Decorator
+from click_extended.utils import is_option
+
+OLD_ONLY = "The parameter '{}' has been deprecated."
+OLD_TO_NEW = "The parameter '{}' has been deprecated. Use '{}' instead."
+OLD_SINCE = "The parameter '{}' has been deprecated since '{}'."
+OLD_REMOVED = (
+    "The parameter '{}' has been deprecated and will be removed in '{}'."
+)
+OLD_TO_NEW_SINCE = (
+    "The parameter '{}' has been deprecated since '{}'. Use '{}' instead."
+)
+OLD_TO_NEW_REMOVED = (
+    "The parameter '{}' has been deprecated and "
+    "will be removed in '{}'. Use '{}' instead."
+)
+
+OLD_SINCE_REMOVED = (
+    "The parameter '{}' was deprecated in '{}' and will be removed in '{}'."
+)
+OLD_TO_NEW_SINCE_REMOVED = (
+    "The parameter '{}' was deprecated in '{}' "
+    "and will be removed in '{}'. Use '{}' instead."
+)
+
+
+class Deprecated(ChildNode):
+    """Show a deprecation warning for a parent node."""
+
+    def handle_all(
+        self, value: Any, context: Context, *args: Any, **kwargs: Any
+    ) -> Any:
+        parent = context.get_current_parent_as_parent()
+
+        if not parent.was_provided:
+            return value
+
+        old_param = parent.name
+        if is_option(parent):
+            if parent.long_flags:
+                old_param = parent.long_flags[0]
+            else:
+                old_param = parent.name
+
+        new_name = kwargs["name"]
+        new_param = None
+
+        if new_name is not None:
+            new_parent = context.get_parent(new_name)
+            if new_parent is None:
+                raise RuntimeError(f"Parent '{new_name}' does not exist.")
+
+            new_param = new_parent.name
+            if is_option(new_parent):
+                new_param = (
+                    new_parent.long_flags[0]
+                    if new_parent.long_flags
+                    else new_parent.name
+                )
+
+            if parent == new_parent:
+                raise ValueError(
+                    f"The parent '{new_parent.name}' cannot replace itself."
+                )
+
+        since = kwargs["since"]
+        removed = kwargs["removed"]
+
+        key = (new_name is not None, since is not None, removed is not None)
+
+        messages = {
+            (False, False, False): OLD_ONLY.format(old_param),
+            (True, False, False): OLD_TO_NEW.format(old_param, new_param),
+            (False, True, False): OLD_SINCE.format(old_param, since),
+            (False, False, True): OLD_REMOVED.format(old_param, removed),
+            (True, True, False): OLD_TO_NEW_SINCE.format(
+                old_param, since, new_param
+            ),
+            (True, False, True): OLD_TO_NEW_REMOVED.format(
+                old_param, removed, new_param
+            ),
+            (False, True, True): OLD_SINCE_REMOVED.format(
+                old_param, since, removed
+            ),
+            (True, True, True): OLD_TO_NEW_SINCE_REMOVED.format(
+                old_param, since, removed, new_param
+            ),
+        }
+
+        echo(f"DeprecationWarning: {messages[key]}", err=True)
+
+        return value
+
+
+def deprecated(
+    name: str | None = None,
+    since: str | None = None,
+    removed: str | None = None,
+) -> Decorator:
+    """
+    Show a deprecation warning when using a parameter.
+
+    Type: `ChildNode`
+
+    Supports: `Any`
+
+    Args:
+        name (str):
+            The name of the new parameter.
+        since (str):
+            The version in which the parameter was deprecated.
+        removed (str):
+            The version the parameter will be removed.
+
+    Returns:
+        Decorator:
+            The decorated function.
+    """
+    return Deprecated.as_decorator(
+        name=name,
+        since=since,
+        removed=removed,
+    )

click_extended/decorators/misc/experimental.py

@@ -0,0 +1,79 @@
+"""Child node for warning the user that a parent is experimental."""
+
+from typing import Any
+
+from click import echo
+
+from click_extended.core.nodes.child_node import ChildNode
+from click_extended.core.other.context import Context
+from click_extended.types import Decorator
+from click_extended.utils import is_option
+
+EMPTY = "The parameter '{}' is experimental."
+SINCE = "The parameter '{}' is experimental since '{}'."
+STABLE = "The parameter '{}' is experimental and will stable in '{}'."
+SINCE_STABLE = (
+    "The parameter '{}' is experimental since '{}' and will stable in '{}'."
+)
+
+
+class Experimental(ChildNode):
+    """Child node for warning the user that a parent is experimental."""
+
+    def handle_all(
+        self, value: Any, context: Context, *args: Any, **kwargs: Any
+    ) -> Any:
+        parent = context.get_current_parent_as_parent()
+
+        if not parent.was_provided:
+            return value
+
+        message = kwargs["message"]
+        since = kwargs["since"]
+        stable = kwargs["stable"]
+
+        if message is not None:
+            echo(f"ExperimentalWarning: {message}")
+            return value
+
+        name = parent.name
+
+        if is_option(parent):
+            name = parent.long_flags[0] if parent.long_flags else parent.name
+
+        key = (since is not None, stable is not None)
+
+        messages = {
+            (False, False): EMPTY.format(name),
+            (True, False): SINCE.format(name, since),
+            (False, True): STABLE.format(name, stable),
+            (True, True): SINCE_STABLE.format(name, since, stable),
+        }
+
+        echo(f"ExperimentalWarning: {messages[key]}", err=True)
+
+        return value
+
+
+def experimental(
+    *,
+    message: str | None = None,
+    since: str | None = None,
+    stable: str | None = None,
+) -> Decorator:
+    """
+
+
+    Type: `ChildNode`
+
+    Supports: `Any`
+
+    Returns:
+        Decorator:
+            The decorated function.
+    """
+    return Experimental.as_decorator(
+        message=message,
+        since=since,
+        stable=stable,
+    )

click_extended/decorators/misc/now.py

@@ -0,0 +1,42 @@
+"""Parent node to return the current time."""
+
+from datetime import datetime
+from typing import Any
+from zoneinfo import ZoneInfo
+
+from click_extended.core.nodes.parent_node import ParentNode
+from click_extended.core.other.context import Context
+from click_extended.types import Decorator
+
+
+class Now(ParentNode):
+    """Parent node to return the current time."""
+
+    def load(self, context: Context, *args: Any, **kwargs: Any) -> Any:
+        tz_name = kwargs.get("tz", "UTC")
+
+        try:
+            tz = ZoneInfo(tz_name)
+        except Exception as e:
+            raise ValueError(f"Invalid timezone '{tz_name}': {e}") from e
+
+        return datetime.now(tz)
+
+
+def now(name: str, tz: str = "UTC") -> Decorator:
+    """
+    Parent node to return the current time.
+
+    Type: `ParentNode`
+
+    Args:
+        name (str):
+            The name of the parameter.
+        tz (str, optional):
+            The timezone to use for the datetime. Defaults to "UTC".
+
+    Returns:
+        Decorator:
+            The decorated function.
+    """
+    return Now.as_decorator(name=name, tz=tz)

click_extended/decorators/random/__init__.py

@@ -0,0 +1,21 @@
+"""Initialization file for the `click_extended.decorators.random` module."""
+
+from click_extended.decorators.random.random_bool import random_bool
+from click_extended.decorators.random.random_choice import random_choice
+from click_extended.decorators.random.random_datetime import random_datetime
+from click_extended.decorators.random.random_float import random_float
+from click_extended.decorators.random.random_integer import random_integer
+from click_extended.decorators.random.random_prime import random_prime
+from click_extended.decorators.random.random_string import random_string
+from click_extended.decorators.random.random_uuid import random_uuid
+
+__all__ = [
+    "random_bool",
+    "random_choice",
+    "random_datetime",
+    "random_float",
+    "random_integer",
+    "random_prime",
+    "random_string",
+    "random_uuid",
+]