roland/falyx
1
1
Fork 0
Code Issues Pull Requests Packages Projects Releases 1 Wiki Activity

1 Release 1 Tag

RSS Feed
  • v0.2.0 efe3f5fd99
    Compare

    Falyx 0.2.0 Stable

    roland released this 2026-06-07 13:07:04 -04:00 | 1 commits to main since this release

    Falyx v0.2.0 Release Notes

    Falyx v0.2.0 is a major runtime and CLI architecture release. It tightens the separation between routing, command parsing, execution, and reusable action composition while making Falyx more reliable as both a full CLI framework and a standalone command runner.

    Highlights

    New routed runtime architecture

    Falyx now has a cleaner execution pipeline:

    • Falyx owns routing across commands and namespaces
    • Command owns command-local argument resolution
    • CommandExecutor owns shared execution lifecycle behavior
    • CommandRunner owns standalone single-command execution
    • OptionsManager owns scoped runtime state

    This makes CLI mode, menu mode, nested namespaces, previews, help rendering, TLDR output, and programmatic execution behave more consistently.

    New CommandExecutor

    CommandExecutor centralizes resolved command execution. It now handles:

    • executor-level lifecycle hooks
    • execution-scoped option overrides
    • retry overrides from parsed execution arguments
    • wrapped or raised error behavior
    • execution summaries
    • consistent command dispatch from both Falyx and CommandRunner

    New CommandRunner

    CommandRunner provides a focused way to run a single Command outside a full Falyx app.

    Useful for:

    • standalone scripts
    • testing one command directly
    • exposing a single command as a CLI entrypoint
    • reusing commands without loading a full menu runtime

    Example pattern:

    runner = CommandRunner.from_command(command)
