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

click_extended/utils/format.py

@@ -0,0 +1,101 @@
+"""Format utility functions."""
+
+from typing import Any
+
+
+def format_list(
+    value: list[Any],
+    prefix_singular: str | None = None,
+    prefix_plural: str | None = None,
+    wrap: str | tuple[str, str] | None = None,
+) -> str:
+    """
+    Format a list of primitives to a human-readable format.
+
+    - **Single item**: "x" or "Prefix Singular: x"
+    - **Two items**: "x and y" or "Prefix Plural: x and y"
+    - **Three+ items**: "x, y and z" or "Prefix Plural: x, y and z"
+
+    Args:
+        value (list[Any]):
+            The list of primitives to format. All items must be
+            primitives (str, int, float, bool).
+        prefix_singular (str, optional):
+            A prefix to use if the list only contains a single element.
+            If this parameter is set, `prefix_plural` must also be set.
+        prefix_plural (str, optional):
+            A prefix to use if the list contains zero or multiple elements.
+            If this parameter is set, `prefix_singular` must also be set.
+        wrap (str | tuple[str, str], optional):
+            A string to wrap each element with (applied to both sides),
+            or a tuple of (left, right) strings for asymmetric wrapping.
+    Returns:
+        str:
+            The formatted string.
+
+    Raises:
+        ValueError:
+            If only one prefix is provided or if the list is empty.
+        TypeError:
+            If a value in the list is not a primitive.
+
+    Examples:
+        >>> format_list(["str"])
+        str
+        >>> format_list(["str", "int"])
+        str and int
+        >>> format_list(["str", "int", "float"])
+        str, int and float
+        >>> format_list(
+        >>>     ["str"],
+        >>>     prefix_singular="Type: ",
+        >>>     prefix_plural="Types: ",
+        >>> )
+        Type: str
+        >>> format_list(
+        >>>     ["str", "int"],
+        >>>     prefix_singular="Type: ",
+        >>>     prefix_plural="Types: ",
+        >>> )
+        Types: str and int
+        >>> format_list(["Alice", "Bob", "Charlie"], wrap="'")
+        'Alice', 'Bob' and 'Charlie'
+        >>> format_list(["str", "int"], wrap=("<", ">"))
+        <str> and <int>
+    """
+    if (prefix_singular is None) != (prefix_plural is None):
+        raise ValueError(
+            "Both prefix_singular and prefix_plural must be provided together, "
+            "or neither should be provided."
+        )
+
+    if not value:
+        raise ValueError("Cannot format an empty list.")
+
+    for item in value:
+        if not isinstance(item, (str, int, float, bool)):
+            raise TypeError(
+                f"All items must be primitives (str, int, float, bool). "
+                f"Got {type(item).__name__}: {item!r}"
+            )
+
+    str_items = [str(item) for item in value]
+
+    if wrap is not None:
+        if isinstance(wrap, tuple):
+            left, right = wrap
+            str_items = [f"{left}{item}{right}" for item in str_items]
+        else:
+            str_items = [f"{wrap}{item}{wrap}" for item in str_items]
+
+    if len(str_items) == 1:
+        formatted = str_items[0]
+        prefix = prefix_singular if prefix_singular is not None else ""
+    elif len(str_items) == 2:
+        formatted = f"{str_items[0]} and {str_items[1]}"
+        prefix = prefix_plural if prefix_plural is not None else ""
+    else:
+        formatted = ", ".join(str_items[:-1]) + f" and {str_items[-1]}"
+        prefix = prefix_plural if prefix_plural is not None else ""
+
+    return prefix + formatted

click_extended/utils/humanize.py

