falyx 0.1.27__py3-none-any.whl → 0.1.28__py3-none-any.whl

falyx/argparse.py

@@ -0,0 +1,596 @@
+# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
+from copy import deepcopy
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any, Iterable
+
+from rich.console import Console
+from rich.table import Table
+
+from falyx.exceptions import CommandArgumentError
+from falyx.signals import HelpSignal
+
+
+class ArgumentAction(Enum):
+    """Defines the action to be taken when the argument is encountered."""
+
+    STORE = "store"
+    STORE_TRUE = "store_true"
+    STORE_FALSE = "store_false"
+    APPEND = "append"
+    EXTEND = "extend"
+    COUNT = "count"
+    HELP = "help"
+
+
+@dataclass
+class Argument:
+    """Represents a command-line argument."""
+
+    flags: list[str]
+    dest: str  # Destination name for the argument
+    action: ArgumentAction = (
+        ArgumentAction.STORE
+    )  # Action to be taken when the argument is encountered
+    type: Any = str  # Type of the argument (e.g., str, int, float) or callable
+    default: Any = None  # Default value if the argument is not provided
+    choices: list[str] | None = None  # List of valid choices for the argument
+    required: bool = False  # True if the argument is required
+    help: str = ""  # Help text for the argument
+    nargs: int | str = 1  # int, '?', '*', '+'
+    positional: bool = False  # True if no leading - or -- in flags
+
+
+class CommandArgumentParser:
+    """
+    Custom argument parser for Falyx Commands.
+    It is used to create a command-line interface for Falyx
+    commands, allowing users to specify options and arguments
+    when executing commands.
+    It is not intended to be a full-featured replacement for
+    argparse, but rather a lightweight alternative for specific use
+    cases within the Falyx framework.
+
+    Features:
+    - Customizable argument parsing.
+    - Type coercion for arguments.
+    - Support for positional and keyword arguments.
+    - Support for default values.
+    - Support for boolean flags.
+    - Exception handling for invalid arguments.
+    - Render Help using Rich library.
+    """
+
+    def __init__(self) -> None:
+        """Initialize the CommandArgumentParser."""
+        self.command_description: str = ""
+        self._arguments: list[Argument] = []
+        self._flag_map: dict[str, Argument] = {}
+        self._dest_set: set[str] = set()
+        self._add_help()
+        self.console = Console(color_system="auto")
+
+    def _add_help(self):
+        """Add help argument to the parser."""
+        self.add_argument(
+            "--help",
+            "-h",
+            action=ArgumentAction.HELP,
+            help="Show this help message and exit.",
+            dest="help",
+        )
+
+    def _is_positional(self, flags: tuple[str, ...]) -> bool:
+        """Check if the flags are positional."""
+        positional = False
+        if any(not flag.startswith("-") for flag in flags):
+            positional = True
+
+        if positional and len(flags) > 1:
+            raise CommandArgumentError("Positional arguments cannot have multiple flags")
+        return positional
+
+    def _get_dest_from_flags(
+        self, flags: tuple[str, ...], dest: str | None
+    ) -> str | None:
+        """Convert flags to a destination name."""
+        if dest:
+            if not dest.replace("_", "").isalnum():
+                raise CommandArgumentError(
+                    "dest must be a valid identifier (letters, digits, and underscores only)"
+                )
+            if dest[0].isdigit():
+                raise CommandArgumentError("dest must not start with a digit")
+            return dest
+        dest = None
+        for flag in flags:
+            if flag.startswith("--"):
+                dest = flag.lstrip("-").replace("-", "_").lower()
+                break
+            elif flag.startswith("-"):
+                dest = flag.lstrip("-").replace("-", "_").lower()
+            else:
+                dest = flag.replace("-", "_").lower()
+        assert dest is not None, "dest should not be None"
+        if not dest.replace("_", "").isalnum():
+            raise CommandArgumentError(
+                "dest must be a valid identifier (letters, digits, and underscores only)"
+            )
+        if dest[0].isdigit():
+            raise CommandArgumentError("dest must not start with a digit")
+        return dest
+
+    def _determine_required(
+        self, required: bool, positional: bool, nargs: int | str
+    ) -> bool:
+        """Determine if the argument is required."""
+        if required:
+            return True
+        if positional:
+            if isinstance(nargs, int):
+                return nargs > 0
+            elif isinstance(nargs, str):
+                if nargs in ("+"):
+                    return True
+                elif nargs in ("*", "?"):
+                    return False
+                else:
+                    raise CommandArgumentError(f"Invalid nargs value: {nargs}")
+
+        return required
+
+    def _validate_nargs(self, nargs: int | str) -> int | str:
+        allowed_nargs = ("?", "*", "+")
+        if isinstance(nargs, int):
+            if nargs <= 0:
+                raise CommandArgumentError("nargs must be a positive integer")
+        elif isinstance(nargs, str):
+            if nargs not in allowed_nargs:
+                raise CommandArgumentError(f"Invalid nargs value: {nargs}")
+        else:
+            raise CommandArgumentError(f"nargs must be an int or one of {allowed_nargs}")
+        return nargs
+
+    def _normalize_choices(self, choices: Iterable, expected_type: Any) -> list[Any]:
+        if choices is not None:
+            if isinstance(choices, dict):
+                raise CommandArgumentError("choices cannot be a dict")
+            try:
+                choices = list(choices)
+            except TypeError:
+                raise CommandArgumentError(
+                    "choices must be iterable (like list, tuple, or set)"
+                )
+        else:
+            choices = []
+        for choice in choices:
+            if not isinstance(choice, expected_type):
+                try:
+                    expected_type(choice)
+                except Exception:
+                    raise CommandArgumentError(
+                        f"Invalid choice {choice!r}: not coercible to {expected_type.__name__}"
+                    )
+        return choices
+
+    def _validate_default_type(
+        self, default: Any, expected_type: type, dest: str
+    ) -> None:
+        """Validate the default value type."""
+        if default is not None and not isinstance(default, expected_type):
+            try:
+                expected_type(default)
+            except Exception:
+                raise CommandArgumentError(
+                    f"Default value {default!r} for '{dest}' cannot be coerced to {expected_type.__name__}"
+                )
+
+    def _validate_default_list_type(
+        self, default: list[Any], expected_type: type, dest: str
+    ) -> None:
+        if isinstance(default, list):
+            for item in default:
+                if not isinstance(item, expected_type):
+                    try:
+                        expected_type(item)
+                    except Exception:
+                        raise CommandArgumentError(
+                            f"Default list value {default!r} for '{dest}' cannot be coerced to {expected_type.__name__}"
+                        )
+
+    def _resolve_default(
+        self, action: ArgumentAction, default: Any, nargs: str | int
+    ) -> Any:
+        """Get the default value for the argument."""
+        if default is None:
+            if action == ArgumentAction.STORE_TRUE:
+                return False
+            elif action == ArgumentAction.STORE_FALSE:
+                return True
+            elif action == ArgumentAction.COUNT:
+                return 0
+            elif action in (ArgumentAction.APPEND, ArgumentAction.EXTEND):
+                return []
+            elif nargs in ("+", "*"):
+                return []
+            else:
+                return None
+        return default
+
+    def _validate_flags(self, flags: tuple[str, ...]) -> None:
+        """Validate the flags provided for the argument."""
+        if not flags:
+            raise CommandArgumentError("No flags provided")
+        for flag in flags:
+            if not isinstance(flag, str):
+                raise CommandArgumentError(f"Flag '{flag}' must be a string")
+            if flag.startswith("--") and len(flag) < 3:
+                raise CommandArgumentError(
+                    f"Flag '{flag}' must be at least 3 characters long"
+                )
+            if flag.startswith("-") and not flag.startswith("--") and len(flag) > 2:
+                raise CommandArgumentError(
+                    f"Flag '{flag}' must be a single character or start with '--'"
+                )
+
+    def add_argument(self, *flags, **kwargs):
+        """Add an argument to the parser.
+        Args:
+            name or flags: Either a name or prefixed flags (e.g. 'faylx', '-f', '--falyx').
+            action: The action to be taken when the argument is encountered.
+            nargs: The number of arguments expected.
+            default: The default value if the argument is not provided.
+            type: The type to which the command-line argument should be converted.
+            choices: A container of the allowable values for the argument.
+            required: Whether or not the argument is required.
+            help: A brief description of the argument.
+            dest: The name of the attribute to be added to the object returned by parse_args().
+        """
+        self._validate_flags(flags)
+        positional = self._is_positional(flags)
+        dest = self._get_dest_from_flags(flags, kwargs.get("dest"))
+        if dest in self._dest_set:
+            raise CommandArgumentError(
+                f"Destination '{dest}' is already defined.\n"
+                "Merging multiple arguments into the same dest (e.g. positional + flagged) "
+                "is not supported. Define a unique 'dest' for each argument."
+            )
+        self._dest_set.add(dest)
+        action = kwargs.get("action", ArgumentAction.STORE)
+        if not isinstance(action, ArgumentAction):
+            try:
+                action = ArgumentAction(action)
+            except ValueError:
+                raise CommandArgumentError(
+                    f"Invalid action '{action}' is not a valid ArgumentAction"
+                )
+        flags = list(flags)
+        nargs = self._validate_nargs(kwargs.get("nargs", 1))
+        default = self._resolve_default(action, kwargs.get("default"), nargs)
+        expected_type = kwargs.get("type", str)
+        if (
+            action in (ArgumentAction.STORE, ArgumentAction.APPEND, ArgumentAction.EXTEND)
+            and default is not None
+        ):
+            if isinstance(default, list):
+                self._validate_default_list_type(default, expected_type, dest)
+            else:
+                self._validate_default_type(default, expected_type, dest)
+        choices = self._normalize_choices(kwargs.get("choices"), expected_type)
+        if default is not None and choices and default not in choices:
+            raise CommandArgumentError(
+                f"Default value '{default}' not in allowed choices: {choices}"
+            )
+        required = self._determine_required(
+            kwargs.get("required", False), positional, nargs
+        )
+        argument = Argument(
+            flags=flags,
+            dest=dest,
+            action=action,
+            type=expected_type,
+            default=default,
+            choices=choices,
+            required=required,
+            help=kwargs.get("help", ""),
+            nargs=nargs,
+            positional=positional,
+        )
+        for flag in flags:
+            if flag in self._flag_map:
+                existing = self._flag_map[flag]
+                raise CommandArgumentError(
+                    f"Flag '{flag}' is already used by argument '{existing.dest}'"
+                )
+            self._flag_map[flag] = argument
+        self._arguments.append(argument)
+
+    def get_argument(self, dest: str) -> Argument | None:
+        return next((a for a in self._arguments if a.dest == dest), None)
+
+    def _consume_nargs(
+        self, args: list[str], start: int, spec: Argument
+    ) -> tuple[list[str], int]:
+        values = []
+        i = start
+        if isinstance(spec.nargs, int):
+            # assert i + spec.nargs <= len(
+            #     args
+            # ), "Not enough arguments provided: shouldn't happen"
+            values = args[i : i + spec.nargs]
+            return values, i + spec.nargs
+        elif spec.nargs == "+":
+            if i >= len(args):
+                raise CommandArgumentError(
+                    f"Expected at least one value for '{spec.dest}'"
+                )
+            while i < len(args) and not args[i].startswith("-"):
+                values.append(args[i])
+                i += 1
+            assert values, "Expected at least one value for '+' nargs: shouldn't happen"
+            return values, i
+        elif spec.nargs == "*":
+            while i < len(args) and not args[i].startswith("-"):
+                values.append(args[i])
+                i += 1
+            return values, i
+        elif spec.nargs == "?":
+            if i < len(args) and not args[i].startswith("-"):
+                return [args[i]], i + 1
+            return [], i
+        else:
+            assert False, "Invalid nargs value: shouldn't happen"
+
+    def _consume_all_positional_args(
+        self,
+        args: list[str],
+        result: dict[str, Any],
+        positional_args: list[Argument],
+        consumed_positional_indicies: set[int],
+    ) -> int:
+        remaining_positional_args = [
+            (j, spec)
+            for j, spec in enumerate(positional_args)
+            if j not in consumed_positional_indicies
+        ]
+        i = 0
+
+        for j, spec in remaining_positional_args:
+            # estimate how many args the remaining specs might need
+            is_last = j == len(positional_args) - 1
+            remaining = len(args) - i
+            min_required = 0
+            for next_spec in positional_args[j + 1 :]:
+                if isinstance(next_spec.nargs, int):
+                    min_required += next_spec.nargs
+                elif next_spec.nargs == "+":
+                    min_required += 1
+                elif next_spec.nargs == "?":
+                    min_required += 0
+                elif next_spec.nargs == "*":
+                    min_required += 0
+                else:
+                    assert False, "Invalid nargs value: shouldn't happen"
+
+            slice_args = args[i:] if is_last else args[i : i + (remaining - min_required)]
+            values, new_i = self._consume_nargs(slice_args, 0, spec)
+            i += new_i
+
+            try:
+                typed = [spec.type(v) for v in values]
+            except Exception:
+                raise CommandArgumentError(
+                    f"Invalid value for '{spec.dest}': expected {spec.type.__name__}"
+                )
+
+            if spec.action == ArgumentAction.APPEND:
+                assert result.get(spec.dest) is not None, "dest should not be None"
+                if spec.nargs in (None, 1):
+                    result[spec.dest].append(typed[0])
+                else:
+                    result[spec.dest].append(typed)
+            elif spec.action == ArgumentAction.EXTEND:
+                assert result.get(spec.dest) is not None, "dest should not be None"
+                result[spec.dest].extend(typed)
+            elif spec.nargs in (None, 1, "?"):
+                result[spec.dest] = typed[0] if len(typed) == 1 else typed
+            else:
+                result[spec.dest] = typed
+
+            if spec.nargs not in ("*", "+"):
+                consumed_positional_indicies.add(j)
+
+        if i < len(args):
+            raise CommandArgumentError(f"Unexpected positional argument: {args[i:]}")
+
+        return i
+
+    def parse_args(self, args: list[str] | None = None) -> dict[str, Any]:
+        """Parse Falyx Command arguments."""
+        if args is None:
+            args = []
+
+        result = {arg.dest: deepcopy(arg.default) for arg in self._arguments}
+        positional_args = [arg for arg in self._arguments if arg.positional]
+        consumed_positional_indices: set[int] = set()
+
+        consumed_indices: set[int] = set()
+        i = 0
+        while i < len(args):
+            token = args[i]
+            if token in self._flag_map:
+                spec = self._flag_map[token]
+                action = spec.action
+
+                if action == ArgumentAction.HELP:
+                    self.render_help()
+                    raise HelpSignal()
+                elif action == ArgumentAction.STORE_TRUE:
+                    result[spec.dest] = True
+                    consumed_indices.add(i)
+                    i += 1
+                elif action == ArgumentAction.STORE_FALSE:
+                    result[spec.dest] = False
+                    consumed_indices.add(i)
+                    i += 1
+                elif action == ArgumentAction.COUNT:
+                    result[spec.dest] = result.get(spec.dest, 0) + 1
+                    consumed_indices.add(i)
+                    i += 1
+                elif action == ArgumentAction.APPEND:
+                    assert result.get(spec.dest) is not None, "dest should not be None"
+                    values, new_i = self._consume_nargs(args, i + 1, spec)
+                    try:
+                        typed_values = [spec.type(value) for value in values]
+                    except ValueError:
+                        raise CommandArgumentError(
+                            f"Invalid value for '{spec.dest}': expected {spec.type.__name__}"
+                        )
+                    if spec.nargs in (None, 1):
+                        try:
+                            result[spec.dest].append(spec.type(values[0]))
+                        except ValueError:
+                            raise CommandArgumentError(
+                                f"Invalid value for '{spec.dest}': expected {spec.type.__name__}"
+                            )
+                    else:
+                        result[spec.dest].append(typed_values)
+                    consumed_indices.update(range(i, new_i))
+                    i = new_i
+                elif action == ArgumentAction.EXTEND:
+                    assert result.get(spec.dest) is not None, "dest should not be None"
+                    values, new_i = self._consume_nargs(args, i + 1, spec)
+                    try:
+                        typed_values = [spec.type(value) for value in values]
+                    except ValueError:
+                        raise CommandArgumentError(
+                            f"Invalid value for '{spec.dest}': expected {spec.type.__name__}"
+                        )
+                    result[spec.dest].extend(typed_values)
+                    consumed_indices.update(range(i, new_i))
+                    i = new_i
+                else:
+                    values, new_i = self._consume_nargs(args, i + 1, spec)
+                    try:
+                        typed_values = [spec.type(v) for v in values]
+                    except ValueError:
+                        raise CommandArgumentError(
+                            f"Invalid value for '{spec.dest}': expected {spec.type.__name__}"
+                        )
+                    if (
+                        spec.nargs in (None, 1, "?")
+                        and spec.action != ArgumentAction.APPEND
+                    ):
+                        result[spec.dest] = (
+                            typed_values[0] if len(typed_values) == 1 else typed_values
+                        )
+                    else:
+                        result[spec.dest] = typed_values
+                    consumed_indices.update(range(i, new_i))
+                    i = new_i
+            else:
+                # Get the next flagged argument index if it exists
+                next_flagged_index = -1
+                for index, arg in enumerate(args[i:], start=i):
+                    if arg.startswith("-"):
+                        next_flagged_index = index
+                        break
+                if next_flagged_index == -1:
+                    next_flagged_index = len(args)
+
+                args_consumed = self._consume_all_positional_args(
+                    args[i:next_flagged_index],
+                    result,
+                    positional_args,
+                    consumed_positional_indices,
+                )
+                i += args_consumed
+
+        # Required validation
+        for spec in self._arguments:
+            if spec.dest == "help":
+                continue
+            if spec.required and not result.get(spec.dest):
+                raise CommandArgumentError(f"Missing required argument: {spec.dest}")
+
+            if spec.choices and result.get(spec.dest) not in spec.choices:
+                raise CommandArgumentError(
+                    f"Invalid value for {spec.dest}: must be one of {spec.choices}"
+                )
+
+            if isinstance(spec.nargs, int) and spec.nargs > 1:
+                if not isinstance(result.get(spec.dest), list):
+                    raise CommandArgumentError(
+                        f"Invalid value for {spec.dest}: expected a list"
+                    )
+                if spec.action == ArgumentAction.APPEND:
+                    if not isinstance(result[spec.dest], list):
+                        raise CommandArgumentError(
+                            f"Invalid value for {spec.dest}: expected a list"
+                        )
+                    for group in result[spec.dest]:
+                        if len(group) % spec.nargs != 0:
+                            raise CommandArgumentError(
+                                f"Invalid number of values for {spec.dest}: expected a multiple of {spec.nargs}"
+                            )
+                elif spec.action == ArgumentAction.EXTEND:
+                    if not isinstance(result[spec.dest], list):
+                        raise CommandArgumentError(
+                            f"Invalid value for {spec.dest}: expected a list"
+                        )
+                    if len(result[spec.dest]) % spec.nargs != 0:
+                        raise CommandArgumentError(
+                            f"Invalid number of values for {spec.dest}: expected a multiple of {spec.nargs}"
+                        )
+                elif len(result[spec.dest]) != spec.nargs:
+                    raise CommandArgumentError(
+                        f"Invalid number of values for {spec.dest}: expected {spec.nargs}, got {len(result[spec.dest])}"
+                    )
+
+        result.pop("help", None)
+        return result
+
+    def parse_args_split(self, args: list[str]) -> tuple[tuple[Any, ...], dict[str, Any]]:
+        """
+        Returns:
+            tuple[args, kwargs] - Positional arguments in defined order,
+            followed by keyword argument mapping.
+        """
+        parsed = self.parse_args(args)
+        args_list = []
+        kwargs_dict = {}
+        for arg in self._arguments:
+            if arg.dest == "help":
+                continue
+            if arg.positional:
+                args_list.append(parsed[arg.dest])
+            else:
+                kwargs_dict[arg.dest] = parsed[arg.dest]
+        return tuple(args_list), kwargs_dict
+
+    def render_help(self):
+        table = Table(title=f"{self.command_description} Help")
+        table.add_column("Flags")
+        table.add_column("Help")
+        for arg in self._arguments:
+            if arg.dest == "help":
+                continue
+            flag_str = ", ".join(arg.flags) if not arg.positional else arg.dest
+            table.add_row(flag_str, arg.help or "")
+        table.add_section()
+        arg = self.get_argument("help")
+        flag_str = ", ".join(arg.flags) if not arg.positional else arg.dest
+        table.add_row(flag_str, arg.help or "")
+        self.console.print(table)
+
+    def __str__(self) -> str:
+        positional = sum(arg.positional for arg in self._arguments)
+        required = sum(arg.required for arg in self._arguments)
+        return (
+            f"CommandArgumentParser(args={len(self._arguments)}, "
+            f"flags={len(self._flag_map)}, dests={len(self._dest_set)}, "
+            f"required={required}, positional={positional})"
+        )
+
+    def __repr__(self) -> str:
+        return str(self)

