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

click_extended/decorators/check/conflicts.py

@@ -0,0 +1,149 @@
+"""Conflicts decorator for enforcing parameter conflicts."""
+
+from typing import Any
+
+from click_extended.core.decorators.tag import Tag
+from click_extended.core.nodes.child_node import ChildNode
+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.humanize import humanize_iterable
+
+
+class Conflicts(ChildNode):
+    """Child node to enforce that conflicting parameters are not provided."""
+
+    def handle_all(
+        self, value: Any, context: Context, *args: Any, **kwargs: Any
+    ) -> Any:
+        parent = context.parent
+        if parent is None or not isinstance(parent, ParentNode):
+            return value
+
+        if not parent.was_provided:
+            return value
+
+        if conflicting := self._get_conflicting_params(context, args):
+            parent_display = parent.get_display_name()
+            conflicting_display = humanize_iterable(
+                [self._get_display_name(name, context) for name in conflicting],
+                wrap="'",
+            )
+
+            raise ValueError(
+                f"'{parent_display}' conflicts with {conflicting_display}. "
+                f"They cannot be used together."
+            )
+
+        return value
+
+    def handle_tag(
+        self, value: dict[str, Any], context: Context, *args: Any, **kwargs: Any
+    ) -> None:
+        tag = context.parent
+        if tag is None or not isinstance(tag, Tag):
+            return
+
+        tagged_parents = getattr(tag, "parent_nodes", [])
+        if not tagged_parents:
+            return
+
+        for parent in tagged_parents:
+            if not parent.was_provided:
+                continue
+
+            if conflicting := self._get_conflicting_params(context, args):
+                parent_display = parent.get_display_name()
+                conflicting_display = humanize_iterable(
+                    [
+                        self._get_display_name(name, context)
+                        for name in conflicting
+                    ],
+                    wrap="'",
+                )
+
+                raise ValueError(
+                    f"'{parent_display}' conflicts with {conflicting_display}. "
+                    f"They cannot be used together."
+                )
+
+    def _get_conflicting_params(
+        self, context: Context, names: tuple[str, ...]
+    ) -> list[str]:
+        conflicting: list[str] = []
+
+        for param_name in names:
+            parent = context.get_parent(param_name)
+            if parent is not None and parent.was_provided:
+                conflicting.append(param_name)
+
+        return conflicting
+
+    def _get_display_name(self, param_name: str, context: Context) -> str:
+        parent = context.get_parent(param_name)
+        if parent is not None:
+            return parent.get_display_name()
+        return param_name
+
+
+def conflicts(*names: str) -> Decorator:
+    """
+    Enforce that parameters conflict with each other.
+
+    This decorator ensures that when the decorated parameter is provided,
+    none of the specified conflicting parameters can be provided.
+
+    Type: `ChildNode`
+
+    Supports: `any`, `tag`
+
+    Args:
+        *names (str):
+            Names of parameters that conflict with the decorated parameter.
+
+    Returns:
+        Decorator:
+            A decorator function that registers the conflicts validation.
+
+    Raises:
+        ValueError:
+            If the decorated parameter and any conflicting parameter
+            are both provided at runtime.
+
+    Examples:
+        ```python
+        from click_extended import option, conflicts
+
+        @option("--username")
+        @conflicts("api_key")
+        @option("--api-key")
+        def login(username, api_key):
+            '''Login using username or API key, but not both.'''
+            pass
+        ```
+
+        Multiple conflicts:
+        ```python
+        @option("--verbose", "-v")
+        @conflicts("quiet", "silent")
+        @option("--quiet", "-q")
+        @option("--silent", "-s")
+        def cmd(verbose, quiet, silent):
+            '''Verbose mode conflicts with quiet and silent modes.'''
+            pass
+        ```
+
+        Works with tags:
+        ```python
+        @option("--basic-auth")
+        @conflicts("oauth")  # All params tagged "oauth"
+        @option("--oauth-token")
+        @tag("oauth")
+        def authenticate(basic_auth, oauth_token):
+            pass
+        ```
+    """
+    return Conflicts.as_decorator(*names)
+
+
+__all__ = ["conflicts", "Conflicts"]

click_extended/decorators/check/contains.py

