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

click_extended/decorators/transform/to_path.py

@@ -0,0 +1,274 @@
+"""Convert a string to a `pathlib.Path` object."""
+
+# pylint: disable=too-many-locals
+# pylint: disable=too-many-branches
+# pylint: disable=too-many-statements
+# pylint: disable=too-many-arguments
+
+import fnmatch
+import os
+from pathlib import Path
+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 ToPath(ChildNode):
+    """Convert a string to a `pathlib.Path` object."""
+
+    def handle_str(
+        self, value: str, context: Context, *args: Any, **kwargs: Any
+    ) -> Path:
+        parent = context.get_current_parent_as_parent()
+        name = parent.name
+        exists = kwargs["exists"]
+        parents = kwargs["parents"]
+        extensions = kwargs["extensions"]
+        include_pattern = kwargs["include_pattern"]
+        exclude_pattern = kwargs["exclude_pattern"]
+        allow_file = kwargs["allow_file"]
+        allow_directory = kwargs["allow_directory"]
+        allow_empty_directory = kwargs["allow_empty_directory"]
+        allow_empty_file = kwargs["allow_empty_file"]
+        allow_symlink = kwargs["allow_symlink"]
+        follow_symlink = kwargs["follow_symlink"]
+        resolve = kwargs["resolve"]
+        is_readable = kwargs["is_readable"]
+        is_writable = kwargs["is_writable"]
+        is_executable = kwargs["is_executable"]
+
+        path = Path(value) if isinstance(value, str) else value
+        path = path.expanduser()
+
+        # Symlinks
+        if not allow_symlink and path.is_symlink():
+            raise OSError(
+                f"Path '{path}' is a symlink, but symlinks are not allowed "
+                f"for '{name}'"
+            )
+
+        if resolve:
+            path = path.resolve() if follow_symlink else path.absolute()
+        elif follow_symlink and path.is_symlink():
+            path = path.resolve()
+        else:
+            path = path.absolute()
+
+        # Existence
+        if exists and not path.exists():
+            raise FileNotFoundError(f"Path '{path}' does not exist.")
+
+        # Parents
+        if parents and not path.parent.exists():
+            path.parent.mkdir(parents=True, exist_ok=True)
+
+        if path.exists():
+            is_file = path.is_file()
+            is_dir = path.is_dir()
+
+            # File disallowed
+            if is_file and not allow_file:
+                raise IsADirectoryError(
+                    f"Path '{path}' is a file, but files are not allowed "
+                    f"for '{name}'"
+                )
+
+            # Directory disallowed
+            if is_dir and not allow_directory:
+                raise NotADirectoryError(
+                    f"Path '{path}' is a directory, but directories are not "
+                    f"allowed for '{name}'"
+                )
+
+            # Check empty directory
+            if is_dir and not allow_empty_directory:
+                if not any(path.iterdir()):
+                    raise ValueError(
+                        f"Directory '{path}' is empty, but empty directories "
+                        f"are not allowed for '{name}'"
+                    )
+
+            # Check empty file
+            if is_file and not allow_empty_file:
+                if path.stat().st_size == 0:
+                    raise ValueError(
+                        f"File '{path}' is empty, but empty files are not "
+                        f"allowed for '{name}'"
+                    )
+
+            # Check permissions
+            if is_readable and not os.access(path, os.R_OK):
+                raise PermissionError(
+                    f"Path '{path}' is not readable for '{name}'"
+                )
+
+            if is_writable and not os.access(path, os.W_OK):
+                raise PermissionError(
+                    f"Path '{path}' is not writable for '{name}'"
+                )
+
+            if is_executable and not os.access(path, os.X_OK):
+                raise PermissionError(
+                    f"Path '{path}' is not executable for '{name}'"
+                )
+
+        # Check extensions
+        if extensions and (not path.exists() or path.is_file()):
+            extensions = [
+                ext if ext.startswith(".") else f".{ext}" for ext in extensions
+            ]
+
+            if not any(path.name.endswith(ext) for ext in extensions):
+                raise ValueError(
+                    f"Path '{path}' does not have an allowed extension. "
+                    f"Allowed extensions: {', '.join(extensions)} "
+                    f"for '{name}'"
+                )
+
+        # Patterns
+        if include_pattern:
+            if not fnmatch.fnmatch(path.name, include_pattern):
+                raise ValueError(
+                    f"Path '{path}' does not match include pattern "
+                    f"'{include_pattern}' for '{name}'"
+                )
+        elif exclude_pattern and fnmatch.fnmatch(path.name, exclude_pattern):
+            raise ValueError(
+                f"Path '{path}' matches exclude pattern "
+                f"'{exclude_pattern}' for '{name}'"
+            )
+
+        return path
+
+
+def to_path(
+    *,
+    exists: bool = True,
+    parents: bool = False,
+    resolve: bool = True,
+    extensions: list[str] | None = None,
+    include_pattern: str | None = None,
+    exclude_pattern: str | None = None,
+    allow_file: bool = True,
+    allow_directory: bool = True,
+    allow_empty_directory: bool = True,
+    allow_empty_file: bool = True,
+    allow_symlink: bool = False,
+    follow_symlink: bool = True,
+    is_readable: bool = False,
+    is_writable: bool = False,
+    is_executable: bool = False,
+) -> Decorator:
+    """
+    Convert, validate, and process a string to a `pathlib.Path` object.
+
+    Type: `ChildNode`
+
+    Supports: `str`
+
+    Args:
+        exists (bool, optional):
+            Whether the path needs to exist.
+            Defaults to `True`.
+
+        parents (bool, optional):
+            Create parent directories if they don't exist.
+            Defaults to `False`.
+
+        resolve (bool, optional):
+            Convert the path to an absolute path. When `True`, resolves
+            `.` and `..` components. When False, only makes the path
+            absolute without resolution.
+            Defaults to `True`.
+
+        extensions (list[str], optional):
+            A list of extensions to require the path to end with.
+            By default, all extensions are allowed.
+
+        include_pattern (str, optional):
+            A whitelist pattern. Uses shell-style glob patterns.
+            Defaults to `None` (All file names allowed).
+
+            When both `include_pattern` and `exclude_pattern` are provided,
+            `include_pattern` takes precedence (files matching include
+            are always accepted).
+
+            ```python
+            include_pattern="*.py"      # Only Python files
+            include_pattern="config_*"  # Files starting with "config_"
+            ```
+
+        exclude_pattern (str, optional):
+            A blacklist pattern. Uses shell-style glob patterns.
+            Defaults to `None` (No file names excluded).
+
+            If provided without `include_pattern`, file names matching this
+            pattern will be rejected, and all other file names will be
+            allowed.
+
+            When both `include_pattern` and `exclude_pattern` are provided,
+            `include_pattern` takes precedence (files matching include
+            are always accepted).
+
+        allow_file (bool, optional):
+            Whether to allow the path to be a file or not.
+            Defaults to `True`.
+
+        allow_directory (bool, optional):
+            Whether to allow the path to be a directory or not.
+            Defaults to `True`.
+
+        allow_empty_directory (bool, optional):
+            If the path points to a directory, whether to allow
+            the directory to be empty. Only checked when the path
+            is a directory. Defaults to `True`.
+
+        allow_empty_file (bool, optional):
+            If the path points to a file, whether to allow the
+            file to be empty. Only checked when the path is a file.
+            Defaults to `True`.
+
+        allow_symlink (bool, optional):
+            Whether to allow the path to be a symlink or not.
+            Defaults to `False`.
+
+        follow_symlink (bool, optional):
+            Whether to follow symlinks when resolving the path.
+            Only applies when resolve=True.
+            Defaults to `True`.
+
+        is_readable (bool, optional):
+            Whether the file has `read` permissions.
+            Defaults to `False`.
+
+        is_writable (bool, optional):
+            Whether the file has `write` permissions.
+            Default to `False`.
+
+        is_executable (bool, optional):
+            A unix-only feature that checks if the file has
+            `execute` permissions. Defaults to `False`.
+
+    Returns:
+        Decorator:
+            The decorated function.
+    """
+    return ToPath.as_decorator(
+        exists=exists,
+        parents=parents,
+        resolve=resolve,
+        extensions=extensions,
+        include_pattern=include_pattern,
+        exclude_pattern=exclude_pattern,
+        allow_file=allow_file,
+        allow_directory=allow_directory,
+        allow_empty_directory=allow_empty_directory,
+        allow_empty_file=allow_empty_file,
+        allow_symlink=allow_symlink,
+        follow_symlink=follow_symlink,
+        is_readable=is_readable,
+        is_writable=is_writable,
+        is_executable=is_executable,
+    )

