falyx 0.1.57__tar.gz → 0.1.59__tar.gz

{falyx-0.1.57 → falyx-0.1.59}/PKG-INFO

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

{falyx-0.1.57 → falyx-0.1.59}/falyx/action/confirm_action.py

@@ -56,13 +56,14 @@ class ConfirmAction(BaseAction):
         prompt_session (PromptSession | None): The session to use for input.
         confirm (bool): Whether to prompt the user for confirmation.
         word (str): The word to type for TYPE_WORD confirmation.
-        return_last_result (bool): Whether to return the last result of the action.
+        return_last_result (bool): Whether to return the last result of the action
+                                   instead of a boolean.
     """
 
     def __init__(
         self,
         name: str,
-        message: str = "Continue",
+        message: str = "Confirm?",
         confirm_type: ConfirmType | str = ConfirmType.YES_NO,
         prompt_session: PromptSession | None = None,
         confirm: bool = True,
@@ -114,16 +115,19 @@ class ConfirmAction(BaseAction):
                     session=self.prompt_session,
                 )
             case ConfirmType.YES_NO_CANCEL:
+                error_message = "Enter 'Y', 'y' to confirm, 'N', 'n' to decline, or 'C', 'c' to abort."
                 answer = await self.prompt_session.prompt_async(
-                    f"❓ {self.message} ([Y]es, [N]o, or [C]ancel to abort): ",
-                    validator=words_validator(["Y", "N", "C"]),
+                    f"❓ {self.message} [Y]es, [N]o, or [C]ancel to abort > ",
+                    validator=words_validator(
+                        ["Y", "N", "C"], error_message=error_message
+                    ),
                 )
                 if answer.upper() == "C":
                     raise CancelSignal(f"Action '{self.name}' was cancelled by the user.")
                 return answer.upper() == "Y"
             case ConfirmType.TYPE_WORD:
                 answer = await self.prompt_session.prompt_async(
-                    f"❓ {self.message} (type '{self.word}' to confirm or N/n): ",
+                    f"❓ {self.message} [{self.word}] to confirm or [N/n] > ",
                     validator=word_validator(self.word),
                 )
                 return answer.upper().strip() != "N"
@@ -138,9 +142,10 @@ class ConfirmAction(BaseAction):
                     raise CancelSignal(f"Action '{self.name}' was cancelled by the user.")
                 return answer
             case ConfirmType.OK_CANCEL:
+                error_message = "Enter 'O', 'o' to confirm or 'C', 'c' to abort."
                 answer = await self.prompt_session.prompt_async(
-                    f"❓ {self.message} ([O]k to continue, [C]ancel to abort): ",
-                    validator=words_validator(["O", "C"]),
+                    f"❓ {self.message} [O]k to confirm, [C]ancel to abort > ",
+                    validator=words_validator(["O", "C"], error_message=error_message),
                 )
                 if answer.upper() == "C":
                     raise CancelSignal(f"Action '{self.name}' was cancelled by the user.")
@@ -213,5 +218,5 @@ class ConfirmAction(BaseAction):
     def __str__(self) -> str:
         return (
             f"ConfirmAction(name={self.name}, message={self.message}, "
-            f"confirm_type={self.confirm_type})"
+            f"confirm_type={self.confirm_type}, return_last_result={self.return_last_result})"
         )

{falyx-0.1.57 → falyx-0.1.59}/falyx/action/save_file_action.py

@@ -36,9 +36,11 @@ class SaveFileAction(BaseAction):
         file_path: str,
         file_type: FileType | str = FileType.TEXT,
         mode: Literal["w", "a"] = "w",
-        inject_last_result: bool = True,
-        inject_into: str = "data",
+        data: Any = None,
         overwrite: bool = True,
+        create_dirs: bool = True,
+        inject_last_result: bool = False,
+        inject_into: str = "data",
     ):
         """
         SaveFileAction allows saving data to a file.
@@ -47,17 +49,22 @@ class SaveFileAction(BaseAction):
             name (str): Name of the action.
             file_path (str | Path): Path to the file where data will be saved.
             file_type (FileType | str): Format to write to (e.g. TEXT, JSON, YAML).