falyx/command.py

@@ -18,6 +18,7 @@ in building robust interactive menus.
 """
 from __future__ import annotations
 
+import shlex
 from functools import cached_property
 from typing import Any, Callable
 
@@ -28,6 +29,7 @@ from rich.tree import Tree
 
 from falyx.action.action import Action, ActionGroup, BaseAction, ChainedAction
 from falyx.action.io_action import BaseIOAction
+from falyx.argparse import CommandArgumentParser
 from falyx.context import ExecutionContext
 from falyx.debug import register_debug_hooks
 from falyx.execution_registry import ExecutionRegistry as er
@@ -35,6 +37,7 @@ from falyx.hook_manager import HookManager, HookType
 from falyx.logger import logger
 from falyx.options_manager import OptionsManager
 from falyx.prompt_utils import confirm_async, should_prompt_user
+from falyx.protocols import ArgParserProtocol
 from falyx.retry import RetryPolicy
 from falyx.retry_utils import enable_retries_recursively
 from falyx.signals import CancelSignal
@@ -121,11 +124,24 @@ class Command(BaseModel):
     logging_hooks: bool = False
     requires_input: bool | None = None
     options_manager: OptionsManager = Field(default_factory=OptionsManager)
+    arg_parser: CommandArgumentParser = Field(default_factory=CommandArgumentParser)
+    custom_parser: ArgParserProtocol | None = None
+    custom_help: Callable[[], str | None] | None = None
 
     _context: ExecutionContext | None = PrivateAttr(default=None)
 
     model_config = ConfigDict(arbitrary_types_allowed=True)
 
+    def parse_args(self, raw_args: list[str] | str) -> tuple[tuple, dict]:
+        if self.custom_parser:
+            if isinstance(raw_args, str):
+                raw_args = shlex.split(raw_args)
+            return self.custom_parser(raw_args)
+
+        if isinstance(raw_args, str):
+            raw_args = shlex.split(raw_args)
+        return self.arg_parser.parse_args_split(raw_args)
+
     @field_validator("action", mode="before")
     @classmethod
     def wrap_callable_as_async(cls, action: Any) -> Any:
@@ -137,6 +153,9 @@ class Command(BaseModel):
 
     def model_post_init(self, _: Any) -> None:
         """Post-initialization to set up the action and hooks."""
+        if isinstance(self.arg_parser, CommandArgumentParser):
+            self.arg_parser.command_description = self.description
+
         if self.retry and isinstance(self.action, Action):
             self.action.enable_retry()
         elif self.retry_policy and isinstance(self.action, Action):
@@ -269,6 +288,18 @@ class Command(BaseModel):
         if self._context:
             self._context.log_summary()
 
+    def show_help(self) -> bool:
+        """Display the help message for the command."""
+        if self.custom_help:
+            output = self.custom_help()
+            if output:
+                console.print(output)
+            return True
+        if isinstance(self.arg_parser, CommandArgumentParser):
+            self.arg_parser.render_help()
+            return True
+        return False
+
     async def preview(self) -> None:
         label = f"[{OneColors.GREEN_b}]Command:[/] '{self.key}' — {self.description}"
 

falyx/exceptions.py

@@ -28,3 +28,7 @@ class CircuitBreakerOpen(FalyxError):
 
 class EmptyChainError(FalyxError):
     """Exception raised when the chain is empty."""
+
+
+class CommandArgumentError(FalyxError):
+    """Exception raised when there is an error in the command argument parser."""

falyx/falyx.py

@@ -23,6 +23,7 @@ from __future__ import annotations
 
 import asyncio
 import logging
+import shlex
 import sys
 from argparse import Namespace
 from difflib import get_close_matches
@@ -34,7 +35,8 @@ from prompt_toolkit import PromptSession
 from prompt_toolkit.completion import WordCompleter
 from prompt_toolkit.formatted_text import AnyFormattedText
 from prompt_toolkit.key_binding import KeyBindings
-from prompt_toolkit.validation import Validator
+from prompt_toolkit.patch_stdout import patch_stdout
+from prompt_toolkit.validation import ValidationError, Validator
 from rich import box
 from rich.console import Console
 from rich.markdown import Markdown
@@ -47,6 +49,7 @@ from falyx.context import ExecutionContext
 from falyx.debug import log_after, log_before, log_error, log_success
 from falyx.exceptions import (
     CommandAlreadyExistsError,
+    CommandArgumentError,
     FalyxError,
     InvalidActionError,
     NotAFalyxError,
@@ -57,19 +60,39 @@ from falyx.logger import logger
 from falyx.options_manager import OptionsManager
 from falyx.parsers import get_arg_parsers
 from falyx.retry import RetryPolicy
-from falyx.signals import BackSignal, CancelSignal, QuitSignal
+from falyx.signals import BackSignal, CancelSignal, HelpSignal, QuitSignal
 from falyx.themes import OneColors, get_nord_theme
 from falyx.utils import CaseInsensitiveDict, _noop, chunks, get_program_invocation
 from falyx.version import __version__
 
 
-class FalyxMode(str, Enum):
+class FalyxMode(Enum):
     MENU = "menu"
     RUN = "run"
     PREVIEW = "preview"
     RUN_ALL = "run-all"
 
 
+class CommandValidator(Validator):
+    """Validator to check if the input is a valid command or toggle key."""
+
+    def __init__(self, falyx: Falyx, error_message: str) -> None:
+        super().__init__()
+        self.falyx = falyx
+        self.error_message = error_message
+
+    def validate(self, document) -> None:
+        text = document.text
+        is_preview, choice, _, __ = self.falyx.get_command(text, from_validate=True)
+        if is_preview:
+            return None
+        if not choice:
+            raise ValidationError(
+                message=self.error_message,
+                cursor_position=document.get_end_of_document_position(),
+            )
+
+
 class Falyx:
     """
     Main menu controller for Falyx CLI applications.
