# Interactive Dispatcher
`interactive-dispatcher` is a small Python library for building menu-based CLI flows.
It maps user input to one or more actions and returns a signal that your app can route.
GitHub: https://github.com/Akhand-Pratap-Tiwari/python-interactive-dispatcher

## Install
```bash
pip install interactive-dispatcher
```

## Quick Example
```python
from interactive_dispatcher import Action, MenuItem, ReturnSignal, interactive_dispatcher

ReturnSignal.register("RESTART")

def greet(name: str) -> str:
    print(f"Hello, {name}!")
    return f"greeted:{name}"

def exit_program() -> str:
    print("Goodbye!")
    return "exited"

menu = [
    MenuItem(
        keys=["greet", "g"],
        description="Greet Alice",
        actions=[Action(function=greet, args=("Alice",))],
        return_signal=ReturnSignal.CONTINUE,
    ),
    MenuItem(
        keys=["restart", "r"],
        description="Restart flow",
        actions=[],
        return_signal=ReturnSignal.RESTART,
    ),
    MenuItem(
        keys=["exit", "e", "q"],
        description="Exit",
        actions=[Action(function=exit_program)],
        return_signal=ReturnSignal.BREAK,
    ),
]

while True:
    results, signal = interactive_dispatcher("Choose an option:", menu)
    print(results, signal)
    if signal == ReturnSignal.BREAK:
        break
```

## API
- `Action`: wraps a callable with positional and keyword arguments.
- `MenuItem`: defines accepted keys, a description, actions, and a return signal.
- `ReturnSignal`: registry-backed signal objects (`CONTINUE`, `BREAK`, `PASS`, `NONE`, plus custom signals).
- `interactive_dispatcher(...)`: prints menu, runs selected actions, and returns `(results, signal)`.
- Input matching is exact and case-sensitive (`"g"` is different from `"G"`).

## Why Use It
- Keeps CLI control flow explicit and readable.
- Lets you compose multiple actions per menu option.
- Works well for REPL-like apps, setup wizards, and small automation tools.

## Development
```bash
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install -e ".[dev]"
python3 -m build
```

## Open Source
- License: Apache-2.0 (`LICENSE`)
- Contributing guide: `CONTRIBUTING.md`

## Output Preview
![CLI output preview](https://github.com/Akhand-Pratap-Tiwari/python-interactive-dispatcher/blob/main/image.png?raw=true)