@@ -0,0 +1,69 @@
+"""Check if the string contains the specified text."""
+
+# pylint: disable=redefined-builtin
+
+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 Contains(ChildNode):
+    """Check if the string contains the specified text."""
+
+    def handle_str(
+        self,
+        value: str,
+        context: Context,
+        *args: Any,
+        **kwargs: Any,
+    ) -> str:
+        require_all = kwargs.get("all", False)
+        matches = [t in value for t in args]
+
+        if require_all:
+            if not all(matches):
+                missing = [t for t, m in zip(args, matches) if not m]
+                humanized = humanize_iterable(
+                    missing,
+                    wrap="'",
+                    prefix_singular="contain the required substring",
+                    prefix_plural="contain all the required substrings",
+                )
+                raise ValueError(f"Value '{value}' does not {humanized}")
+        else:
+            if not any(matches):
+                humanized = humanize_iterable(
+                    args,
+                    wrap="'",
+                    prefix_singular="contain the required substring",
+                    prefix_plural="contain any of the required substrings",
+                )
+                raise ValueError(f"Value '{value}' does not {humanized}")
+
+        return value
+
+
+def contains(*text: str, all: bool = False) -> Decorator:
+    """
+    Check if the string contains the specified text.
+
+    Type: `ChildNode`
+
+    Supports: `str`
+
+    Args:
+        *text (str):
+            The substrings to check for.
+        all (bool):
+            If `True`, all substrings must be present.
+            If `False`, at least one substring must be present.
+            Defaults to `False`.
+
+    Returns:
+        Decorator:
+            The decorated function.
+    """
+    return Contains.as_decorator(*text, all=all)

click_extended/decorators/check/dependencies.py

@@ -0,0 +1,115 @@
+"""Mutual dependency validation decorator."""
+
+from typing import TYPE_CHECKING, Any
+
+from click_extended.core.nodes.validation_node import ValidationNode
+from click_extended.core.other.context import Context
+from click_extended.types import Decorator
+from click_extended.utils.humanize import humanize_iterable
+
+if TYPE_CHECKING:
+    from click_extended.core.nodes.parent_node import ParentNode
+
+
+class Dependencies(ValidationNode):
+    """
+    Validation node that ensures mutual dependencies between parameters.
+
+    If any parameter in a dependency group is provided, all parameters
+    in that group must be provided.
+
+    Examples:
+        # Single dependency group
+        @dependencies("username", "password")
+        def login(username, password): ...
+
+        # Multiple dependency groups
+        @dependencies("username", "password")
+        @dependencies("api_key", "api_secret")
+        def auth(username, password, api_key, api_secret): ...
+
+        # Works with tags too
+        @dependencies("credentials")  # All params tagged "credentials"
+        def login(**kwargs): ...
+    """
+
+    def on_finalize(self, context: Context, *args: Any, **kwargs: Any) -> None:
+        """
+        Validate mutual dependencies at finalization.
+
+        Args:
+            context: The execution context
+            *args: Additional positional arguments
+            **kwargs: Additional keyword arguments
+
+        Raises:
+            ProcessError: If some but not all dependencies are provided
+        """
+        provided_params: list[str] = []
+        missing_params: list[str] = []
+        names = args
+        parent: "ParentNode | None"
+
+        for name in names:
+            tag = context.get_tag(name)
+            if tag is not None:
+                for parent in tag.parent_nodes:
+                    if parent.was_provided:
+                        provided_params.append(parent.get_display_name())
+                    else:
+                        missing_params.append(parent.get_display_name())
+            else:
+                if (parent := context.get_parent(name)) is not None:
+                    if parent.was_provided:
+                        provided_params.append(parent.get_display_name())
+                    else:
+                        missing_params.append(parent.get_display_name())
+
+        if provided_params and missing_params:
+            provided_str = humanize_iterable(provided_params, wrap="'")
+            missing_str = humanize_iterable(
+                missing_params,
+                wrap="'",
+                prefix_singular="requires",
+                prefix_plural="require",
+            )
+
+            raise ValueError(f"{provided_str} {missing_str} to be provided.")
+
+
+def dependencies(*names: str) -> Decorator:
+    """
+    Decorator that validates mutual dependencies between parameters.
+
+    If any parameter in the dependency group is provided, all must be provided.
+
+    Type: `ValidationNode`
+
+    Args:
+        *names: Parameter names or tag names that are mutually dependent
+
+    Returns:
+        Decorator function
+
+    Examples:
+        @command()
+        @option("--username")
+        @option("--password")
+        @dependencies("username", "password")
+        def login(username, password):
+            # If username is provided, password must also be provided
+            # If password is provided, username must also be provided
+            pass
+
+        @command()
+        @option("--api-key")
+        @option("--api-secret")
+        @option("--username")
+        @option("--password")
+        @dependencies("api_key", "api_secret")
+        @dependencies("username", "password")
+        def auth(**kwargs):
+            # Two separate dependency groups
+            pass
+    """
+    return Dependencies.as_decorator(*names)