@@ -325,7 +348,7 @@ class Falyx:
             keys.extend(cmd.aliases)
         return WordCompleter(keys, ignore_case=True)
 
-    def _get_validator(self) -> Validator:
+    def _get_validator_error_message(self) -> str:
         """Validator to check if the input is a valid command or toggle key."""
         keys = {self.exit_command.key.upper()}
         keys.update({alias.upper() for alias in self.exit_command.aliases})
@@ -354,18 +377,7 @@ class Falyx:
         if toggle_keys:
             message_lines.append(f"  Toggles: {toggles_str}")
         error_message = " ".join(message_lines)
-
-        def validator(text):
-            is_preview, choice = self.get_command(text, from_validate=True)
-            if is_preview and choice is None:
-                return True
-            return bool(choice)
-
-        return Validator.from_callable(
-            validator,
-            error_message=error_message,
-            move_cursor_to_end=True,
-        )
+        return error_message
 
     def _invalidate_prompt_session_cache(self):
         """Forces the prompt session to be recreated on the next access."""
@@ -428,9 +440,10 @@ class Falyx:
                 multiline=False,
                 completer=self._get_completer(),
                 reserve_space_for_menu=1,
-                validator=self._get_validator(),
+                validator=CommandValidator(self, self._get_validator_error_message()),
                 bottom_toolbar=self._get_bottom_bar_render(),
                 key_bindings=self.key_bindings,