@@ -0,0 +1,209 @@
+"""Format utility functions."""
+
+# pylint: disable=too-many-return-statements
+# pylint: disable=too-many-arguments
+# pylint: disable=too-many-positional-arguments
+
+from types import UnionType
+from typing import Any, Iterable, cast, get_args, get_origin
+
+
+def humanize_iterable(
+    value: Iterable[str | int | float | bool],
+    prefix_singular: str | None = None,
+    prefix_plural: str | None = None,
+    suffix_singular: str | None = None,
+    suffix_plural: str | None = None,
+    wrap: str | tuple[str, str] | None = None,
+    sep: str = "and",
+) -> str:
+    """
+    Format an iterable of primitives to a human-readable format.
+
+    - **Single item**: "x"
+    - **Two items**: "x and y"
+    - **Three+ items**: "x, y and z"
+
+    Args:
+        value (Iterable[str | int | float | bool]):
+            The iterable of primitives to format. All items must be
+            primitives (str, int, float, bool).
+        prefix_singular (str, optional):
+            A prefix to use if the list only contains a single element.
+            If this parameter is set, `prefix_plural` must also be set.
+        prefix_plural (str, optional):
+            A prefix to use if the list contains zero or multiple elements.
+            If this parameter is set, `prefix_singular` must also be set.
+        suffix_singular (str, optional):
+            A suffix to use if the list only contains a single element.
+            If this parameter is set, `suffix_plural` must also be set.
+        suffix_plural (str, optional):
+            A suffix to use if the list contains zero or multiple elements.
+            If this parameter is set, `prefix_singular` must also be set.
+        wrap (str | tuple[str, str], optional):
+            A string to wrap each element with (applied to both sides),
+            or a tuple of (left, right) strings for asymmetric wrapping.
+        sep (str, optional):
+            The sep when the length is greater than 2 (X, Y <sep> Z).
+    Returns:
+        str:
+            The formatted string.
+
+    Raises:
+        ValueError:
+            If only one prefix is provided or if the list is empty.
+        TypeError:
+            If a value in the list is not a primitive.
+
+    Examples:
+        >>> humanize_iterable(["str"])
+        str
+        >>> humanize_iterable(["str", "int"])
+        str and int
+        >>> humanize_iterable(["str", "int", "float"])
+        str, int and float
+        >>> humanize_iterable(
+        >>>     ["str"],
+        >>>     prefix_singular="Type: ",
+        >>>     prefix_plural="Types: ",
+        >>> )
+        Type: str
+        >>> humanize_iterable(
+        >>>     ["str", "int"],
+        >>>     prefix_singular="Type: ",
+        >>>     prefix_plural="Types: ",
+        >>> )
+        Types: str and int
+        >>> humanize_iterable(["Alice", "Bob", "Charlie"], wrap="'")
+        'Alice', 'Bob' and 'Charlie'
+        >>> humanize_iterable(["str", "int"], wrap=("<", ">"))
+        <str> and <int>
+    """
+    if (prefix_singular is None) != (prefix_plural is None):
+        raise ValueError(
+            "Both prefix_singular and prefix_plural must be provided together, "
+            "or neither should be provided."
+        )
+
+    if (suffix_singular is None) != (suffix_plural is None):
+        raise ValueError(
+            "Both suffix_singular and suffix_plural must be provided together, "
+            "or neither should be provided."
+        )
+
+    if not value:
+        raise ValueError("Cannot format an empty iterable.")
+
+    for item in value:
+        if not isinstance(item, (str, int, float, bool)):
+            raise TypeError(
+                f"All items must be primitives (str, int, float, bool). "
+                f"Got {type(item).__name__}: {item!r}"
+            )
+
+    str_items = [str(item) for item in value]
+
+    if wrap is not None:
+        if isinstance(wrap, tuple):
+            left, right = wrap
+            str_items = [f"{left}{item}{right}" for item in str_items]
+        else:
+            str_items = [f"{wrap}{item}{wrap}" for item in str_items]
+
+    if len(str_items) == 1:
+        formatted = str_items[0]
+        prefix = prefix_singular if prefix_singular is not None else ""
+        suffix = suffix_singular if suffix_singular is not None else ""
+    elif len(str_items) == 2:
+        formatted = f"{str_items[0]} {sep} {str_items[1]}"
+        prefix = prefix_plural if prefix_plural is not None else ""
+        suffix = suffix_plural if suffix_plural is not None else ""
+    else:
+        formatted = ", ".join(str_items[:-1]) + f" {sep} {str_items[-1]}"
+        prefix = prefix_plural if prefix_plural is not None else ""
+        suffix = suffix_plural if suffix_plural is not None else ""
+
+    return str(prefix.strip() + " " + formatted + " " + suffix.strip()).strip()
+
+
+def humanize_type(value: Any) -> str:
+    """
+    Humanize the output of a `type` instance in the same format as
+    `humanize_iterable`.
+
+    Args:
+        value (type):
+            The type to humanize. This can be simple types like `str` and more
+            complex types like `typing.Union` or `types.UnionType`.
+
+    Returns:
+        str:
+            The formatted string.
+
+    Examples:
+        >>> humanize_type(str)
+        str
+        >>> humanize_type(int | float)
+        int and float
+        >>> humanize_type(int | float | bool)
+        int, float and bool
+        >>> humanize_type(list[int | float])
+        list[int | float]
+        >>> humanize_type(tuple[str] | list[str])
+        tuple[str] and list[str]
+        >>> humanize_type(str | list[list[str]])
+        str and list[list[str]]
+    """
+
+    def format_type(t: Any, inside_generic: bool = False) -> str:
+        """
+        Format a type into a string.
+
+        Args:
+            t (Any):
+                The type to format
+            inside_generic (bool):
+                If `True`, unions use `|` instead of `humanize_iterable`
+        """
+        if t is type(None):
+            return "None"
+
+        origin = get_origin(t)
+        args = get_args(t)
+
+        is_union = origin is UnionType or str(origin).startswith("typing.Union")
+        if is_union:
+            members: list[str] = []
+            for arg in args:
+                members.append(format_type(arg, inside_generic=True))
+
+            if inside_generic:
+                return " | ".join(members)
+
+            return humanize_iterable(members)
+
+        if origin is not None and args:
+            origin_name = getattr(origin, "__name__", str(origin))
+
+            if args[-1] is Ellipsis:
+                inner_types: list[str] = []
+                for arg in args[:-1]:
+                    inner_types.append(format_type(arg, inside_generic=True))
+                inner = ", ".join(inner_types)
+                return f"{origin_name}[{inner}, ...]"
+
+            inner_types = []
+            for arg in args:
+                inner_types.append(format_type(arg, inside_generic=True))
+            inner = ", ".join(inner_types)
+            return f"{origin_name}[{inner}]"
+
+        if hasattr(t, "__name__"):
+            return cast(str, t.__name__)
+
+        return str(t)
+
+    return format_type(value, inside_generic=False)
+
+
+__all__ = ["humanize_iterable", "humanize_type"]

