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

click_extended/decorators/random/random_uuid.py

@@ -0,0 +1,119 @@
+"""Parent node for generating a random UUID."""
+
+import random
+from typing import Any, Literal
+from uuid import UUID, uuid1, uuid3, uuid5
+
+from click_extended.classes import ParentNode
+from click_extended.core.other.context import Context
+from click_extended.types import Decorator
+
+
+class RandomUUID(ParentNode):
+    """Parent node for generating a random UUID."""
+
+    @staticmethod
+    def _validate_namespace(namespace: UUID | str | None, version: int) -> UUID:
+        """Validate and convert namespace to UUID object."""
+        if namespace is None:
+            raise ValueError(
+                f"namespace is required for UUID version {version}"
+            )
+        if isinstance(namespace, str):
+            try:
+                return UUID(namespace)
+            except ValueError as exc:
+                raise ValueError(
+                    f"Invalid namespace UUID format: '{namespace}'. "
+                    f"Expected a valid UUID string "
+                    f"(e.g., '6ba7b810-9dad-11d1-80b4-00c04fd430c8') "
+                    f"or use predefined constants like uuid.NAMESPACE_DNS"
+                ) from exc
+        return namespace
+
+    def load(self, context: Context, *args: Any, **kwargs: Any) -> UUID:
+        if kwargs.get("seed") is not None:
+            random.seed(kwargs["seed"])
+
+        version = kwargs.get("version", 4)
+
+        if version == 1:
+            return uuid1()
+
+        if version == 3:
+            namespace = self._validate_namespace(kwargs.get("namespace"), 3)
+            uuid_name = kwargs.get("uuid_name")
+            if uuid_name is None:
+                raise ValueError("uuid_name is required for UUID version 3")
+            return uuid3(namespace, uuid_name)
+
+        if version == 4:
+            random_bytes = bytearray(random.getrandbits(8) for _ in range(16))
+            random_bytes[6] = (random_bytes[6] & 0x0F) | 0x40
+            random_bytes[8] = (random_bytes[8] & 0x3F) | 0x80
+            return UUID(bytes=bytes(random_bytes))
+
+        if version == 5:
+            namespace = self._validate_namespace(kwargs.get("namespace"), 5)
+            uuid_name = kwargs.get("uuid_name")
+            if uuid_name is None:
+                raise ValueError("uuid_name is required for UUID version 5")
+            return uuid5(namespace, uuid_name)
+
+        raise ValueError(
+            f"Unsupported UUID version: {version}. "
+            f"Supported versions are 1, 3, 4, and 5."
+        )
+
+
+def random_uuid(
+    name: str,
+    version: Literal[1, 3, 4, 5] = 4,
+    namespace: UUID | str | None = None,
+    uuid_name: str | None = None,
+    seed: int | None = None,
+) -> Decorator:
+    """
+    Generate a random UUID.
+
+    Type: `ParentNode`
+
+    Args:
+        name (str):
+            The name of the parent node.
+        version (Literal[1, 3, 4, 5], optional):
+            The version of the UUID. Defaults to 4.
+            - Version 1: Time-based UUID (includes MAC address and timestamp)
+            - Version 3: MD5 hash of namespace + name (deterministic)
+            - Version 4: Random UUID (recommended for most use cases)
+            - Version 5: SHA-1 hash of namespace + name (deterministic)
+        namespace (UUID | str | None, optional):
+            The namespace UUID for versions 3 and 5. Required for those
+            versions. Must be a valid UUID object, a valid UUID string in the
+            format 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx', or use predefined
+            constants from the uuid module (NAMESPACE_DNS, NAMESPACE_URL,
+            NAMESPACE_OID, NAMESPACE_X500). The namespace acts as a domain
+            identifier to generate deterministic UUIDs.
+        uuid_name (str | None, optional):
+            The name string for versions 3 and 5. Required for those versions.
+            This is combined with the namespace to generate a deterministic
+            UUID. The same namespace and name will always produce the same UUID.
+        seed (int | None, optional):
+            Optional seed for reproducible UUIDs (only affects version 4).
+
+    Returns:
+        Decorator:
+            The decorator function.
+
+    Raises:
+        ValueError:
+            If an unsupported UUID version is specified or if namespace/name
+            are missing for versions 3 or 5.
+    """
+    return RandomUUID.as_decorator(
+        name=name,
+        version=version,
+        namespace=namespace,
+        uuid_name=uuid_name,
+        seed=seed,
+    )

click_extended/decorators/transform/__init__.py

