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

click_extended/decorators/transform/split.py

@@ -0,0 +1,43 @@
+"""Split the string by a separator."""
+
+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 Split(ChildNode):
+    """Split the string by a separator."""
+
+    def handle_str(
+        self,
+        value: str,
+        context: Context,
+        *args: Any,
+        **kwargs: Any,
+    ) -> list[str]:
+        sep = kwargs.get("sep")
+        maxsplit = kwargs.get("maxsplit", -1)
+        return value.split(sep, maxsplit)
+
+
+def split(sep: str | None = None, maxsplit: int = -1) -> Decorator:
+    """
+    Split the string by a separator.
+
+    Type: `ChildNode`
+
+    Supports: `str`
+
+    Args:
+        sep (str | None):
+            The delimiter string. If None, split by whitespace.
+        maxsplit (int):
+            Maximum number of splits. Defaults to `-1` (no limit).
+
+    Returns:
+        Decorator:
+            The decorated function.
+    """
+    return Split.as_decorator(sep=sep, maxsplit=maxsplit)

click_extended/decorators/transform/strip.py

@@ -0,0 +1,148 @@
+"""Child decorators to strip characters from strings."""
+
+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 Strip(ChildNode):
+    """Child decorator to strip characters from both ends of a string."""
+
+    def handle_str(
+        self, value: str, context: Context, *args: Any, **kwargs: Any
+    ) -> str:
+        chars: str | None = kwargs.get("chars")
+        return value.strip(chars)
+
+
+class LStrip(ChildNode):
+    """Child decorator to strip characters from the left end of a string."""
+
+    def handle_str(
+        self, value: str, context: Context, *args: Any, **kwargs: Any
+    ) -> str:
+        chars: str | None = kwargs.get("chars")
+        return value.lstrip(chars)
+
+
+class RStrip(ChildNode):
+    """Child decorator to strip characters from the right end of a string."""
+
+    def handle_str(
+        self, value: str, context: Context, *args: Any, **kwargs: Any
+    ) -> str:
+        chars: str | None = kwargs.get("chars")
+        return value.rstrip(chars)
+
+
+def strip(chars: str | None = None) -> Decorator:
+    """
+    Remove leading and trailing characters from a string.
+
+    Type: `ChildNode`
+
+    Supports: `str`
+
+    Args:
+        chars (str | None, optional):
+            A string specifying the set of characters to be removed.
+            If `None` (default), whitespace characters are removed.
+
+    Returns:
+        Decorator:
+            The decorator function.
+
+    Examples:
+        ```python
+        @command()
+        @option("name", default="  hello  ")
+        @strip()
+        def cmd(name: str) -> None:
+            click.echo(f"Name: '{name}'")  # Output: Name: 'hello'
+        ```
+
+        ```python
+        @command()
+        @option("path", default="///path///")
+        @strip("/")
+        def cmd(path: str) -> None:
+            click.echo(f"Path: '{path}'")  # Output: Path: 'path'
+        ```
+    """
+    return Strip.as_decorator(chars=chars)
+
+
+def lstrip(chars: str | None = None) -> Decorator:
+    """
+    Remove leading (left) characters from a string.
+
+    Type: `ChildNode`
+
+    Supports: `str`
+
+    Args:
+        chars (str | None, optional):
+            A string specifying the set of characters to be removed.
+            If `None` (default), whitespace characters are removed.
+
+    Returns:
+        Decorator:
+            The decorator function.
+
+    Examples:
+        ```python
+        @command()
+        @option("name", default="  hello  ")
+        @lstrip()
+        def cmd(name: str) -> None:
+            click.echo(f"Name: '{name}'")  # Output: Name: 'hello  '
+        ```
+
+        ```python
+        @command()
+        @option("path", default="///path///")
+        @lstrip("/")
+        def cmd(path: str) -> None:
+            click.echo(f"Path: '{path}'")  # Output: Path: 'path///'
+        ```
+    """
+    return LStrip.as_decorator(chars=chars)
+
+
+def rstrip(chars: str | None = None) -> Decorator:
+    """
+    Remove trailing (right) characters from a string.
+
+    Type: `ChildNode`
+
+    Supports: `str`
+
+    Args:
+        chars (str | None, optional):
+            A string specifying the set of characters to be removed.
+            If `None` (default), whitespace characters are removed.
+
+    Returns:
+        Decorator:
+            The decorator function.
+
+    Examples:
+        ```python
+        @command()
+        @option("name", default="  hello  ")
+        @rstrip()
+        def cmd(name: str) -> None:
+            click.echo(f"Name: '{name}'")  # Output: Name: '  hello'
+        ```
+
+        ```python
+        @command()
+        @option("path", default="///path///")
+        @rstrip("/")
+        def cmd(path: str) -> None:
+            click.echo(f"Path: '{path}'")  # Output: Path: '///path'
+        ```
+    """
+    return RStrip.as_decorator(chars=chars)

