115 lines
4.0 KiB
Markdown
115 lines
4.0 KiB
Markdown
---
|
||
author: "Roland Thomas Jr"
|
||
title: "Falyx"
|
||
date: "2025-04-15"
|
||
description: ""
|
||
tags: ["post", "falyx", "cli"]
|
||
ShowToc: false
|
||
ShowBreadCrumbs: true
|
||
---
|
||
|
||
## 🛡️ Introducing Falyx: A Resilient CLI Framework for Modern Workflows
|
||
In the ever-evolving landscape of software development, tools that offer resilience, clarity, and introspection are invaluable.
|
||
|
||
Enter **Falyx**—a robust, asynchronous command-line interface (CLI) framework designed to streamline and fortify your workflows.
|
||
|
||
### ⚙️ What is Falyx?
|
||
Falyx is a Python-based CLI framework that empowers developers to build **modular**, **fault-tolerant** command-line applications. Inspired by the discipline and strength of a phalanx, Falyx ensures that each component of your workflow stands firm — even in the face of failure.
|
||
|
||
### 🚀 Key Features
|
||
|
||
- **Modular Action Chaining** Compose complex workflows by chaining together discrete actions, each with its own context and lifecycle.
|
||
- **Built-in Retry Mechanism** – Handle flaky or transient failures with configurable retry policies, including exponential backoff.
|
||
- **Lifecycle Hooks** – Inject logic at every stage: `before`, `after`, `on_success`, `on_error`, and `on_teardown`.
|
||
- **Execution Tracing** – Built-in logging, result tracking, and timing for complete visibility.
|
||
- **Async-First Design** – Built on `asyncio`, with optional multiprocessing via `ProcessAction`.
|
||
- **Extensible CLI Menus** – Create interactive or headless menus using `prompt_toolkit` and `rich`, with support for history, tags, toggle states, and more.
|
||
|
||
### 🧪 Getting Started
|
||
|
||
Here's a simple example to illustrate how Falyx can be used to build a resilient CLI application:
|
||
|
||
```python
|
||
import asyncio
|
||
import random
|
||
from falyx import Falyx, Action, ChainedAction
|
||
|
||
# Define a flaky asynchronous step
|
||
async def flaky_step():
|
||
await asyncio.sleep(0.2)
|
||
if random.random() < 0.5:
|
||
raise RuntimeError("Random failure!")
|
||
return "ok"
|
||
|
||
# Create actions with retry enabled
|
||
step1 = Action(name="step_1", action=flaky_step, retry=True)
|
||
step2 = Action(name="step_2", action=flaky_step, retry=True)
|
||
|
||
# Chain the actions together
|
||
chain = ChainedAction(name="my_pipeline", actions=[step1, step2])
|
||
|
||
# Set up the CLI menu
|
||
falyx = Falyx("🚀 Falyx Demo")
|
||
falyx.add_command(
|
||
key="R",
|
||
description="Run My Pipeline",
|
||
action=chain,
|
||
logging_hooks=True,
|
||
preview_before_confirm=True,
|
||
confirm=True,
|
||
)
|
||
|
||
# Entry point
|
||
if __name__ == "__main__":
|
||
asyncio.run(falyx.run())
|
||
```
|
||
|
||
When run, this script presents an interactive CLI menu with built-in preview, confirmation, and retry handling.
|
||
|
||
```bash
|
||
❯ python simple.py
|
||
🚀 Falyx Demo
|
||
|
||
[R] Run My Pipeline
|
||
[Y] History [Q] Exit
|
||
|
||
>
|
||
```
|
||
|
||
Or run headlessly using intuitive CLI arguments:
|
||
|
||
```bash
|
||
❯ python simple.py run R
|
||
Command: 'R' — Run My Pipeline
|
||
└── ⛓ ChainedAction 'my_pipeline'
|
||
├── ⚙ Action 'step_1'
|
||
│ ↻ Retries: 3x, delay 1.0s, backoff 2.0x
|
||
└── ⚙ Action 'step_2'
|
||
↻ Retries: 3x, delay 1.0s, backoff 2.0x
|
||
Confirm execution of R — Run My Pipeline (calls `my_pipeline`) [Y/n] y
|
||
[2025-04-15 22:03:57] WARNING ⚠️ Retry attempt 1/3 failed due to 'Random failure!'.
|
||
✅ Result: ['ok', 'ok']
|
||
```
|
||
|
||
### 📈 Real-World Applications
|
||
|
||
Falyx is particularly well-suited for:
|
||
|
||
- **Automation Script**: Build resilient tools that self-heal from transient errors.
|
||
- **Data Pipelines**: Orchestrate complex data flows with retry logic and full observability.
|
||
- **Deployment Tooling**: Create safe deploys with preview, rollback, and confirmation baked in.
|
||
|
||
### 📚 Learn More
|
||
|
||
- 📖 [Source Code on GitHub](https://github.com/rolandtjr/falyx)
|
||
|
||
---
|
||
|
||
Falyx was designed for developers who don’t just want CLI tools to **run** — they want them to **recover**, **report**, and **adapt**.
|
||
|
||
If that sounds like you, give it a spin and start building resilient command flows today.
|
||
|
||
> _"Like a phalanx: organized, resilient, and reliable."_ ⚔️
|
||
|
||
---
|