@@ -0,0 +1,71 @@
+"""Initialization file for the `click_extended.decorators.transform` module."""
+
+from click_extended.decorators.transform.add_prefix import add_prefix
+from click_extended.decorators.transform.add_suffix import add_suffix
+from click_extended.decorators.transform.apply import apply
+from click_extended.decorators.transform.basename import basename
+from click_extended.decorators.transform.dirname import dirname
+from click_extended.decorators.transform.expand_vars import expand_vars
+from click_extended.decorators.transform.remove_prefix import remove_prefix
+from click_extended.decorators.transform.remove_suffix import remove_suffix
+from click_extended.decorators.transform.replace import replace
+from click_extended.decorators.transform.slugify import slugify
+from click_extended.decorators.transform.split import split
+from click_extended.decorators.transform.strip import lstrip, rstrip, strip
+from click_extended.decorators.transform.to_case import (
+    to_camel_case,
+    to_dot_case,
+    to_flat_case,
+    to_kebab_case,
+    to_lower_case,
+    to_meme_case,
+    to_pascal_case,
+    to_path_case,
+    to_screaming_snake_case,
+    to_snake_case,
+    to_title_case,
+    to_train_case,
+    to_upper_case,
+)
+from click_extended.decorators.transform.to_date import to_date
+from click_extended.decorators.transform.to_datetime import to_datetime
+from click_extended.decorators.transform.to_path import to_path
+from click_extended.decorators.transform.to_time import to_time
+from click_extended.decorators.transform.to_timestamp import to_timestamp
+from click_extended.decorators.transform.truncate import truncate
+
+__all__ = [
+    "add_prefix",
+    "add_suffix",
+    "apply",
+    "basename",
+    "dirname",
+    "expand_vars",
+    "lstrip",
+    "remove_prefix",
+    "remove_suffix",
+    "replace",
+    "rstrip",
+    "slugify",
+    "split",
+    "strip",
+    "to_camel_case",
+    "to_dot_case",
+    "to_flat_case",
+    "to_kebab_case",
+    "to_lower_case",
+    "to_meme_case",
+    "to_pascal_case",
+    "to_path_case",
+    "to_screaming_snake_case",
+    "to_snake_case",
+    "to_title_case",
+    "to_train_case",
+    "to_upper_case",
+    "to_date",
+    "to_datetime",
+    "to_path",
+    "to_time",
+    "to_timestamp",
+    "truncate",
+]

click_extended/decorators/transform/add_prefix.py

@@ -0,0 +1,58 @@
+"""Child node to add a prefix to a string."""
+
+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 AddPrefix(ChildNode):
+    """Child node to add a prefix to a string."""
+
+    def handle_str(
+        self, value: str, context: Context, *args: Any, **kwargs: Any
+    ) -> Any:
+        prefix = kwargs["prefix"]
+        skip = kwargs["skip"]
+        case_sensitive = kwargs["case_sensitive"]
+
+        if skip:
+            if case_sensitive:
+                if value.startswith(prefix):
+                    return value
+            else:
+                if value.lower().startswith(prefix.lower()):
+                    return value
+
+        return prefix + value
+
+
+def add_prefix(
+    prefix: str,
+    skip: bool = True,
+    case_sensitive: bool = False,
+) -> Decorator:
+    """
+    Add a prefix to a string.
+
+    Type: `ChildNode`
+
+    Supports: `str`
+
+    Args:
+        prefix (str):
+            The prefix to add.
+        skip (bool, optional):
+            Skip adding the prefix if it already exists. Defaults to `True`.
+        case_sensitive (bool)
+            Check for exact case matching when `skip=True`. Defaults to `False`.
+    Returns:
+        Decorator:
+            The decorated function.
+    """
+    return AddPrefix.as_decorator(
+        prefix=prefix,
+        skip=skip,
+        case_sensitive=case_sensitive,
+    )

click_extended/decorators/transform/add_suffix.py

@@ -0,0 +1,58 @@
+"""Child node to add a suffix to a string."""
+
+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 AddSuffix(ChildNode):
+    """Child node to add a suffix to a string."""
+
+    def handle_str(
+        self, value: str, context: Context, *args: Any, **kwargs: Any
+    ) -> Any:
+        suffix = kwargs["suffix"]
+        skip = kwargs["skip"]
+        case_sensitive = kwargs["case_sensitive"]
+
+        if skip:
+            if case_sensitive:
+                if value.endswith(suffix):
+                    return value
+            else:
+                if value.lower().endswith(suffix.lower()):
+                    return value
+
+        return value + suffix
+
+
+def add_suffix(
+    suffix: str,
+    skip: bool = True,
+    case_sensitive: bool = False,
+) -> Decorator:
+    """
+    Add a suffix to a string.
+
+    Type: `ChildNode`
+
+    Supports: `str`
+
+    Args:
+        suffix (str):
+            The suffix to add.
+        skip (bool, optional):
+            Skip adding the suffix if it already exists. Defaults to `True`.
+        case_sensitive (bool)
+            Check for exact case matching when `skip=True`. Defaults to `False`.
+    Returns:
+        Decorator:
+            The decorated function.
+    """
+    return AddSuffix.as_decorator(
+        suffix=suffix,
+        skip=skip,
+        case_sensitive=case_sensitive,
+    )

