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

click_extended/utils/process.py

@@ -0,0 +1,294 @@
+"""Utility functions for processing child nodes."""
+
+# pylint: disable=too-many-locals
+# pylint: disable=broad-exception-caught
+# pylint: disable=too-many-branches
+
+from typing import TYPE_CHECKING, Any, Mapping, cast
+
+import click
+
+from click_extended.core.other._tree import Tree
+from click_extended.core.other.context import Context
+from click_extended.errors import ContextAwareError
+from click_extended.utils.dispatch import (
+    dispatch_to_child,
+    dispatch_to_child_async,
+    has_async_handlers,
+)
+
+if TYPE_CHECKING:
+    from click_extended.core.decorators.tag import Tag
+    from click_extended.core.nodes._root_node import RootNode
+    from click_extended.core.nodes.child_node import ChildNode
+    from click_extended.core.nodes.parent_node import ParentNode
+
+
+def process_children(
+    value: Any,
+    children: Mapping[Any, Any],
+    parent: "ParentNode | Tag",
+    tags: dict[str, "Tag"] | None = None,
+    click_context: click.Context | None = None,
+) -> Any:
+    """
+    Process a value through a chain of child nodes.
+    This is a `phase 4` function and does the following:
+
+    1. Updates scope tracking for each child
+    2. Dispatches value to appropriate handler
+    3. Wraps handler execution to catch exceptions
+    4. Converts user exceptions to ProcessError with context
+
+    Args:
+        value (Any):
+            The initial value to process.
+        children (Mapping[Any, Any]):
+            Mapping of child nodes to process the value through.
+        parent (ParentNode | Tag):
+            The parent node that owns these children.
+        tags (dict[str, Tag]):
+            Dictionary mapping tag names to Tag instances.
+        context (click.Context):
+            The Click context for scope tracking and error reporting.
+
+    Returns:
+        The processed value after passing through all children.
+
+    Raises:
+        UnhandledTypeError:
+            If a child node doesn't implement a handler for the value type.
+        ProcessError:
+            If validation or transformation fails in a child node.
+    """
+    child_nodes = [cast("ChildNode", child) for child in children.values()]
+
+    if tags is None:
+        tags = {}
+
+    is_container_tuple = False
+    if isinstance(value, tuple) and parent.__class__.__name__ in (
+        "Option",
+        "Argument",
+    ):
+        parent_cast: click.Option | click.Argument
+        if parent.__class__.__name__ == "Option":
+            parent_cast = cast(click.Option, parent)
+            is_container_tuple = parent_cast.multiple or parent_cast.nargs != 1
+        else:
+            parent_cast = cast(click.Argument, parent)
+            is_container_tuple = parent_cast.nargs != 1
+
+    for child in child_nodes:
+        if click_context is not None:
+            Tree.update_scope(
+                click_context,
+                "child",
+                parent_node=(
+                    cast("ParentNode", parent)
+                    if parent.__class__.__name__ != "Tag"
+                    else None
+                ),
+                child_node=child,
+            )
+
+            if "click_extended" in click_context.meta:
+                click_context.meta["click_extended"]["handler_value"] = value
+                click_context.meta["click_extended"][
+                    "is_container_tuple"
+                ] = is_container_tuple
+
+        root_node: "RootNode | None" = None
+        all_nodes: dict[str, Any] = {}
+        all_parents: dict[str, Any] = {}
+        all_tags: dict[str, Any] = {}
+        all_children: dict[str, Any] = {}
+        all_globals: dict[str, Any] = {}
+        meta: dict[str, Any] = {}
+
+        if click_context is not None and "click_extended" in click_context.meta:
+            meta = click_context.meta["click_extended"]
+            root_node = meta.get("root_node")
+
+            if "parents" in meta:
+                all_parents = meta["parents"]
+                all_nodes.update(all_parents)
+
+            if "tags" in meta:
+                all_tags = meta["tags"]
+                all_nodes.update(all_tags)
+
+            if "children" in meta:
+                all_children = meta["children"]
+                all_nodes.update(all_children)
+
+            if "globals" in meta:
+                all_globals = meta["globals"]
+                all_nodes.update(all_globals)
+
+            if root_node:
+                all_nodes[root_node.name] = root_node
+
+        context = Context(
+            root=cast("RootNode", root_node),
+            parent=parent,
+            current=child,
+            click_context=cast(click.Context, click_context),
+            nodes=all_nodes,
+            parents=all_parents,
+            tags=all_tags,
+            children=all_children,
+            data=meta.get("data", {}),
+            debug=meta.get("debug", False),
+        )
+
+        if isinstance(child, type(ContextAwareError)):
+            raise child
+
+        value = dispatch_to_child(child, value, context)
+
+    return value  # type: ignore
+
+
+async def process_children_async(
+    value: Any,
+    children: Mapping[Any, Any],
+    parent: "ParentNode | Tag",
+    tags: dict[str, "Tag"] | None = None,
+    click_context: click.Context | None = None,
+) -> Any:
+    """
+    Async version of process_children for async handler support.
+
+    Process a value through a chain of child nodes (async).
+    This is a `phase 4` function and does the following:
+
+    1. Updates scope tracking for each child
+    2. Dispatches value to appropriate handler (with async support)
+    3. Wraps handler execution to catch exceptions
+    4. Converts user exceptions to ProcessError with context
+
+    Args:
+        value (Any):
+            The initial value to process.
+        children (Mapping[Any, Any]):
+            Mapping of child nodes to process the value through.
+        parent (ParentNode | Tag):
+            The parent node that owns these children.
+        tags (dict[str, Tag]):
+            Dictionary mapping tag names to Tag instances.
+        context (click.Context):
+            The Click context for scope tracking and error reporting.
+
+    Returns:
+        The processed value after passing through all children.
+
+    Raises:
+        UnhandledTypeError:
+            If a child node doesn't implement a handler for the value type.
+        ProcessError:
+            If validation or transformation fails in a child node.
+    """
+    child_nodes = [cast("ChildNode", child) for child in children.values()]
+
+    if tags is None:
+        tags = {}
+
+    is_container_tuple = False
+    if isinstance(value, tuple) and parent.__class__.__name__ in (
+        "Option",
+        "Argument",
+    ):
+        parent_cast: click.Option | click.Argument
+        if parent.__class__.__name__ == "Option":
+            parent_cast = cast(click.Option, parent)
+            is_container_tuple = parent_cast.multiple or parent_cast.nargs != 1
+        else:
+            parent_cast = cast(click.Argument, parent)
+            is_container_tuple = parent_cast.nargs != 1
+
+    for child in child_nodes:
+        if click_context is not None:
+            Tree.update_scope(
+                click_context,
+                "child",
+                parent_node=(
+                    cast("ParentNode", parent)
+                    if parent.__class__.__name__ != "Tag"
+                    else None
+                ),
+                child_node=child,
+            )
+
+            if "click_extended" in click_context.meta:
+                click_context.meta["click_extended"]["handler_value"] = value
+                click_context.meta["click_extended"][
+                    "is_container_tuple"
+                ] = is_container_tuple
+
+        root_node: "RootNode | None" = None
+        all_nodes: dict[str, Any] = {}
+        all_parents: dict[str, Any] = {}
+        all_tags: dict[str, Any] = {}
+        all_children: dict[str, Any] = {}
+        all_globals: dict[str, Any] = {}
+        meta: dict[str, Any] = {}
+
+        if click_context is not None and "click_extended" in click_context.meta:
+            meta = click_context.meta["click_extended"]
+            root_node = meta.get("root_node")
+
+            if "parents" in meta:
+                all_parents = meta["parents"]
+                all_nodes.update(all_parents)
+
+            if "tags" in meta:
+                all_tags = meta["tags"]
+                all_nodes.update(all_tags)
+
+            if "children" in meta:
+                all_children = meta["children"]
+                all_nodes.update(all_children)
+
+            if "globals" in meta:
+                all_globals = meta["globals"]
+                all_nodes.update(all_globals)
+
+            if root_node:
+                all_nodes[root_node.name] = root_node
+
+        context = Context(
+            root=cast("RootNode", root_node),
+            parent=parent,
+            current=child,
+            click_context=cast(click.Context, click_context),
+            nodes=all_nodes,
+            parents=all_parents,
+            tags=all_tags,
+            children=all_children,
+            data=meta.get("data", {}),
+            debug=meta.get("debug", False),
+        )
+
+        if isinstance(child, type(ContextAwareError)):
+            raise child
+
+        value = await dispatch_to_child_async(child, value, context)
+
+    return value  # type: ignore
+
+
+def check_has_async_handlers(children: Mapping[Any, Any]) -> bool:
+    """
+    Check if any child in the collection has async handlers.
+
+    Args:
+        children (Mapping[Any, Any]):
+            Mapping of child nodes to check.
+
+    Returns:
+        bool:
+            `True` if any child has async handlers, `False` otherwise.
+    """
+    child_nodes = [cast("ChildNode", child) for child in children.values()]
+    return any(has_async_handlers(child) for child in child_nodes)

