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

click_extended/decorators/check/requires.py

@@ -0,0 +1,190 @@
+"""Requires decorator for enforcing parameter dependencies."""
+
+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 Requires(ChildNode):
+    """Child node to enforce that required parameters are 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 missing := self._get_missing_requirements(context, args):
+            parent_display = parent.get_display_name()
+            missing_display = humanize_iterable(
+                [self._get_display_name(name, context) for name in missing],
+                wrap="'",
+            )
+
+            raise ValueError(
+                f"'{parent_display}' requires {missing_display} to be provided."
+            )
+
+        return value
+
+    def handle_tag(
+        self, value: dict[str, Any], context: Context, *args: Any, **kwargs: Any
+    ) -> None:
+        """Validate requirements for tags."""
+        tag = context.parent
+        if tag is None or not isinstance(tag, Tag):
+            return
+
+        tagged_parents = getattr(tag, "parent_nodes", [])
+        if not tagged_parents:
+            return
+
+        provided_count = sum(1 for p in tagged_parents if p.was_provided)
+
+        require_all_tagged = kwargs.get("require_all_tagged", True)
+        should_check = False
+        if require_all_tagged:
+            should_check = provided_count > 0
+        else:
+            should_check = provided_count == len(tagged_parents)
+
+        if not should_check:
+            return
+
+        if missing := self._get_missing_requirements(context, args):
+            tag_display = f"tag '{tag.name}'"
+            missing_display = humanize_iterable(
+                [self._get_display_name(name, context) for name in missing],
+                wrap="'",
+            )
+
+            raise ValueError(
+                f"'{tag_display}' requires {missing_display} to be provided."
+            )
+
+    def _get_missing_requirements(
+        self, context: Context, required_names: tuple[Any, ...]
+    ) -> list[str]:
+        missing: list[str] = []
+
+        for name in required_names:
+            parent = context.get_parent(name)
+            if parent is not None:
+                if not parent.was_provided:
+                    missing.append(name)
+                continue
+
+            if (tag := context.get_tag(name)) is not None:
+                tagged_parents = getattr(tag, "parent_nodes", [])
+                if not any(p.was_provided for p in tagged_parents):
+                    missing.append(name)
+                continue
+
+            raise ValueError(
+                f"Required parameter or tag '{name}' does not exist. "
+                f"Check that it is defined in the command."
+            )
+
+        return missing
+
+    def _get_display_name(self, name: str, context: Context) -> str:
+        parent = context.get_parent(name)
+        if parent is not None:
+            return parent.get_display_name()
+
+        tag = context.get_tag(name)
+        if tag is not None:
+            return f"tag '{tag.name}'"
+
+        return name
+
+
+def requires(*names: str, require_all_tagged: bool = True) -> Decorator:
+    """
+    Enforce that specified parameters or tags are provided.
+
+    Type: `ChildNode`
+
+    Supports: `any`, `tag`
+
+    Args:
+        *names (str):
+            Names of parameters or tags that must be provided.
+        require_all_tagged (bool):
+            If a tag is references, all parents must be provided.
+            Defaults to `True`.
+
+    Returns:
+        Decorator:
+            The decorated function.
+
+    Raises:
+        ValueError:
+            If the parent/tag is provided but required dependencies are not met,
+            or if a required name doesn't exist.
+
+    Examples:
+        Basic requirement:
+        ```python
+        @command()
+        @option("--output")
+        @requires("input")
+        @option("--input")
+        def my_command(input: str, output: str):
+            # --output requires --input to be provided
+            pass
+        ```
+
+        Multiple requirements:
+        ```python
+        @command()
+        @option("--save")
+        @requires("format", "output")
+        @option("--format")
+        @option("--output")
+        def my_command(save: bool, format: str, output: str):
+            # --save requires both --format and --output
+            pass
+        ```
+
+        Tag requirements:
+
+        ```python
+        @command()
+        @tag("database")
+        @requires("host", "port")
+        @option("--database-name")
+        @option("--database-user")
+        @option("--host")
+        @option("--port")
+        def my_command(**kwargs):
+            pass
+        ```
+
+        Tag with require_all_tagged=False:
+
+        ```python
+        @command()
+        @tag("advanced")
+        @requires("config", require_all_tagged=False)
+        # Only if ALL advanced options provided, require config
+        @option("--verbose")
+        @option("--debug")
+        @option("--config")
+        def my_command(**kwargs):
+            pass
+        ```
+    """
+    return Requires.as_decorator(*names, require_all_tagged=require_all_tagged)
+
+
+__all__ = ["requires", "Requires"]

click_extended/decorators/check/starts_with.py

@@ -0,0 +1,87 @@
+"""Child decorator to check if a string starts 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 StartsWith(ChildNode):
+    """
+    Child decorator to check if a string starts 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.match(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.endswith("*") else pattern,
+                ):
+                    matches.append(pattern)
+            elif isinstance(pattern, str):
+                if value.startswith(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 start with {pattern_list}")
+
+        return value
+
+
+def starts_with(*text: str | re.Pattern[str]) -> Decorator:
+    """
+    Check if a string starts 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 prefix
+        @starts_with("http://", "https://")
+
+        # Glob pattern
+        @starts_with("user_*", "admin_*")
+
+        # Regex matching
+        @starts_with(re.compile(r"https?://"))
+
+        # Mixed patterns
+        @starts_with("www.", re.compile(r"https?://"), "ftp_*")
+        ```
+    """
+    return StartsWith.as_decorator(text=text)

click_extended/decorators/check/truthy.py

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

click_extended/decorators/compare/__init__.py

@@ -0,0 +1,15 @@
+"""Initialization file for the `click_extended.decorators.compare` module."""
+
+from click_extended.decorators.compare.at_least import at_least
+from click_extended.decorators.compare.at_most import at_most
+from click_extended.decorators.compare.between import between
+from click_extended.decorators.compare.greater_than import greater_than
+from click_extended.decorators.compare.less_than import less_than
+
+__all__ = [
+    "at_least",
+    "at_most",
+    "between",
+    "greater_than",
+    "less_than",
+]

click_extended/decorators/compare/at_least.py

@@ -0,0 +1,57 @@
+"""A child decorator to check if at least n number or arguments are provided."""
+
+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 AtLeast(ChildNode):
+    """
+    A child decorator to check if at least n
+    number or arguments are provided.
+    """
+
+    def handle_tag(
+        self,
+        value: Any,
+        context: Context,
+        *args: Any,
+        **kwargs: Any,
+    ) -> None:
+        if context.parent is None:
+            raise EnvironmentError("Parent is not defined.")
+
+        parents = context.get_tagged(context.parent.name)
+        required = kwargs["n"]
+        provided = sum(p.was_provided for p in parents)
+
+        if provided < required:
+            humanized = humanize_iterable([p.name for p in parents], wrap="'")
+            word = "was" if provided == 1 else "were"
+            raise ValueError(
+                f"At least {required} of {humanized} must be provided, "
+                f"but only {provided} {word} given."
+            )
+
+
+def at_least(n: int) -> Decorator:
+    """
+    Checks if at least `n` number of arguments
+    are provided.
+
+    Type: `ChildNode`
+
+    Supports: `Tag`
+
+    Args:
+        n (int):
+            The number of arguments required.
+
+    Returns:
+        Decorator:
+            The decorated function.
+    """
+    return AtLeast.as_decorator(n=n)

click_extended/decorators/compare/at_most.py

@@ -0,0 +1,57 @@
+"""A child decorator to check if at most n number or arguments are provided."""
+
+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 AtMost(ChildNode):
+    """
+    A child decorator to check if at most n
+    number or arguments are provided.
+    """
+
+    def handle_tag(
+        self,
+        value: Any,
+        context: Context,
+        *args: Any,
+        **kwargs: Any,
+    ) -> None:
+        if context.parent is None:
+            raise EnvironmentError("Parent is not defined.")
+
+        parents = context.get_tagged(context.parent.name)
+        maximum = kwargs["n"]
+        provided = sum(p.was_provided for p in parents)
+
+        if provided > maximum:
+            humanized = humanize_iterable([p.name for p in parents], wrap="'")
+            word = "was" if provided == 1 else "were"
+            raise ValueError(
+                f"At most {maximum} of {humanized} can be provided, "
+                f"but {provided} {word} given."
+            )
+
+
+def at_most(n: int) -> Decorator:
+    """
+    Checks if at most `n` number of arguments
+    are provided.
+
+    Type: `ChildNode`
+
+    Supports: `Tag`
+
+    Args:
+        n (int):
+            The maximum number of arguments allowed.
+
+    Returns:
+        Decorator:
+            The decorated function.
+    """
+    return AtMost.as_decorator(n=n)

click_extended/decorators/compare/between.py

@@ -0,0 +1,119 @@
+"""Check if a value is between two bounds."""
+
+from datetime import date, datetime, time
+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 Between(ChildNode):
+    """Check if a value is between two bounds."""
+
+    def _check_between(
+        self,
+        value: Any,
+        lower: Any,
+        upper: Any,
+        inclusive: bool,
+    ) -> Any:
+        if inclusive:
+            if not lower <= value <= upper:
+                raise ValueError(
+                    f"Value '{value}' is not between '{lower}' and '{upper}'."
+                )
+        else:
+            if not lower < value < upper:
+                raise ValueError(
+                    f"Value '{value}' is not between '{lower}' and '{upper}'."
+                )
+        return value
+
+    def handle_numeric(
+        self,
+        value: int | float,
+        context: Context,
+        *args: Any,
+        **kwargs: Any,
+    ) -> Any:
+        return self._check_between(
+            value,
+            kwargs["lower"],
+            kwargs["upper"],
+            kwargs["inclusive"],
+        )
+
+    def handle_time(
+        self,
+        value: time,
+        context: Context,
+        *args: Any,
+        **kwargs: Any,
+    ) -> Any:
+        return self._check_between(
+            value,
+            kwargs["lower"],
+            kwargs["upper"],
+            kwargs["inclusive"],
+        )
+
+    def handle_date(
+        self,
+        value: date,
+        context: Context,
+        *args: Any,
+        **kwargs: Any,
+    ) -> Any:
+        return self._check_between(
+            value,
+            kwargs["lower"],
+            kwargs["upper"],
+            kwargs["inclusive"],
+        )
+
+    def handle_datetime(
+        self,
+        value: datetime,
+        context: Context,
+        *args: Any,
+        **kwargs: Any,
+    ) -> Any:
+        return self._check_between(
+            value,
+            kwargs["lower"],
+            kwargs["upper"],
+            kwargs["inclusive"],
+        )
+
+
+def between(
+    lower: int | float | date | time | datetime,
+    upper: int | float | date | time | datetime,
+    inclusive: bool = True,
+) -> Decorator:
+    """
+    Check if a value is between two bounds where the bounds must be of
+    the same type.
+
+    Type: `ChildNode`
+
+    Supports: `int`, `float`, `date`, `time`, `datetime`
+
+    Args:
+        lower (int | float | date | time | datetime):
+            The lower bound to check.
+        upper (int | float | date | time | datetime):
+            The upper bound to check.
+        inclusive (bool, optional):
+            Whether to include the bounds or not. Defaults to `True`.
+
+    Returns:
+        Decorator:
+            The decorated function.
+    """
+    return Between.as_decorator(
+        lower=lower,
+        upper=upper,
+        inclusive=inclusive,
+    )