click_extended/decorators/transform/apply.py

@@ -0,0 +1,35 @@
+"""Child decorator to apply an arbitrary function to any input."""
+
+from typing import Any, Callable
+
+from click_extended.core.nodes.child_node import ChildNode
+from click_extended.core.other.context import Context
+from click_extended.types import Decorator
+
+
+class Apply(ChildNode):
+    """Child decorator to apply an arbitrary function to any input."""
+
+    def handle_all(
+        self, value: Any, context: Context, *args: Any, **kwargs: Any
+    ) -> Any:
+        return kwargs["fn"](value)
+
+
+def apply(fn: Callable[[Any], Any]) -> Decorator:
+    """
+    A decorator to apply an arbitrary function to all input.
+
+    Type: `ChildNode`
+
+    Supports: `Any`
+
+    Args:
+        fn (Callable[[Any], Any]):
+            The function to apply.
+
+    Returns:
+        Decorator:
+            The decorated function.
+    """
+    return Apply.as_decorator(fn=fn)

click_extended/decorators/transform/basename.py

@@ -0,0 +1,44 @@
+"""Extract the base name from a path."""
+
+import os
+from pathlib import Path
+from typing import Any
+
+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 Basename(ChildNode):
+    """Extract the base name from a path."""
+
+    def handle_str(
+        self, value: str, context: Context, *args: Any, **kwargs: Any
+    ) -> str:
+        try:
+            return os.path.basename(value)
+        except ValueError as e:
+            raise click.BadParameter(str(e)) from e
+
+    def handle_path(
+        self, value: Path, context: Context, *args: Any, **kwargs: Any
+    ) -> str:
+        return value.name
+
+
+def basename() -> Decorator:
+    """
+    Extract the base name from a path.
+
+    Example:
+        >>> @basename()
+        ... @option("--path")
+        ... def cli(path):
+        ...     print(path)
+        ...
+        >>> cli(["--path", "/foo/bar/baz.txt"])
+        baz.txt
+    """
+    return Basename.as_decorator()

click_extended/decorators/transform/dirname.py

@@ -0,0 +1,44 @@
+"""Extract the directory name from a path."""
+
+import os
+from pathlib import Path
+from typing import Any
+
+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 Dirname(ChildNode):
+    """Extract the directory name from a path."""
+
+    def handle_str(
+        self, value: str, context: Context, *args: Any, **kwargs: Any
+    ) -> str:
+        try:
+            return os.path.dirname(value)
+        except ValueError as e:
+            raise click.BadParameter(str(e)) from e
+
+    def handle_path(
+        self, value: Path, context: Context, *args: Any, **kwargs: Any
+    ) -> Path:
+        return value.parent
+
+
+def dirname() -> Decorator:
+    """
+    Extract the directory name from a path.
+
+    Example:
+        >>> @dirname()
+        ... @option("--path")
+        ... def cli(path):
+        ...     print(path)
+        ...
+        >>> cli(["--path", "/foo/bar/baz.txt"])
+        /foo/bar
+    """
+    return Dirname.as_decorator()

click_extended/decorators/transform/expand_vars.py

@@ -0,0 +1,36 @@
+"""Expand environment variables in the string."""
+
+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 ExpandVars(ChildNode):
+    """Expand environment variables in the string."""
+
+    def handle_str(
+        self,
+        value: str,
+        context: Context,
+        *args: Any,
+        **kwargs: Any,
+    ) -> str:
+        return os.path.expandvars(value)
+
+
+def expand_vars() -> Decorator:
+    """
+    Expand environment variables in the string.
+
+    Type: `ChildNode`
+
+    Supports: `str`
+
+    Returns:
+        Decorator:
+            The decorated function.
+    """
+    return ExpandVars.as_decorator()

click_extended/decorators/transform/remove_prefix.py