click_extended/decorators/transform/to_time.py

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

click_extended/decorators/transform/to_timestamp.py

@@ -0,0 +1,114 @@
+"""Convert datetime, date, or time objects to Unix timestamps."""
+
+from datetime import date, datetime, time, timezone
+from typing import Any, Literal
+
+from click_extended.core.nodes.child_node import ChildNode
+from click_extended.core.other.context import Context
+from click_extended.types import Decorator
+
+
+class ToTimestamp(ChildNode):
+    """Convert datetime, date, or time objects to Unix timestamps."""
+
+    def handle_datetime(
+        self, value: datetime, context: Context, *args: Any, **kwargs: Any
+    ) -> int:
+        unit = kwargs["unit"]
+
+        if value.date() == date(1900, 1, 1):
+            today = datetime.now(timezone.utc).date()
+            value = datetime.combine(today, value.time())
+            if value.tzinfo is None:
+                value = value.replace(tzinfo=timezone.utc)
+        elif value.tzinfo is None:
+            value = value.replace(tzinfo=timezone.utc)
+
+        timestamp = value.timestamp()
+
+        if unit == "s":
+            return int(timestamp)
+
+        if unit == "ms":
+            return int(timestamp * 1000)
+
+        if unit == "us":
+            return int(timestamp * 1_000_000)
+
+        return int(timestamp * 1_000_000_000)
+
+    def handle_date(
+        self, value: date, context: Context, *args: Any, **kwargs: Any
+    ) -> int:
+        dt = datetime.combine(value, datetime.min.time(), tzinfo=timezone.utc)
+        return self.handle_datetime(dt, context, *args, **kwargs)
+
+    def handle_time(
+        self, value: time, context: Context, *args: Any, **kwargs: Any
+    ) -> int:
+        today = datetime.now(timezone.utc).date()
+
+        if value.tzinfo is None:
+            value = value.replace(tzinfo=timezone.utc)
+
+        dt = datetime.combine(today, value)
+        return self.handle_datetime(dt, context, *args, **kwargs)
+
+
+def to_timestamp(unit: Literal["s", "ms", "us", "ns"] = "s") -> Decorator:
+    """
+    Convert datetime, date, or time objects to Unix timestamps.
+
+    Type: `ChildNode`
+
+    Supports: `datetime`, `date`, `time`
+
+    Args:
+        unit (Literal["s", "ms", "us", "ns"], optional):
+            The unit of the timestamp:
+            - `"s"`: Seconds (standard Unix timestamp)
+            - `"ms"`: Milliseconds (JavaScript/Java style)
+            - `"us"`: Microseconds (Python datetime precision)
+            - `"ns"`: Nanoseconds (high-precision logging)
+            Defaults to `"s"`.
+
+    Returns:
+        Decorator:
+            The decorated function.
+
+    Examples:
+        Basic usage with datetime:
+
+        ```python
+        @command()
+        @option("dt", default=None)
+        @to_datetime()
+        @to_timestamp()
+        def cmd(dt: int) -> None:
+            click.echo(f"Timestamp: {dt}")
+        ```
+
+        With milliseconds for JavaScript:
+
+        ```python
+        @command()
+        @option("dt", default=None)
+        @to_datetime()
+        @to_timestamp("ms")
+        def cmd(dt: int) -> None:
+            click.echo(f"Milliseconds: {dt}")
+        ```
+
+        Multiple timestamps:
+
+        ```python
+        @command()
+        @option("dates", default=None, nargs=3)
+        @to_date()
+        @to_timestamp()
+        def cmd(dates: tuple[int, ...]) -> None:
+            for ts in dates:
+                click.echo(f"Timestamp: {ts}")
+        ```
+    """
+    return ToTimestamp.as_decorator(unit=unit)