click_extended/decorators/transform/to_case.py

@@ -0,0 +1,216 @@
+"""Child node to convert a string to one of many formats."""
+
+from typing import Any, cast
+
+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.casing import Casing
+
+
+class ToCase(ChildNode):
+    """Child node to convert a string to one of many formats."""
+
+    def handle_str(
+        self,
+        value: str,
+        context: Context,
+        *args: Any,
+        **kwargs: Any,
+    ) -> str:
+        return cast(str, getattr(Casing, kwargs["method"])(str(value)))
+
+
+def to_lower_case() -> Decorator:
+    """
+    Convert a string to `lower case`.
+
+    Type: `ChildNode`
+
+    Supports: `str`
+
+    Returns:
+        Decorator:
+            The decorator function.
+    """
+    return ToCase.as_decorator(method="to_lower_case")
+
+
+def to_upper_case() -> Decorator:
+    """
+    Convert a string to `UPPER CASE`.
+
+    Type: `ChildNode`
+
+    Supports: `str`
+
+    Returns:
+        Decorator:
+            The decorator function.
+    """
+    return ToCase.as_decorator(method="to_upper_case")
+
+
+def to_meme_case() -> Decorator:
+    """
+    Convert a string to `mEmE cAsE`.
+
+    Type: `ChildNode`
+
+    Supports: `str`
+
+    Returns:
+        Decorator:
+            The decorator function.
+    """
+    return ToCase.as_decorator(method="to_meme_case")
+
+
+def to_snake_case() -> Decorator:
+    """
+    Convert a string to `snake_case`.
+
+    Type: `ChildNode`
+
+    Supports: `str`
+
+    Returns:
+        Decorator:
+            The decorator function.
+    """
+    return ToCase.as_decorator(method="to_snake_case")
+
+
+def to_screaming_snake_case() -> Decorator:
+    """
+    Convert a string to `SCREAMING_SNAKE_CASE`.
+
+    Type: `ChildNode`
+
+    Supports: `str`
+
+    Returns:
+        Decorator:
+            The decorator function.
+    """
+    return ToCase.as_decorator(method="to_screaming_snake_case")
+
+
+def to_camel_case() -> Decorator:
+    """
+    Convert a string to `camelCase`.
+
+    Type: `ChildNode`
+
+    Supports: `str`
+
+    Returns:
+        Decorator:
+            The decorator function.
+    """
+    return ToCase.as_decorator(method="to_camel_case")
+
+
+def to_pascal_case() -> Decorator:
+    """
+    Convert a string to `PascalCase`.
+
+    Type: `ChildNode`
+
+    Supports: `str`
+
+    Returns:
+        Decorator:
+            The decorator function.
+    """
+    return ToCase.as_decorator(method="to_pascal_case")
+
+
+def to_kebab_case() -> Decorator:
+    """
+    Convert a string to `kebab-case`.
+
+    Type: `ChildNode`
+
+    Supports: `str`
+
+    Returns:
+        Decorator:
+            The decorator function.
+    """
+    return ToCase.as_decorator(method="to_kebab_case")
+
+
+def to_train_case() -> Decorator:
+    """
+    Convert a string to `Train-Case`.
+
+    Type: `ChildNode`
+
+    Supports: `str`
+
+    Returns:
+        Decorator:
+            The decorator function.
+    """
+    return ToCase.as_decorator(method="to_train_case")
+
+
+def to_flat_case() -> Decorator:
+    """
+    Convert a string to `flatcase`.
+
+    Type: `ChildNode`
+
+    Supports: `str`
+
+    Returns:
+        Decorator:
+            The decorator function.
+    """
+    return ToCase.as_decorator(method="to_flat_case")
+
+
+def to_dot_case() -> Decorator:
+    """
+    Convert a string to `dot.case`.
+
+    Type: `ChildNode`
+
+    Supports: `str`
+
+    Returns:
+        Decorator:
+            The decorator function.
+    """
+    return ToCase.as_decorator(method="to_dot_case")
+
+
+def to_title_case() -> Decorator:
+    """
+    Convert a string to `Title Case`.
+
+    Type: `ChildNode`
+
+    Supports: `str`
+
+    Returns:
+        Decorator:
+            The decorator function.
+    """
+    return ToCase.as_decorator(method="to_title_case")
+
+
+def to_path_case() -> Decorator:
+    """
+    Convert a string to `path/case`.
+
+    Type: `ChildNode`
+
+    Supports: `str`
+
+    Returns:
+        Decorator:
+            The decorator function.
+    """
+    return ToCase.as_decorator(method="to_path_case")

click_extended/decorators/transform/to_date.py