asyncio.run(runner.cli())

    Command cloning and safe rebinding

    Commands and actions can now be cloned and rebound safely.

    This prevents shared mutable runtime state from leaking when the same command is registered in a Falyx app, wrapped by a CommandRunner, or reused across runtimes.

    Added clone support across major action types, including:

    • Action
    • ActionFactory
    • ActionGroup
    • ChainedAction
    • ConfirmAction
    • FallbackAction
    • HTTPAction
    • LoadFileAction
    • MenuAction
    • ProcessAction
    • ProcessPoolAction
    • PromptMenuAction
    • SaveFileAction
    • SelectFileAction
    • SelectionAction
    • ShellAction
    • SignalAction
    • UserInputAction

    Canonical command construction

    Command.build() is now the central command construction path.

    It normalizes command setup for:

    • hooks
    • retry policy
    • execution options
    • argument parser binding
    • spinner hooks
    • shared OptionsManager
    • custom help, usage, and TLDR renderers

    Command.clone_with_overrides() adds a safe way to derive a bound command from an existing command while changing runtime-specific fields.

    CLI and routing changes

    Native Falyx bootstrap flow

    The package entrypoint now uses Falyx-native commands instead of the old argparse bootstrap flow.

    The built-in bootstrap commands are now modeled as normal Falyx commands:

    • I / init
    • G / init-global

    This makes bootstrap behavior consistent with the rest of the framework.

    Root parser and namespace parser improvements

    Falyx now uses FalyxParser for root/session and namespace-level option parsing.

    This supports:

    • root options such as verbose/debug/never-prompt behavior
    • namespace-level options
    • TLDR registration
    • forwarding command-local help after route boundaries
    • typed defaults and choices
    • option suggestions for completion

    Scoped option namespaces

    Runtime state is now separated into option namespaces.

    Important scopes include:

    • root
    • default
    • execution

    This prevents root/session flags, namespace options, and command execution overrides from clobbering each other.

    Improved nested namespace support

    Nested Falyx instances are now modeled through FalyxNamespace.

    This improves:

    • recursive routing
    • namespace help
    • namespace TLDR examples
    • completion
    • aliases
    • invocation path rendering

    Argument parsing improvements

    Execution options

    Commands can opt into execution-scoped options independently from domain arguments.

    Supported execution option groups include:

    • summary
    • retry
    • confirm

    These can expose flags such as:

    • --summary
    • --retries
    • --retry-delay
    • --retry-backoff
    • --confirm
    • --skip-confirm

    Argument groups and mutually exclusive groups

    CommandArgumentParser now supports grouped arguments and mutually exclusive argument groups.

    This enables cleaner help output and stricter command contracts.

    Better command-local parsing boundary

    Command arguments are now resolved through Command.resolve_args(), which splits parsed input into:

    • positional args
    • keyword args
    • execution args

    Execution args affect runtime behavior and are not passed into the underlying action.

    Better errors

    Parser and routing errors now carry more structured context and hints.

    New or improved error types include:

    • UsageError
    • FalyxOptionError
    • ArgumentParsingError
    • EntryNotFoundError
    • UnrecognizedOptionError
    • InvalidValueError
    • MissingValueError
    • TokenizationError

    print_error() now renders Falyx error hints automatically when available.

    Completion improvements

    Completion is now routing-aware.

    The completer now:

    • resolves partial namespace routes before suggesting command arguments
    • supports nested namespace completions
    • delegates command-local completions to CommandArgumentParser.suggest_next()
    • handles namespace-level option suggestions
    • preserves preview-prefixed input
    • improves longest-common-prefix behavior
    • quotes suggestions containing spaces

    Help, usage, and TLDR improvements

    v0.2.0 adds context-aware invocation rendering through InvocationContext.

    Help, usage, preview, and TLDR output can now preserve the routed command path, including nested namespace paths.

    This is especially useful for deeply nested CLIs where command help should reflect the exact path the user took to reach a command.

    Action and workflow changes

    never_prompt behavior

    Prompt suppression now respects local action-level never_prompt settings while still allowing root/session-level prompt behavior through OptionsManager.

    Concurrent terminology

    ActionGroup and shared context terminology now uses “concurrent” rather than “parallel” where the implementation is asyncio-based.

    File actions

    File-related actions received reliability improvements:

    • LoadFileAction.preview() now awaits structured file loading correctly
    • SelectFileAction now raises parse failures instead of only logging them
    • SaveFileAction now supports Path | str | None file paths and prompt suppression

    HTTP actions

    HTTPAction cloning now preserves request configuration, retry policy, prompt behavior, and structured payloads more safely.

    Examples

    The examples were updated to demonstrate the new runtime shape:

    • argument examples now show namespace options, grouped arguments, mutex groups, TLDR examples, execution summaries, and custom type validation
    • menu demo now demonstrates CommandRunner.from_command()
    • submenu demo now demonstrates nested namespaces, namespace aliases, namespace options, and nested TLDR examples
    • HTTP demo now uses an explicit program name
    • YAML config now includes the argument examples submenu

    Breaking changes

    options renamed to options_manager

    Constructor and runtime APIs now consistently use options_manager.

    Code that passed options= should be updated to options_manager=.

    Old argparse bootstrap path removed

    The package entrypoint no longer builds argparse root/subparser objects for bootstrap commands. Bootstrap commands are now native Falyx commands.

    Runtime modes changed

    FalyxMode.RUN and FalyxMode.RUN_ALL have been replaced by the routed command execution model.

    Use FalyxMode.COMMAND for direct command execution semantics.

    Command parsing now requires a valid parser boundary

    Command.resolve_args() is the canonical parsing boundary. Custom parsing should be supplied through a valid custom parser or CommandArgumentParser.

    Commands registered from existing commands are cloned

    Falyx.add_command_from_command() and CommandRunner.from_command() bind cloned command instances rather than mutating the original command.

    This is safer, but code relying on mutation of the original command after binding may need to be adjusted.

    Migration notes

    Replace options= with options_manager=

    # Before
runner = CommandRunner.from_command(command, options=options)

# After
runner = CommandRunner.from_command(command, options_manager=options)

    Use CommandRunner for standalone commands

    command = flx.add_command(
    key="D",
    description="Deploy",
    action=deploy,
)

runner = CommandRunner.from_command(command)
asyncio.run(runner.cli())

    Prefer execution options over global execution flags

    flx.add_command(
    key="D",
    description="Deploy",
    action=deploy,
    execution_options=["summary", "retry", "confirm"],
)

    Use native Falyx routing for CLI entrypoints

    if __name__ == "__main__":
    asyncio.run(flx.run())

    Summary

    v0.2.0 is a foundation release. It makes Falyx more composable, more predictable, and easier to reason about by clarifying the boundaries between routing, parsing, execution, options, and action reuse.

    Downloads