click_extended/decorators/transform/truncate.py

@@ -0,0 +1,47 @@
+"""Truncate the string to a specific length."""
+
+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 Truncate(ChildNode):
+    """Truncate the string to a specific length."""
+
+    def handle_str(
+        self,
+        value: str,
+        context: Context,
+        *args: Any,
+        **kwargs: Any,
+    ) -> Any:
+        length = kwargs["length"]
+        suffix = kwargs["suffix"]
+
+        if len(value) <= length:
+            return value
+
+        return value[: length - len(suffix)] + suffix
+
+
+def truncate(length: int, suffix: str = "...") -> Decorator:
+    """
+    Truncate the string to a specific length.
+
+    Type: `ChildNode`
+
+    Supports: `str`
+
+    Args:
+        length (int):
+            The maximum length of the string.
+        suffix (str):
+            The suffix to append when truncated. Defaults to `...`.
+
+    Returns:
+        Decorator:
+            The decorated function.
+    """
+    return Truncate.as_decorator(length=length, suffix=suffix)

click_extended/types.py

@@ -2,7 +2,7 @@
 
 from typing import Any, Callable
 
-from click_extended.core.context import Context
+from click_extended.core.other.context import Context
 
 Decorator = Callable[[Callable[..., Any]], Callable[..., Any]]
 

click_extended/utils/__init__.py

@@ -0,0 +1,13 @@
+"""Initialization file for the 'click_extended.utils' module."""
+
+from click_extended.utils.casing import Casing
+from click_extended.utils.checks import is_argument, is_option, is_tag
+from click_extended.utils.humanize import humanize_iterable
+
+__all__ = [
+    "Casing",
+    "is_argument",
+    "is_option",
+    "is_tag",
+    "humanize_iterable",
+]