@@ -0,0 +1,75 @@
+"""Child decorator to convert a string to a date."""
+
+from datetime import date, datetime
+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 import humanize_iterable
+from click_extended.utils.time import normalize_datetime_format
+
+
+class ToDate(ChildNode):
+    """Child decorator to convert a string to a date."""
+
+    def handle_str(
+        self,
+        value: str,
+        context: Context,
+        *args: Any,
+        **kwargs: Any,
+    ) -> date:
+        formats = kwargs["formats"] or (
+            "%Y-%m-%d",
+            "%d/%m/%Y",
+            "%m/%d/%Y",
+        )
+
+        for fmt in formats:
+            try:
+                normalized_fmt = normalize_datetime_format(fmt)
+                dt = datetime.strptime(value, normalized_fmt)
+                return dt.date()
+            except ValueError:
+                continue
+
+        fmt_text = (
+            "either of the formats" if len(formats) != 1 else "in the format"
+        )
+        raise ValueError(
+            f"Invalid date '{value}', must be in "
+            f"{fmt_text} {humanize_iterable(formats, sep='or')}"
+        )
+
+
+def to_date(
+    *formats: str,
+) -> Decorator:
+    """
+    Convert a string to a date by trying multiple formats.
+
+    Type: `ChildNode`
+
+    Supports: `str`
+
+    Args:
+        *formats (str):
+            One or more date format strings to try. Supports both Python
+            strptime format (e.g., "%Y-%m-%d", "%d/%m/%Y") and simplified format
+            (e.g., "YYYY-MM-DD", "DD/MM/YYYY"). The decorator will attempt each
+            format in order until one succeeds. Defaults to `"%Y-%m-%d"`,
+            `"%d/%m/%Y"`, and `"%m/%d/%Y"`.
+
+    Returns:
+        Decorator:
+            The decorated function.
+
+    Example:
+        @to_date("YYYY-MM-DD", "DD/MM/YYYY")
+        # Or using Python strptime format:
+        @to_date("%Y-%m-%d", "%d/%m/%Y")
+        def process_date(date_val: date):
+            print(date_val)
+    """
+    return ToDate.as_decorator(formats=formats)

click_extended/decorators/transform/to_datetime.py

@@ -0,0 +1,83 @@
+"""Child decorator to convert a string to a datetime."""
+
+from datetime import datetime
+from typing import Any
+from zoneinfo import ZoneInfo
+
+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 humanize_iterable
+from click_extended.utils.time import normalize_datetime_format
+
+
+class ToDatetime(ChildNode):
+    """Child decorator to convert a string to a datetime."""
+
+    def handle_str(
+        self,
+        value: str,
+        context: Context,
+        *args: Any,
+        **kwargs: Any,
+    ) -> datetime:
+        formats = kwargs["formats"] or (
+            "%Y-%m-%d",
+            "%H:%M:%S",
+            "%Y-%m-%d %H:%M:%S",
+        )
+        tz = kwargs.get("tz")
+
+        for fmt in formats:
+            try:
+                normalized_fmt = normalize_datetime_format(fmt)
+                dt = datetime.strptime(value, normalized_fmt)
+                if tz:
+                    dt = dt.replace(tzinfo=ZoneInfo(tz))
+                return dt
+            except ValueError:
+                continue
+
+        fmt = "either of the formats" if len(formats) != 1 else "in the format"
+        raise ValueError(
+            f"Invalid datetime '{value}', must be in "
+            f"{fmt} {humanize_iterable(formats, sep='or')}"
+        )
+
+
+def to_datetime(
+    *formats: str,
+    tz: str | None = None,
+) -> Decorator:
+    """
+    Convert a string to a datetime by trying multiple formats.
+
+    Type: `ChildNode`
+
+    Supports: `str`
+
+    Args:
+        *formats (str):
+            One or more datetime format strings to try. Supports both Python
+            strptime format (e.g., "%Y-%m-%d", "%d/%m/%Y") and simplified format
+            (e.g., "YYYY-MM-DD", "DD/MM/YYYY"). The decorator will attempt each
+            format in order until one succeeds. Defaults to `"%Y-%m-%d"`,
+            `"%H:%M:%S"` and `"%Y-%m-%d %H:%M:%S"`,
+
+        tz (str | None, optional):
+            Timezone name (e.g., "UTC", "America/New_York", "Europe/Stockholm")
+            to apply to the parsed datetime. Uses zoneinfo.ZoneInfo for timezone
+            handling. Defaults to `None` (naive datetime).
+
+    Returns:
+        Decorator:
+            The decorated function.
+
+    Example:
+        @to_datetime("YYYY-MM-DD", "DD/MM/YYYY", tz="America/New_York")
+        # Or using Python strptime format:
+        @to_datetime("%Y-%m-%d", "%d/%m/%Y", tz="America/New_York")
+        def process_date(date: datetime):
+            print(date)
+    """
+    return ToDatetime.as_decorator(formats=formats, tz=tz)