+                validate_while_typing=False,
             )
         return self._prompt_session
 
@@ -694,32 +707,52 @@ class Falyx:
         return False, input_str.strip()
 
     def get_command(
-        self, choice: str, from_validate=False
-    ) -> tuple[bool, Command | None]:
+        self, raw_choices: str, from_validate=False
+    ) -> tuple[bool, Command | None, tuple, dict[str, Any]]:
         """
         Returns the selected command based on user input.
         Supports keys, aliases, and abbreviations.
         """
+        args = ()
+        kwargs: dict[str, Any] = {}
+        choice, *input_args = shlex.split(raw_choices)
         is_preview, choice = self.parse_preview_command(choice)
         if is_preview and not choice and self.help_command:
             is_preview = False
             choice = "?"
         elif is_preview and not choice:
+            # No help command enabled
             if not from_validate:
                 self.console.print(
                     f"[{OneColors.DARK_RED}]❌ You must enter a command for preview mode."
                 )
-            return is_preview, None
+            return is_preview, None, args, kwargs
 
         choice = choice.upper()
         name_map = self._name_map
-
         if choice in name_map:
-            return is_preview, name_map[choice]
+            if not from_validate:
+                logger.info("Command '%s' selected.", choice)
+            if input_args and name_map[choice].arg_parser:
+                try:
+                    args, kwargs = name_map[choice].parse_args(input_args)
+                except CommandArgumentError as error:
+                    if not from_validate:
+                        if not name_map[choice].show_help():
+                            self.console.print(
+                                f"[{OneColors.DARK_RED}]❌ Invalid arguments for '{choice}': {error}"
+                            )
+                    else:
+                        name_map[choice].show_help()
+                        raise ValidationError(
+                            message=str(error), cursor_position=len(raw_choices)
+                        )
+                    return is_preview, None, args, kwargs
+            return is_preview, name_map[choice], args, kwargs
 
         prefix_matches = [cmd for key, cmd in name_map.items() if key.startswith(choice)]
         if len(prefix_matches) == 1:
-            return is_preview, prefix_matches[0]
+            return is_preview, prefix_matches[0], args, kwargs
 
         fuzzy_matches = get_close_matches(choice, list(name_map.keys()), n=3, cutoff=0.7)
         if fuzzy_matches:
@@ -736,7 +769,7 @@ class Falyx:
                 self.console.print(
                     f"[{OneColors.LIGHT_YELLOW}]⚠️ Unknown command '{choice}'[/]"
                 )
-        return is_preview, None
+        return is_preview, None, args, kwargs
 
     def _create_context(self, selected_command: Command) -> ExecutionContext:
         """Creates a context dictionary for the selected command."""
@@ -759,8 +792,9 @@ class Falyx:
 
     async def process_command(self) -> bool:
         """Processes the action of the selected command."""
-        choice = await self.prompt_session.prompt_async()
-        is_preview, selected_command = self.get_command(choice)
+        with patch_stdout(raw=True):
+            choice = await self.prompt_session.prompt_async()
+        is_preview, selected_command, args, kwargs = self.get_command(choice)
         if not selected_command:
             logger.info("Invalid command '%s'.", choice)
             return True
@@ -789,8 +823,8 @@ class Falyx:
         context.start_timer()
         try:
             await self.hooks.trigger(HookType.BEFORE, context)