click_extended/utils/selection.py

@@ -0,0 +1,267 @@
+"""Interactive selection prompt for runtime use."""
+
+# pylint: disable=too-many-arguments
+# pylint: disable=too-many-positional-arguments
+# pylint: disable=too-many-locals
+# pylint: disable=too-many-branches
+# pylint: disable=too-many-statements
+
+import sys
+import termios
+import tty
+
+
+def selection(
+    selections: list[str | tuple[str, str]],
+    prompt: str = "Select an option",
+    multiple: bool = False,
+    default: str | list[str] | None = None,
+    min_selections: int = 0,
+    max_selections: int | None = None,
+    cursor_style: str = ">",
+    checkbox_style: tuple[str, str] = ("◯", "◉"),
+    show_count: bool = False,
+) -> str | list[str]:
+    """
+    Interactive selection prompt with arrow key navigation.
+
+    Creates an interactive terminal prompt that allows users to select one or
+    more options using arrow keys (or j/k vim-style keys). The list wraps around
+    (carousel behavior) when scrolling past the first or last item.
+
+    Args:
+        selections (list[str | tuple[str, str]]):
+            List of options. Each item can be:
+            - str: Used as both display text and value
+            - tuple[str, str]: (display_text, value)
+        prompt (str):
+            Text to display above the selection list.
+            Defaults to "Select an option".
+        multiple (bool):
+            If `True`, allows multiple selections with checkboxes.
+            If `False`, allows single selection only. Defaults to `False`.
+        default (str | list[str] | None):
+            Default selection(s). Should be a string for single mode,
+            or list of strings for multiple mode. Defaults to `None`.
+        min_selections (int):
+            Minimum number of selections required (multiple mode only).
+            Defaults to 0. User cannot confirm until minimum is met.
+        max_selections (int | None):
+            Maximum number of selections allowed (multiple mode only).
+            Defaults to `None` (unlimited). Prevents selecting more than max.
+        cursor_style (str):
+            The cursor indicator string. Defaults to ">".
+            Examples: ">", "→", "▶", "•"
+        checkbox_style (tuple[str, str]):
+            Tuple of (unselected, selected) checkbox indicators.
+            Defaults to ("◯", "◉").
+            Examples: ("☐", "☑"), ("○", "●"), ("[ ]", "[x]")
+        show_count (bool):
+            Whether to show selection count in the prompt.
+            Defaults to `False`. Shows "(X/Y selected)" when enabled.
+
+    Returns:
+        str | list[str]:
+            Selected value(s). `str` for single mode, `list[str]` for
+            multiple mode.
+
+    Raises:
+        ValueError:
+            If selections list is empty or invalid.
+        RuntimeError:
+            If not running in a TTY and no default is provided.
+        KeyboardInterrupt:
+            If user presses Ctrl+C.
+
+    Examples:
+        >>> from click_extended.interactive import selection
+        >>>
+        >>> # Simple single selection
+        >>> framework = selection(["React", "Vue", "Angular"])
+        >>> print(f"Selected: {framework}")
+        >>>
+        >>> # Multiple selection with constraints
+        >>> features = selection(
+        ...     [("TypeScript", "ts"), ("ESLint", "eslint"),
+                 ("Prettier", "prettier")],
+        ...     prompt="Select features",
+        ...     multiple=True,
+        ...     min_selections=1,
+        ...     max_selections=2,
+        ...     default=["eslint"]
+        ... )
+        >>> print(f"Enabled: {features}")
+    """
+    if not selections:
+        raise ValueError("Selections list cannot be empty")
+
+    normalized: list[tuple[str, str]] = []
+    for item in selections:
+        if isinstance(item, tuple):
+            if len(item) != 2:
+                raise ValueError(
+                    "Tuple selections must have exactly "
+                    f"2 elements, got {len(item)}"
+                )
+            display, value = item
+            normalized.append((str(display), str(value)))
+        else:
+            normalized.append((str(item), str(item)))
+
+    if multiple:
+        if min_selections < 0:
+            raise ValueError(
+                f"min_selections must be >= 0, got {min_selections}"
+            )
+        if max_selections is not None:
+            if max_selections < 1:
+                raise ValueError(
+                    f"max_selections must be >= 1, got {max_selections}"
+                )
+            if max_selections < min_selections:
+                raise ValueError(
+                    f"max_selections ({max_selections}) must be >= "
+                    f"min_selections ({min_selections})"
+                )
+            if max_selections > len(normalized):
+                raise ValueError(
+                    f"max_selections ({max_selections}) cannot exceed "
+                    f"number of options ({len(normalized)})"
+                )
+
+    if not sys.stdin.isatty():
+        if default is not None:
+            return default
+        raise RuntimeError(
+            "Interactive selection requires a TTY. "
+            "Please provide a default value."
+        )
+
+    cursor = 0
+    selected: set[int] = set()
+
+    if default is not None:
+        value_to_idx = {value: idx for idx, (_, value) in enumerate(normalized)}
+
+        if multiple and isinstance(default, list):
+            for val in default:
+                if val in value_to_idx:
+                    selected.add(value_to_idx[val])
+        elif not multiple and isinstance(default, str):
+            if default in value_to_idx:
+                cursor = value_to_idx[default]
+                selected.add(cursor)
+        elif multiple and isinstance(default, str):
+            if default in value_to_idx:
+                selected.add(value_to_idx[default])
+        elif not multiple and isinstance(default, list) and len(default) > 0:
+            if default[0] in value_to_idx:
+                cursor = value_to_idx[default[0]]
+                selected.add(cursor)
+
+    num_options = len(normalized)
+    num_lines = 0
+
+    try:
+        while True:
+            if num_lines > 0:
+                for _ in range(num_lines):
+                    sys.stdout.write("\x1b[1A\x1b[2K")
+                sys.stdout.flush()
+
+            lines: list[str] = []
+            title = prompt.strip().rstrip(":")
+
+            if multiple:
+                count = len(selected)
+                if max_selections is not None:
+                    title += f" ({count}/{max_selections} selected"
+                    if min_selections > 0 and count < min_selections:
+                        needed = min_selections - count
+                        title += f", need {needed} more"
+                    title += ")"
+                elif min_selections > 0 and count < min_selections:
+                    needed = min_selections - count
+                    title += f" ({count} selected, need {needed} more)"
+                elif show_count:
+                    title += f" ({count} selected)"
+
+            title += ":"
+            lines.append(title)
+
+            for idx, (display, _) in enumerate(normalized):
+                is_cursor = idx == cursor
+                is_selected = idx in selected
+
+                if multiple:
+                    checkbox = (
+                        checkbox_style[1] if is_selected else checkbox_style[0]
+                    )
+                    prefix = f"{cursor_style} " if is_cursor else "  "
+                    lines.append(f"{prefix}{checkbox} {display}")
+                else:
+                    prefix = f"{cursor_style} " if is_cursor else "  "
+                    lines.append(f"{prefix}{display}")
+
+            output = "\n".join(lines)
+            sys.stdout.write(output + "\n")
+            sys.stdout.flush()
+            num_lines = len(lines)
+
+            fd = sys.stdin.fileno()
+            old_settings = termios.tcgetattr(fd)
+
+            try:
+                tty.setraw(fd)
+                ch = sys.stdin.read(1)
+
+                if ch == "\x1b":
+                    next_chars = sys.stdin.read(2)
+                    if next_chars == "[A":
+                        key = "up"
+                    elif next_chars == "[B":
+                        key = "down"
+                    else:
+                        key = "other"
+                elif ch in ("\r", "\n"):
+                    key = "enter"
+                elif ch == " ":
+                    key = "space"
+                elif ch == "\x03":  # Ctrl+C
+                    key = "ctrl_c"
+                elif ch == "k":
+                    key = "up"
+                elif ch == "j":
+                    key = "down"
+                else:
+                    key = "other"
+            finally:
+                termios.tcsetattr(fd, termios.TCSADRAIN, old_settings)
+
+            if key == "up":
+                cursor = (cursor - 1) % num_options
+            elif key == "down":
+                cursor = (cursor + 1) % num_options
+            elif key == "space" and multiple:
+                if cursor in selected:
+                    selected.remove(cursor)
+                else:
+                    if max_selections is None or len(selected) < max_selections:
+                        selected.add(cursor)
+            elif key == "enter":
+                if multiple:
+                    if len(selected) < min_selections:
+                        continue
+                    result = [normalized[idx][1] for idx in sorted(selected)]
+                    return result
+                return normalized[cursor][1]
+            elif key == "ctrl_c":
+                raise KeyboardInterrupt("Selection cancelled by user")
+
+    except KeyboardInterrupt:
+        if num_lines > 0:
+            for _ in range(num_lines):
+                sys.stdout.write("\x1b[1A\x1b[2K")
+            sys.stdout.write("\x1b[1A")
+            sys.stdout.flush()
+        raise