click_extended/utils/naming.py

@@ -0,0 +1,238 @@
+"""Utilities for validating and parsing naming conventions."""
+
+import re
+import sys
+
+import click
+
+from click_extended.utils.humanize import humanize_iterable
+
+SNAKE_CASE_PATTERN = re.compile(r"^[a-z][a-z0-9]*(_[a-z0-9]+)*$")
+SCREAMING_SNAKE_CASE_PATTERN = re.compile(r"^[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$")
+KEBAB_CASE_PATTERN = re.compile(r"^[a-z][a-z0-9]*(-[a-z0-9]+)*$")
+
+LONG_FLAG_PATTERN = re.compile(r"^--[a-z][a-z0-9-]*$")
+SHORT_FLAG_PATTERN = re.compile(r"^-[a-zA-Z]$")
+
+
+def is_valid_name(name: str) -> bool:
+    """
+    Check if a name is a valid name, in this case only `snake_case` formats
+    are considered valid.
+
+    Args:
+        name (str):
+            The name to validate.
+
+    Returns:
+        bool:
+            `True` if the name is valid, `False` otherwise.
+    """
+    return bool(SNAKE_CASE_PATTERN.match(name))
+
+
+def is_long_flag(value: str) -> bool:
+    """
+    Check if a value is a long flag (e.g. --option).
+
+    Args:
+        value (str):
+            The value to check.
+
+    Returns:
+        `True` if the value is a long flag, `False` otherwise.
+    """
+    return bool(LONG_FLAG_PATTERN.match(value))
+
+
+def is_short_flag(value: str) -> bool:
+    """
+    Check if a value is a short flag (e.g. -o).
+
+    Args:
+        value (str):
+            The value to check.
+
+    Returns:
+        `True` if the value is a short flag, `False` otherwise.
+    """
+    return bool(SHORT_FLAG_PATTERN.match(value))
+
+
+def validate_name(name: str, context: str = "name") -> None:
+    """
+    Validate a name follows naming conventions.
+
+    Args:
+        name (str):
+            The name to validate.
+        context (Context):
+            Context string for error messages
+            (e.g. "option name", "argument name").
+
+    Raises:
+        ValueError:
+            If the name doesn't follow valid conventions.
+    """
+    if not is_valid_name(name):
+
+        def _exit_program(message: str, tip: str) -> None:
+            click.echo(f"InvalidNameError: {message}", err=True)
+            click.echo(f"Tip: {tip}", err=True)
+            sys.exit(1)
+
+        # Empty name
+        if not name:
+            _exit_program(
+                "The name cannot be empty.",
+                "Provide a valid snake_case name (e.g. name, my_name)",
+            )
+
+        # Starts with number
+        if re.match(r"^\d", name):
+            _exit_program(
+                f"The name '{name}' cannot start with a number.",
+                f"Try with a letter prefix (e.g. 'var_{name}' or 'opt_{name}')",
+            )
+
+        # Starts with underscore
+        if name[0] == "_":
+            _exit_program(
+                f"The name '{name}' cannot start with an underscore.",
+                f"Try '{name[1:]}' without the leading underscore",
+            )
+
+        # Contains uppercase
+        if re.search(r"[A-Z]", name):
+            suggested = re.sub(r"(?<!^)(?=[A-Z])", "_", name).lower()
+            _exit_program(
+                f"The name '{name}' contains uppercase letters.",
+                f"Only use lowercase characters such as '{suggested}'",
+            )
+
+        # Contains hyphens
+        if "-" in name:
+            _exit_program(
+                f"The name '{name}' contains hyphens.",
+                f"Use underscores instead like '{name.replace('-', '_')}'",
+            )
+
+        # Contains spaces
+        if re.search(r"\s", name):
+            suggested_name = re.sub(r"\s+", "_", name).lower()
+            _exit_program(
+                f"The name '{name}' contains whitespace.",
+                f"Use underscores instead like '{suggested_name}'",
+            )
+
+        # Contains consecutive underscores
+        if re.search(r"__+", name):
+            _exit_program(
+                f"The name '{name}' contains consecutive underscores.",
+                f"Use single underscores like '{re.sub(r'__+', '_', name)}'",
+            )
+
+        # Contains invalid characters
+        invalid_match = re.search(r"[^a-z0-9_]", name)
+        if invalid_match:
+            invalid_chars = set(re.findall(r"[^a-z0-9_]", name))
+            contains_chars = humanize_iterable(
+                invalid_chars,
+                wrap="'",
+                prefix_singular="an invalid character",
+                prefix_plural="invalid characters",
+            )
+            remove_chars = humanize_iterable(
+                invalid_chars,
+                wrap="'",
+                prefix_singular="the character",
+                prefix_plural="the characters",
+            )
+            _exit_program(
+                f"The name '{name}' is invalid and contains {contains_chars}",
+                f"Remove {remove_chars}",
+            )
+
+        # General fallback
+        _exit_program(
+            f"The name '{name}' is invalid.",
+            "Names must be in snake_case (e.g. name, my_name, my_name1)",
+        )
+
+
+def parse_option_args(*args: str) -> tuple[str | None, str | None, str | None]:
+    """
+    Parse option decorator arguments intelligently.
+
+    Supports three forms:
+
+    1. **@option("my_option")**: name only
+    2. **@option("--my-option")**: long flag (derives name)
+    3. **@option("-m", "--my-option")**: short and long flags
+
+    Args:
+        *args (str):
+            Positional arguments passed to `@option` decorator.
+
+    Returns:
+        Tuple of (name, short, long):
+
+        - **name**: The parameter name (`None` if not provided)
+        - **short**: The short flag (`None` if not provided)
+        - **long**: The long flag (`None` if not provided)
+
+    Raises:
+        ValueError:
+            If arguments are invalid or ambiguous.
+    """
+
+    if len(args) == 0:
+        return None, None, None
+
+    if len(args) == 1:
+        arg = args[0]
+
+        # @option("--my-option")
+        if is_long_flag(arg):
+            return None, None, arg
+
+        # @option("-m")
+        if is_short_flag(arg):
+            raise ValueError(
+                f"Short flag '{arg}' provided without long flag or name. "
+                f"Use one of:\n"
+                f"  @option('{arg}', '--flag')  # with long flag\n"
+                f"  @option('name', short='{arg}')  # with name parameter"
+            )
+
+        # @option("my_option")
+        validate_name(arg, "option name")
+        return arg, None, None
+
+    if len(args) == 2:
+        first, second = args
+
+        # @option("-m", "--my-option")
+        if is_short_flag(first) and is_long_flag(second):
+            return None, first, second
+
+        # @option("--my-option", "-m")
+        if is_long_flag(first) and is_short_flag(second):
+            raise ValueError(
+                "Invalid argument order. "
+                "Short flag must come before long flag:\n"
+                f"  Use: @option('{second}', '{first}')"
+            )
+
+        raise ValueError(
+            f"Invalid arguments: '{first}', '{second}'. "
+            f"Expected one of:\n"
+            f"  @option('name')  # name only\n"
+            f"  @option('--flag')  # long flag only\n"
+            f"  @option('-f', '--flag')  # short and long flags"
+        )
+
+    raise ValueError(
+        f"Too many positional arguments ({len(args)}). "
+        f"Maximum is 2 (short and long flags)."
+    )