-
-            result = await selected_command()
+            print(args, kwargs)
+            result = await selected_command(*args, **kwargs)
             context.result = result
             await self.hooks.trigger(HookType.ON_SUCCESS, context)
         except Exception as error:
@@ -803,10 +837,18 @@ class Falyx:
             await self.hooks.trigger(HookType.ON_TEARDOWN, context)
         return True
 
-    async def run_key(self, command_key: str, return_context: bool = False) -> Any:
+    async def run_key(
+        self,
+        command_key: str,
+        return_context: bool = False,
+        args: tuple = (),
+        kwargs: dict[str, Any] | None = None,
+    ) -> Any:
         """Run a command by key without displaying the menu (non-interactive mode)."""
         self.debug_hooks()
-        is_preview, selected_command = self.get_command(command_key)
+        is_preview, selected_command, _, __ = self.get_command(command_key)
+        kwargs = kwargs or {}
+
         self.last_run_command = selected_command
 
         if not selected_command:
@@ -827,7 +869,7 @@ class Falyx:
         context.start_timer()
         try:
             await self.hooks.trigger(HookType.BEFORE, context)
-            result = await selected_command()
+            result = await selected_command(*args, **kwargs)
             context.result = result
 
             await self.hooks.trigger(HookType.ON_SUCCESS, context)
@@ -922,6 +964,8 @@ class Falyx:
                     logger.info("BackSignal received.")
                 except CancelSignal:
                     logger.info("CancelSignal received.")
+                except HelpSignal:
+                    logger.info("HelpSignal received.")
         finally:
             logger.info("Exiting menu: %s", self.get_title())
             if self.exit_message:
