4.2 KiB

Raw Blame History

⚔️ Falyx

Falyx is a resilient, introspectable CLI framework for building robust, asynchronous command-line workflows with:

✅ Modular action chaining and rollback
🔁 Built-in retry handling
⚙️ Full lifecycle hooks (before, after, success, error, teardown)
📊 Execution tracing, logging, and introspection
🧙‍♂️ Async-first design with Process support
🧩 Extensible CLI menus and customizable output

Built for developers who value clarity, resilience, and visibility in their terminal workflows.

✨ Why Falyx?

Modern CLI tools deserve the same resilience as production systems. Falyx makes it easy to:

Compose workflows using Action, ChainedAction, or ActionGroup
Inject the result of one step into the next (last_result)
Handle flaky operations with retries and exponential backoff
Roll back safely on failure with structured undo logic
Add observability with execution timing, result tracking, and hooks
Run in both interactive or headless (scriptable) modes
Customize output with Rich Tables (grouping, theming, etc.)

🔧 Installation

pip install falyx

Or install from source:

git clone https://github.com/yourname/falyx.git
cd falyx
poetry install

⚡ Quick Example

from falyx import Action, ChainedAction, Menu
from falyx.hooks import RetryHandler, log_success

async def flaky_step():
    import random, asyncio
    await asyncio.sleep(0.2)
    if random.random() < 0.8:
        raise RuntimeError("Random failure!")
    return "ok"

retry = RetryHandler()

step1 = Action("Step 1", flaky_step)
step1.hooks.register("on_error", retry.retry_on_error)

step2 = Action("Step 2", flaky_step)
step2.hooks.register("on_error", retry.retry_on_error)

chain = ChainedAction("My Pipeline", [step1, step2])
chain.hooks.register("on_success", log_success)

menu = Menu(title="🚀 Falyx Demo")
menu.add_command("R", "Run My Pipeline", chain)

if __name__ == "__main__":
    import asyncio
    asyncio.run(menu.run())

📦 Core Features

✅ Async-native Action, ChainedAction, ActionGroup
🔁 Retry policies + exponential backoff
⛓ Rollbacks on chained failures
🎛️ Headless or interactive CLI with argparse and prompt_toolkit
📊 Built-in execution registry, result tracking, and timing
🧠 Supports ProcessAction for CPU-bound workloads
🧩 Custom Table rendering for CLI menu views
🔍 Hook lifecycle: before, on_success, on_error, after, on_teardown

🔍 Execution Trace

[2025-04-14 10:33:22] DEBUG    [Step 1] ⚙ flaky_step()
[2025-04-14 10:33:22] INFO     [Step 1] 🔁 Retrying (1/3) in 1.0s...
[2025-04-14 10:33:23] DEBUG    [Step 1] ✅ Success | Result: ok
[2025-04-14 10:33:23] DEBUG    [My Pipeline] ✅ Result: ['ok', 'ok']

🧩 Components

Component	Purpose
`Action`	Single async task with hook + result injection support
`ChainedAction`	Sequential task runner with rollback
`ActionGroup`	Parallel runner for independent tasks
`ProcessAction`	CPU-bound task in a separate process (multiprocessing)
`Menu`	CLI runner with toggleable prompt or headless mode
`ExecutionContext`	Captures metadata per execution
`HookManager`	Lifecycle hook registration engine

🧠 Design Philosophy

“Like a phalanx: organized, resilient, and reliable.”

Falyx is designed for developers who don’t just want CLI tools to run — they want them to fail meaningfully, recover gracefully, and log clearly.

🛣️ Roadmap

Retry policy DSL (e.g., max_retries=3, backoff="exponential")
Metrics export (Prometheus-style)
Plugin system for menu extensions
Native support for structured logs + log forwarding
Web UI for interactive execution history (maybe!)

🧑‍💼 License

MIT — use it, fork it, improve it. Attribution appreciated!

4.2 KiB Raw Blame History Unescape Escape