click_extended/decorators/check/divisible_by.py

@@ -0,0 +1,48 @@
+"""Check if a value is divisible by a number."""
+
+from decimal import Decimal, getcontext
+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
+
+getcontext().prec = 35
+
+
+class DivisibleBy(ChildNode):
+    """Check if a value is divisible by a number."""
+
+    def handle_numeric(
+        self,
+        value: int | float,
+        context: Context,
+        *args: Any,
+        **kwargs: Any,
+    ) -> int | float:
+        n = kwargs["n"]
+        val = Decimal(str(value))
+        div = Decimal(str(n))
+
+        if val % div != 0:
+            raise ValueError(f"Value '{value}' is not divisible by '{n}'.")
+
+        return value
+
+
+def divisible_by(n: int | float) -> Decorator:
+    """
+    Check if a value is divisible by a number.
+
+    Type: `ChildNode`
+
+    Supports: `int`, `float`
+
+    Args:
+        n (int | float): The number to check divisibility against.
+
+    Returns:
+        Decorator:
+            The decorated function.
+    """
+    return DivisibleBy.as_decorator(n=n)

click_extended/decorators/check/ends_with.py

@@ -0,0 +1,85 @@
+"""Child decorator to check if a string ends with one or more substrings."""
+
+import fnmatch
+import re
+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 EndsWith(ChildNode):
+    """Child decorator to check if a string ends with one or more substrings."""
+
+    def handle_str(
+        self, value: str, context: Context, *args: Any, **kwargs: Any
+    ) -> Any:
+        patterns: tuple[str | re.Pattern[str], ...] = kwargs.get("text", ())
+        matches: list[str | re.Pattern[str]] = []
+
+        for pattern in patterns:
+            if isinstance(pattern, re.Pattern):
+                if pattern.search(value):
+                    matches.append(pattern)
+            elif isinstance(pattern, str) and any(
+                char in pattern for char in ["*", "?", "[", "]"]
+            ):
+                if fnmatch.fnmatch(
+                    value,
+                    f"*{pattern}" if not pattern.startswith("*") else pattern,
+                ):
+                    matches.append(pattern)
+            elif isinstance(pattern, str):
+                if value.endswith(pattern):
+                    matches.append(pattern)
+
+        if not matches:
+            pattern_strs: list[str] = [
+                p.pattern if isinstance(p, re.Pattern) else p for p in patterns
+            ]
+            pattern_list = humanize_iterable(
+                pattern_strs,
+                wrap="'",
+                sep="or",
+                prefix_singular="the pattern",
+                prefix_plural="one of the patterns",
+            )
+            raise ValueError(f"Value must end with {pattern_list}")
+
+        return value
+
+
+def ends_with(*text: str | re.Pattern[str]) -> Decorator:
+    """
+    Check if a string ends with one or more substrings or patterns.
+
+    Type: `ChildNode`
+
+    Supports: `str`
+
+    Args:
+        *text (str | re.Pattern[str]):
+            Patterns to check for.
+
+    Returns:
+        Decorator:
+            The decorated function.
+
+    Examples:
+        ```python
+        # Exact suffix
+        @ends_with(".com", ".org")
+
+        # Glob pattern
+        @ends_with("*_test", "*_prod")
+
+        # Regex matching
+        @ends_with(re.compile(r"\\.(com|org|net)$"))
+
+        # Mixed patterns
+        @ends_with(".txt", re.compile(r"\\.\\d+$"), "*.log")
+        ```
+    """
+    return EndsWith.as_decorator(text=text)

click_extended/decorators/check/exclusive.py