click_extended/utils/time.py

@@ -0,0 +1,46 @@
+"""Time, date, and datetime utilities."""
+
+
+def normalize_datetime_format(fmt: str) -> str:
+    """
+    Convert simplified format strings to Python strptime format.
+
+    Supports both Python strptime format (e.g., %Y-%m-%d, %H:%M:%S)
+    and simplified format (e.g., YYYY-MM-DD, HH:mm:SS).
+
+    Args:
+        fmt (str):
+            A format string in either Python strptime format or
+            simplified format.
+
+    Returns:
+        str:
+            The normalized Python strptime format string.
+
+    Example:
+        ```python
+        >>> normalize_datetime_format("YYYY-MM-DD HH:mm:SS")
+        '%Y-%m-%d %H:%M:%S'
+        >>> normalize_datetime_format("%Y-%m-%d")
+        '%Y-%m-%d'
+        ```
+    """
+    if "%" in fmt:
+        return fmt
+
+    replacements = {
+        "YYYY": "%Y",
+        "YY": "%y",
+        "MM": "%m",
+        "DD": "%d",
+        "HH": "%H",
+        "mm": "%M",
+        "SS": "%S",
+        "ss": "%S",
+    }
+
+    result = fmt
+    for simple, strp in replacements.items():
+        result = result.replace(simple, strp)
+
+    return result