@@ -0,0 +1,57 @@
+"""Child decorator to remove a prefix from a string."""
+
+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 RemovePrefix(ChildNode):
+    """Child decorator to remove a prefix from a string."""
+
+    def handle_str(
+        self, value: str, context: Context, *args: Any, **kwargs: Any
+    ) -> str:
+        prefix: str = kwargs["prefix"]
+
+        if value.startswith(prefix):
+            return value[len(prefix) :]
+
+        return value
+
+
+def remove_prefix(prefix: str) -> Decorator:
+    """
+    Remove a prefix from a string if it exists.
+
+    Type: `ChildNode`
+
+    Supports: `str`
+
+    Args:
+        prefix (str):
+            The prefix to remove from the beginning of the string.
+
+    Returns:
+        Decorator:
+            The decorator function.
+
+    Examples:
+        ```python
+        @command()
+        @option("name", default="Mr. John")
+        @remove_prefix("Mr. ")
+        def cmd(name: str) -> None:
+            click.echo(f"Name: {name}")  # Output: Name: John
+        ```
+
+        ```python
+        @command()
+        @option("url", default="https://example.com")
+        @remove_prefix("https://")
+        def cmd(url: str) -> None:
+            click.echo(f"Domain: {url}")  # Output: Domain: example.com
+        ```
+    """
+    return RemovePrefix.as_decorator(prefix=prefix)

click_extended/decorators/transform/remove_suffix.py

@@ -0,0 +1,57 @@
+"""Child decorator to remove a suffix from a string."""
+
+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 RemoveSuffix(ChildNode):
+    """Child decorator to remove a suffix from a string."""
+
+    def handle_str(
+        self, value: str, context: Context, *args: Any, **kwargs: Any
+    ) -> str:
+        suffix: str = kwargs["suffix"]
+
+        if value.endswith(suffix):
+            return value[: -len(suffix)]
+
+        return value
+
+
+def remove_suffix(suffix: str) -> Decorator:
+    """
+    Remove a suffix from a string if it exists.
+
+    Type: `ChildNode`
+
+    Supports: `str`
+
+    Args:
+        suffix (str):
+            The suffix to remove from the end of the string.
+
+    Returns:
+        Decorator:
+            The decorator function.
+
+    Examples:
+        ```python
+        @command()
+        @option("filename", default="document.txt")
+        @remove_suffix(".txt")
+        def cmd(filename: str) -> None:
+            click.echo(f"Name: {filename}")  # Output: Name: document
+        ```
+
+        ```python
+        @command()
+        @option("url", default="example.com/")
+        @remove_suffix("/")
+        def cmd(url: str) -> None:
+            click.echo(f"URL: {url}")  # Output: URL: example.com
+        ```
+    """
+    return RemoveSuffix.as_decorator(suffix=suffix)

click_extended/decorators/transform/replace.py

@@ -0,0 +1,46 @@
+"""Replace occurrences of a substring with another."""
+
+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 Replace(ChildNode):
+    """Replace occurrences of a substring with another."""
+
+    def handle_str(
+        self,
+        value: str,
+        context: Context,
+        *args: Any,
+        **kwargs: Any,
+    ) -> str:
+        old = kwargs["old"]
+        new = kwargs["new"]
+        count = kwargs.get("count", -1)
+        return value.replace(old, new, count)
+
+
+def replace(old: str, new: str, count: int = -1) -> Decorator:
+    """
+    Replace occurrences of a substring with another.
+
+    Type: `ChildNode`
+
+    Supports: `str`
+
+    Args:
+        old (str):
+            The substring to replace.
+        new (str):
+            The replacement substring.
+        count (int):
+            Maximum number of occurrences to replace. Defaults to `-1` (all).
+
+    Returns:
+        Decorator:
+            The decorated function.
+    """
+    return Replace.as_decorator(old=old, new=new, count=count)

click_extended/decorators/transform/slugify.py

@@ -0,0 +1,45 @@
+"""Convert the string to a slug."""
+
+from typing import Any
+
+from slugify import slugify as _slugify
+
+from click_extended.core.nodes.child_node import ChildNode
+from click_extended.core.other.context import Context
+from click_extended.types import Decorator
+
+
+class Slugify(ChildNode):
+    """Convert the string to a slug."""
+
+    def handle_str(
+        self,
+        value: str,
+        context: Context,
+        *args: Any,
+        **kwargs: Any,
+    ) -> str:
+        return _slugify(value, **kwargs)
+
+
+def slugify(**kwargs: Any) -> Decorator:
+    """
+    Convert the string to a slug.
+
+    This decorator uses the `python-slugify` library under the hood.
+
+    Read more about the library here: https://pypi.org/project/python-slugify/
+
+    Type: `ChildNode`
+
+    Supports: `str`
+
+    Args:
+        **kwargs (Any):
+            Additional keyword arguments passed to `slugify.slugify`.
+
+    Returns:
+        Decorator:
+            The decorated function.
+    """
+    return Slugify.as_decorator(**kwargs)