@@ -0,0 +1,75 @@
+"""Exclusive group decorator for validating mutual exclusivity."""
+
+from typing import Any
+
+from click_extended.core.nodes.validation_node import ValidationNode
+from click_extended.core.other.context import Context
+from click_extended.types import Decorator
+from click_extended.utils.humanize import humanize_iterable
+
+
+class ExclusiveGroup(ValidationNode):
+    """Validation node to enforce mutual exclusivity between parameters."""
+
+    def on_finalize(self, context: Context, *args: Any, **kwargs: Any) -> None:
+        names = args if args else kwargs.get("params", ())
+
+        if not names:
+            return
+
+        provided: list[str] = []
+        for param_name in names:
+            parent = context.get_parent(param_name)
+            if parent is not None and parent.was_provided:
+                provided.append(param_name)
+
+        if len(provided) > 1:
+            humanized = humanize_iterable(provided, wrap="'")
+            raise ValueError(
+                f"The parameters {humanized} are mutually exclusive. "
+                f"Only one can be provided, but {len(provided)} were given."
+            )
+
+
+def exclusive(*names: str) -> Decorator:
+    """
+    Enforce mutual exclusivity between multiple parameters.
+
+    Type: `ValidationNode`
+
+    Args:
+        *names (str):
+            Names of parameters that should be mutually exclusive.
+
+    Returns:
+        Decorator:
+            A decorator function that registers the exclusive group validation.
+
+    Raises:
+        ValueError:
+            If more than one parameter from the group is provided at runtime.
+
+    Examples:
+        ```python
+        @command()
+        @exclusive_group("json", "xml", "yaml")
+        @option("--json", is_flag=True)
+        @option("--xml", is_flag=True)
+        @option("--yaml", is_flag=True)
+        def my_command(json: bool, xml: bool, yaml: bool):
+            # Only one format can be specified
+            pass
+        ```
+
+        ```python
+        @command()
+        @exclusive_group("p", "q", "r")
+        @random_prime("p")
+        @random_prime("q")
+        @random_prime("r")
+        def my_command(p: int, q: int, r: int):
+            # Only one prime can be provided
+            pass
+        ```
+    """
+    return ExclusiveGroup.as_decorator(*names)

click_extended/decorators/check/falsy.py

@@ -0,0 +1,37 @@
+"""Check if a value is falsy."""
+
+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 Falsy(ChildNode):
+    """Check if a value is falsy."""
+
+    def handle_all(
+        self,
+        value: Any,
+        context: Context,
+        *args: Any,
+        **kwargs: Any,
+    ) -> Any:
+        if value:
+            raise ValueError(f"Value '{value}' is not falsy.")
+        return value
+
+
+def falsy() -> Decorator:
+    """
+    Check if a value is falsy.
+
+    Type: `ChildNode`
+
+    Supports: `Any`
+
+    Returns:
+        Decorator:
+            The decorated function.
+    """
+    return Falsy.as_decorator()

click_extended/decorators/check/is_email.py

@@ -0,0 +1,43 @@
+"""Check if a value is a valid email address."""
+
+from typing import Any
+
+from email_validator import EmailNotValidError, validate_email
+
+from click_extended.core.nodes.child_node import ChildNode
+from click_extended.core.other.context import Context
+from click_extended.types import Decorator
+
+
+class IsEmail(ChildNode):
+    """Check if a value is a valid email address."""
+
+    def handle_str(
+        self,
+        value: str,
+        context: Context,
+        *args: Any,
+        **kwargs: Any,
+    ) -> Any:
+        try:
+            validate_email(value, check_deliverability=False)
+        except EmailNotValidError as e:
+            raise ValueError(
+                f"Value '{value}' is not a valid email address ({e})."
+            ) from e
+        return value
+
+
+def is_email() -> Decorator:
+    """
+    Check if a value is a valid email address.
+
+    Type: `ChildNode`
+
+    Supports: `str`
+
+    Returns:
+        Decorator:
+            The decorated function.
+    """
+    return IsEmail.as_decorator()

click_extended/decorators/check/is_hex_color.py

@@ -0,0 +1,41 @@
+"""Check if a value is a valid hex color code."""
+
+import re
+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
+
+HEX_PATTERN = re.compile(r"^#?([0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$")
+
+
+class IsHexColor(ChildNode):
+    """Check if a value is a valid hex color code."""
+
+    def handle_str(
+        self,
+        value: str,
+        context: Context,
+        *args: Any,
+        **kwargs: Any,
+    ) -> Any:
+        if not re.fullmatch(HEX_PATTERN, value):
+            raise ValueError(f"Value '{value}' is not a valid hex color.")
+
+        return value
+
+
+def is_hex_color() -> Decorator:
+    """
+    Check if a value is a valid hex color code.
+
+    Type: `ChildNode`
+
+    Supports: `str`
+
+    Returns:
+        Decorator:
+            The decorated function.
+    """
+    return IsHexColor.as_decorator()