+            mode (Literal["w", "a"]): File mode (default: "w").
+            data (Any): Data to be saved (if not using inject_last_result).
+            overwrite (bool): Whether to overwrite the file if it exists.
+            create_dirs (bool): Whether to create parent directories if they do not exist.
             inject_last_result (bool): Whether to inject result from previous action.
             inject_into (str): Kwarg name to inject the last result as.
-            overwrite (bool): Whether to overwrite the file if it exists.
         """
         super().__init__(
             name=name, inject_last_result=inject_last_result, inject_into=inject_into
         )
         self._file_path = self._coerce_file_path(file_path)
         self._file_type = self._coerce_file_type(file_type)
+        self.data = data
         self.overwrite = overwrite
         self.mode = mode
+        self.create_dirs = create_dirs
 
     @property
     def file_path(self) -> Path | None:
@@ -126,6 +133,14 @@ class SaveFileAction(BaseAction):
         elif self.file_path.exists() and not self.overwrite:
             raise FileExistsError(f"File already exists: {self.file_path}")
 
+        if self.file_path.parent and not self.file_path.parent.exists():
+            if self.create_dirs:
+                self.file_path.parent.mkdir(parents=True, exist_ok=True)
+            else:
+                raise FileNotFoundError(
+                    f"Directory does not exist: {self.file_path.parent}"
+                )
+
         try:
             if self.file_type == FileType.TEXT:
                 self.file_path.write_text(data, encoding="UTF-8")
@@ -175,7 +190,7 @@ class SaveFileAction(BaseAction):
 
     async def _run(self, *args, **kwargs):
         combined_kwargs = self._maybe_inject_last_result(kwargs)
-        data = combined_kwargs.get(self.inject_into)
+        data = self.data or combined_kwargs.get(self.inject_into)
 
         context = ExecutionContext(
             name=self.name, args=args, kwargs=combined_kwargs, action=self

{falyx-0.1.57 → falyx-0.1.59}/falyx/action/signal_action.py

@@ -14,7 +14,7 @@ class SignalAction(Action):
     Useful for exiting a menu, going back, or halting execution gracefully.
     """
 
-    def __init__(self, name: str, signal: Exception):
+    def __init__(self, name: str, signal: FlowSignal):
         self.signal = signal
         super().__init__(name, action=self.raise_signal)
 

{falyx-0.1.57 → falyx-0.1.59}/falyx/bottom_bar.py

@@ -5,6 +5,7 @@ from typing import Any, Callable
 
 from prompt_toolkit.formatted_text import HTML, merge_formatted_text
 from prompt_toolkit.key_binding import KeyBindings
+from rich.console import Console
 
 from falyx.console import console
 from falyx.options_manager import OptionsManager

{falyx-0.1.57 → falyx-0.1.59}/falyx/falyx.py

@@ -1,7 +1,5 @@
 # Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
-"""falyx.py
-
-Main class for constructing and running Falyx CLI menus.
+"""Main class for constructing and running Falyx CLI menus.
 
 Falyx provides a structured, customizable interactive menu system
 for running commands, actions, and workflows. It supports:

{falyx-0.1.57 → falyx-0.1.59}/falyx/parser/argument.py

@@ -9,22 +9,37 @@ from falyx.parser.argument_action import ArgumentAction
 
 @dataclass
 class Argument:
-    """Represents a command-line argument."""
+    """
+    Represents a command-line argument.
+
+    Attributes:
+        flags (tuple[str, ...]): Short and long flags for the argument.
+        dest (str): The destination name for the argument.
+        action (ArgumentAction): The action to be taken when the argument is encountered.
+        type (Any): The type of the argument (e.g., str, int, float) or a callable that converts the argument value.
+        default (Any): The default value if the argument is not provided.
+        choices (list[str] | None): A list of valid choices for the argument.
+        required (bool): True if the argument is required, False otherwise.
+        help (str): Help text for the argument.
+        nargs (int | str | None): Number of arguments expected. Can be an int, '?', '*', '+', or None.
+        positional (bool): True if the argument is positional (no leading - or -- in flags), False otherwise.
+        resolver (BaseAction | None):
+            An action object that resolves the argument, if applicable.
+        lazy_resolver (bool): True if the resolver should be called lazily, False otherwise
+    """
 
     flags: tuple[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 | None = None  # int, '?', '*', '+', None
-    positional: bool = False  # True if no leading - or -- in flags
-    resolver: BaseAction | None = None  # Action object for the argument
-    lazy_resolver: bool = False  # True if resolver should be called lazily
+    dest: str
+    action: ArgumentAction = ArgumentAction.STORE
+    type: Any = str
+    default: Any = None
+    choices: list[str] | None = None
+    required: bool = False
+    help: str = ""
+    nargs: int | str | None = None
+    positional: bool = False
+    resolver: BaseAction | None = None
+    lazy_resolver: bool = False
 
     def get_positional_text(self) -> str:
         """Get the positional text for the argument."""

{falyx-0.1.57 → falyx-0.1.59}/falyx/parser/parsers.py

@@ -56,6 +56,39 @@ def get_root_parser(
     allow_abbrev: bool = True,
     exit_on_error: bool = True,
 ) -> ArgumentParser:
+    """
+    Construct the root-level ArgumentParser for the Falyx CLI.
+
+    This parser handles global arguments shared across subcommands and can serve
+    as the base parser for the Falyx CLI or standalone applications. It includes
+    options for verbosity, debug logging, and version output.
+
+    Args:
+        prog (str | None): Name of the program (e.g., 'falyx').
+        usage (str | None): Optional custom usage string.
+        description (str | None): Description shown in the CLI help.
+        epilog (str | None): Message displayed at the end of help output.
+        parents (Sequence[ArgumentParser] | None): Optional parent parsers.
+        prefix_chars (str): Characters to denote optional arguments (default: "-").
+        fromfile_prefix_chars (str | None): Prefix to indicate argument file input.
+        argument_default (Any): Global default value for arguments.
+        conflict_handler (str): Strategy to resolve conflicting argument names.
+        add_help (bool): Whether to include help (`-h/--help`) in this parser.
+        allow_abbrev (bool): Allow abbreviated long options.
+        exit_on_error (bool): Exit immediately on error or raise an exception.
+
+    Returns:
+        ArgumentParser: The root parser with global options attached.
+
+    Notes:
+        ```
+        Includes the following arguments:
+            --never-prompt       : Run in non-interactive mode.
+            -v / --verbose       : Enable debug logging.
+            --debug-hooks        : Enable hook lifecycle debug logs.
+            --version            : Print the Falyx version.
+        ```
+    """
     parser = ArgumentParser(
         prog=prog,
         usage=usage,
@@ -92,7 +125,30 @@ def get_subparsers(
     title: str = "Falyx Commands",
     description: str | None = "Available commands for the Falyx CLI.",
 ) -> _SubParsersAction:
-    """Create and return a subparsers action for the given parser."""
+    """
+    Create and return a subparsers object for registering Falyx CLI subcommands.
+
+    This function adds a `subparsers` block to the given root parser, enabling
+    structured subcommands such as `run`, `run-all`, `preview`, etc.
+
+    Args:
+        parser (ArgumentParser): The root parser to attach the subparsers to.
+        title (str): Title used in help output to group subcommands.
+        description (str | None): Optional text describing the group of subcommands.
+
+    Returns:
+        _SubParsersAction: The subparsers object that can be used to add new CLI subcommands.
+
+    Raises:
+        TypeError: If `parser` is not an instance of `ArgumentParser`.
+
+    Example:
+        ```python
+        >>> parser = get_root_parser()
+        >>> subparsers = get_subparsers(parser, title="Available Commands")
+        >>> subparsers.add_parser("run", help="Run a Falyx command")
+        ```
+    """
     if not isinstance(parser, ArgumentParser):
         raise TypeError("parser must be an instance of ArgumentParser")
     subparsers = parser.add_subparsers(
@@ -122,7 +178,54 @@ def get_arg_parsers(
     root_parser: ArgumentParser | None = None,
     subparsers: _SubParsersAction | None = None,
 ) -> FalyxParsers:
-    """Returns the argument parser for the CLI."""
+    """
+    Create and return the full suite of argument parsers used by the Falyx CLI.
+
+    This function builds the root parser and all subcommand parsers used for structured
+    CLI workflows in Falyx. It supports standard subcommands including `run`, `run-all`,
+    `preview`, `list`, and `version`, and integrates with registered `Command` objects
+    to populate dynamic help and usage documentation.
+
+    Args:
+        prog (str | None): Program name to display in help and usage messages.
+        usage (str | None): Optional usage message to override the default.
+        description (str | None): Description for the CLI root parser.
+        epilog (str | None): Epilog message shown after the help text.
+        parents (Sequence[ArgumentParser] | None): Optional parent parsers.
+        prefix_chars (str): Characters that prefix optional arguments.
+        fromfile_prefix_chars (str | None): Prefix character for reading args from file.
+        argument_default (Any): Default value for arguments if not specified.
+        conflict_handler (str): Strategy for resolving conflicting arguments.
+        add_help (bool): Whether to add the `-h/--help` option to the root parser.
+        allow_abbrev (bool): Whether to allow abbreviated long options.
+        exit_on_error (bool): Whether the parser exits on error or raises.
+        commands (dict[str, Command] | None): Optional dictionary of registered commands
+            to populate help and subcommand descriptions dynamically.
+        root_parser (ArgumentParser | None): Custom root parser to use instead of building one.
+        subparsers (_SubParsersAction | None): Optional existing subparser object to extend.
+
+    Returns:
+        FalyxParsers: A structured container of all parsers, including `run`, `run-all`,
+                      `preview`, `list`, `version`, and the root parser.
+
+    Raises:
+        TypeError: If `root_parser` is not an instance of ArgumentParser or
+                   `subparsers` is not an instance of _SubParsersAction.
+
+    Example:
+        ```python
+        >>> parsers = get_arg_parsers(commands=my_command_dict)
+        >>> args = parsers.root.parse_args()
+        ```
+
+    Notes:
+        - This function integrates dynamic command usage and descriptions if the
+          `commands` argument is provided.
+        - The `run` parser supports additional options for retry logic and confirmation
+          prompts.
+        - The `run-all` parser executes all commands matching a tag.
+        - Use `falyx run ?[COMMAND]` from the CLI to preview a command.
+    """
     if epilog is None:
         epilog = f"Tip: Use '{prog} run ?[COMMAND]' to preview any command from the CLI."
     if root_parser is None:

{falyx-0.1.57 → falyx-0.1.59}/falyx/validators.py

@@ -44,10 +44,12 @@ def yes_no_validator() -> Validator:
             return False
         return True
 
-    return Validator.from_callable(validate, error_message="Enter 'Y' or 'n'.")
+    return Validator.from_callable(validate, error_message="Enter 'Y', 'y' or 'N', 'n'.")
 
 
-def words_validator(keys: Sequence[str] | KeysView[str]) -> Validator:
+def words_validator(
+    keys: Sequence[str] | KeysView[str], error_message: str | None = None
+) -> Validator:
     """Validator for specific word inputs."""
 
     def validate(text: str) -> bool:
@@ -55,9 +57,10 @@ def words_validator(keys: Sequence[str] | KeysView[str]) -> Validator:
             return False
         return True
 
-    return Validator.from_callable(
-        validate, error_message=f"Invalid input. Choices: {{{', '.join(keys)}}}."
-    )
+    if error_message is None:
+        error_message = f"Invalid input. Choices: {{{', '.join(keys)}}}."
+
+    return Validator.from_callable(validate, error_message=error_message)
 
 
 def word_validator(word: str) -> Validator:
@@ -68,7 +71,7 @@ def word_validator(word: str) -> Validator:
             return True
         return text.upper().strip() == word.upper()
 
-    return Validator.from_callable(validate, error_message=f"Enter '{word}' or 'N'.")
+    return Validator.from_callable(validate, error_message=f"Enter '{word}' or 'N', 'n'.")
 
 
 class MultiIndexValidator(Validator):

falyx-0.1.59/falyx/version.py

@@ -0,0 +1 @@
+__version__ = "0.1.59"

{falyx-0.1.57 → falyx-0.1.59}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "falyx"
-version = "0.1.57"
+version = "0.1.59"
 description = "Reliable and introspectable async CLI action framework."
 authors = ["Roland Thomas Jr <roland@rtj.dev>"]
 license = "MIT"

falyx-0.1.57/falyx/version.py

@@ -1 +0,0 @@
-__version__ = "0.1.57"