@@ -956,7 +1000,7 @@ class Falyx:
 
         if self.cli_args.command == "preview":
             self.mode = FalyxMode.PREVIEW
-            _, command = self.get_command(self.cli_args.name)
+            _, command, args, kwargs = self.get_command(self.cli_args.name)
             if not command:
                 self.console.print(
                     f"[{OneColors.DARK_RED}]❌ Command '{self.cli_args.name}' not found."
@@ -970,7 +1014,7 @@ class Falyx:
 
         if self.cli_args.command == "run":
             self.mode = FalyxMode.RUN
-            is_preview, command = self.get_command(self.cli_args.name)
+            is_preview, command, _, __ = self.get_command(self.cli_args.name)
             if is_preview:
                 if command is None:
                     sys.exit(1)
@@ -981,7 +1025,11 @@ class Falyx:
                 sys.exit(1)
             self._set_retry_policy(command)
             try:
-                await self.run_key(self.cli_args.name)
+                args, kwargs = command.parse_args(self.cli_args.command_args)
+            except HelpSignal:
+                sys.exit(0)
+            try:
+                await self.run_key(self.cli_args.name, args=args, kwargs=kwargs)
             except FalyxError as error:
                 self.console.print(f"[{OneColors.DARK_RED}]❌ Error: {error}[/]")
                 sys.exit(1)

falyx/parsers.py

@@ -2,7 +2,7 @@
 """parsers.py
 This module contains the argument parsers used for the Falyx CLI.
 """
-from argparse import ArgumentParser, Namespace, _SubParsersAction
+from argparse import REMAINDER, ArgumentParser, Namespace, _SubParsersAction
 from dataclasses import asdict, dataclass
 from typing import Any, Sequence
 
@@ -114,6 +114,12 @@ def get_arg_parsers(
         help="Skip confirmation prompts",
     )
 
+    run_group.add_argument(
+        "command_args",
+        nargs=REMAINDER,
+        help="Arguments to pass to the command (if applicable)",
+    )
+
     run_all_parser = subparsers.add_parser(
         "run-all", help="Run all commands with a given tag"
     )

falyx/protocols.py

@@ -2,10 +2,16 @@
 """protocols.py"""
 from __future__ import annotations
 
-from typing import Any, Awaitable, Protocol
+from typing import Any, Awaitable, Protocol, runtime_checkable
 
 from falyx.action.action import BaseAction
 
 
+@runtime_checkable
 class ActionFactoryProtocol(Protocol):
     async def __call__(self, *args: Any, **kwargs: Any) -> Awaitable[BaseAction]: ...
+
+
+@runtime_checkable
+class ArgParserProtocol(Protocol):
+    def __call__(self, args: list[str]) -> tuple[tuple, dict]: ...

falyx/signals.py

@@ -29,3 +29,10 @@ class CancelSignal(FlowSignal):
 
     def __init__(self, message: str = "Cancel signal received."):
         super().__init__(message)
+
+
+class HelpSignal(FlowSignal):
+    """Raised to display help information."""
+
+    def __init__(self, message: str = "Help signal received."):
+        super().__init__(message)

falyx/version.py

@@ -1 +1 @@
-__version__ = "0.1.27"
+__version__ = "0.1.28"

{falyx-0.1.27.dist-info → falyx-0.1.28.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: falyx
-Version: 0.1.27
+Version: 0.1.28
 Summary: Reliable and introspectable async CLI action framework.
 License: MIT
 Author: Roland Thomas Jr

{falyx-0.1.27.dist-info → falyx-0.1.28.dist-info}/RECORD

@@ -12,36 +12,37 @@ falyx/action/selection_action.py,sha256=22rF7UqRrQAMjGIheDqAbUizVMBg9aCl9e4VOLLZ
 falyx/action/signal_action.py,sha256=5UMqvzy7fBnLANGwYUWoe1VRhrr7e-yOVeLdOnCBiJo,1350
 falyx/action/types.py,sha256=iVD-bHm1GRXOTIlHOeT_KcDBRZm4Hz5Xzl_BOalvEf4,961
 falyx/action/user_input_action.py,sha256=LSTzC_3TfsfXdz-qV3GlOIGpZWAOgO9J5DnNsHO7ee8,3398
+falyx/argparse.py,sha256=kI_tLYD6KOiWvXEHEvOi8bprx5sQm9KTrgens2_nWKU,24498
 falyx/bottom_bar.py,sha256=iWxgOKWgn5YmREeZBuGA50FzqzEfz1-Vnqm0V_fhldc,7383
-falyx/command.py,sha256=CeleZJ039996d6qn895JXagLeh7gMZltx7jABecjSXY,12224
+falyx/command.py,sha256=Vr5YHehZB6GavBbHe9diNbdeXNWfnWTkuDZ-NfymcFo,13437
 falyx/config.py,sha256=8dkQfL-Ro-vWw1AcO2fD1PGZ92Cyfnwl885ZlpLkp4Y,9636
 falyx/config_schema.py,sha256=j5GQuHVlaU-VLxLF9t8idZRjqOP9MIKp1hyd9NhpAGU,3124
 falyx/context.py,sha256=FNF-IS7RMDxel2l3kskEqQImZ0mLO6zvGw_xC9cIzgI,10338
 falyx/debug.py,sha256=oWWTLOF8elrx_RGZ1G4pbzfFr46FjB0woFXpVU2wmjU,1567
-falyx/exceptions.py,sha256=Qxp6UScZWEyno-6Lgksrv3s9iwjbr2U-d6hun-_xpc0,798
+falyx/exceptions.py,sha256=kK9k1v7LVNjJSwYztRa9Krhr3ZOI-6Htq2ZjlYICPKg,922
 falyx/execution_registry.py,sha256=rctsz0mrIHPToLZqylblVjDdKWdq1x_JBc8GwMP5sJ8,4710
-falyx/falyx.py,sha256=ECL6nDgqxS0s8lzOlMnBOSqwZEsLN0kYzeBCs0lUsYI,40860
+falyx/falyx.py,sha256=3OrmQ0p7ZOpjLaH5mqTYVEZ96KKTygSLYlPqg3eH5eM,43061
 falyx/hook_manager.py,sha256=GuGxVVz9FXrU39Tk220QcsLsMXeut7ZDkGW3hU9GcwQ,2952
 falyx/hooks.py,sha256=IV2nbj5FjY2m3_L7x4mYBnaRDG45E8tWQU90i4butlw,2940
 falyx/init.py,sha256=abcSlPmxVeByLIHdUkNjqtO_tEkO3ApC6f9WbxsSEWg,3393
 falyx/logger.py,sha256=1Mfb_vJFJ1tQwziuyU2p-cSMi2Js8N2byniFEnI6vOQ,132
 falyx/menu.py,sha256=faxGgocqQYY6HtzVbenHaFj8YqsmycBEyziC8Ahzqjo,2870
 falyx/options_manager.py,sha256=dFAnQw543tQ6Xupvh1PwBrhiSWlSACHw8K-sHP_lUh4,2842
-falyx/parsers.py,sha256=hxrBouQEqdgk6aWzNa7UwTg7u55vJffSEUUTiiQoI0U,5602
+falyx/parsers.py,sha256=KsDFEmJLM86d2X4Kh4SHA9mBbUk351NjLhhFYzQkaPk,5762
 falyx/prompt_utils.py,sha256=qgk0bXs7mwzflqzWyFhEOTpKQ_ZtMIqGhKeg-ocwNnE,1542
-falyx/protocols.py,sha256=ejSz18D8Qg63ONdgwbvn2YanKK9bGF0e3Bjxh9y3Buc,334
+falyx/protocols.py,sha256=mesdq5CjPF_5Kyu7Evwr6qMT71tUHlw0SjjtmnggTZw,495
 falyx/retry.py,sha256=UUzY6FlKobr84Afw7yJO9rj3AIQepDk2fcWs6_1gi6Q,3788
 falyx/retry_utils.py,sha256=EAzc-ECTu8AxKkmlw28ioOW9y-Y9tLQ0KasvSkBRYgs,694
 falyx/selection.py,sha256=l2LLISqgP8xfHdcTAEbTTqs_Bae4-LVUKMN7VQH7tM0,10731
-falyx/signals.py,sha256=PGlc0Cm8DfUB3lCf58u_kwTwm2XUEFQ2joFq0Qc_GXI,906
+falyx/signals.py,sha256=Y_neFXpfHs7qY0syw9XcfR9WeAGRcRw1nG_2L1JJqKE,1083
 falyx/tagged_table.py,sha256=4SV-SdXFrAhy1JNToeBCvyxT-iWVf6cWY7XETTys4n8,1067
 falyx/themes/__init__.py,sha256=1CZhEUCin9cUk8IGYBUFkVvdHRNNJBEFXccHwpUKZCA,284
 falyx/themes/colors.py,sha256=4aaeAHJetmeNInI0Zytg4E3YqKfPFelpf04vtjSvsS8,19776
 falyx/utils.py,sha256=u3puR4Bh-unNBw9a0V9sw7PDTIzRaNLolap0oz5bVIk,6718
 falyx/validators.py,sha256=t5iyzVpY8tdC4rfhr4isEfWpD5gNTzjeX_Hbi_Uq6sA,1328
-falyx/version.py,sha256=vEF032D64gj-9WJp4kp0yS1eFIq4XHIqJr91sJJNwWg,23
-falyx-0.1.27.dist-info/LICENSE,sha256=B0yqgaHuSdhN7T3OBmgQSiDTy8HqT5Oe_dLypRe4Ra4,1073
-falyx-0.1.27.dist-info/METADATA,sha256=rs1IR_MPVQKge3QAZjwHUbh3sOfIutI5qckcMIaVR5w,5521
-falyx-0.1.27.dist-info/WHEEL,sha256=fGIA9gx4Qxk2KDKeNJCbOEwSrmLtjWCwzBz351GyrPQ,88
-falyx-0.1.27.dist-info/entry_points.txt,sha256=j8owOSl2j1Ss8DtGMnKfgehKaolqnIPhVFHaUBLUnMs,45
-falyx-0.1.27.dist-info/RECORD,,
+falyx/version.py,sha256=MWZDdAHrdUZS0c3VlLqX4O1eaxPodI7irMtEvknKQ94,23
+falyx-0.1.28.dist-info/LICENSE,sha256=B0yqgaHuSdhN7T3OBmgQSiDTy8HqT5Oe_dLypRe4Ra4,1073
+falyx-0.1.28.dist-info/METADATA,sha256=n-VK44OFgjFxyRn1-LdysM1ciDF8RKxlKfAy_0Yz_Zc,5521
+falyx-0.1.28.dist-info/WHEEL,sha256=fGIA9gx4Qxk2KDKeNJCbOEwSrmLtjWCwzBz351GyrPQ,88
+falyx-0.1.28.dist-info/entry_points.txt,sha256=j8owOSl2j1Ss8DtGMnKfgehKaolqnIPhVFHaUBLUnMs,45
+falyx-0.1.28.dist-info/RECORD,,