Metadata-Version: 2.4
Name: interactive-dispatcher
Version: 1.0.4
Summary: A customizable interactive CLI menu dispatcher with extendable return signals and matching function calls.
Author: Akhand Pratap Tiwari
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/Akhand-Pratap-Tiwari/python-interactive-dispatcher
Project-URL: Repository, https://github.com/Akhand-Pratap-Tiwari/python-interactive-dispatcher
Project-URL: Issues, https://github.com/Akhand-Pratap-Tiwari/python-interactive-dispatcher/issues
Project-URL: Changelog, https://github.com/Akhand-Pratap-Tiwari/python-interactive-dispatcher/blob/main/CHANGELOG.md
Keywords: cli,menu,dispatcher,return-signal,customizable,interactive,function-calls
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: User Interfaces
Classifier: Operating System :: OS Independent
Classifier: Typing :: Typed
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: black>=24.0.0; extra == "dev"
Requires-Dist: build>=1.2.0; extra == "dev"
Requires-Dist: mypy>=1.10.0; extra == "dev"
Requires-Dist: ruff>=0.5.0; extra == "dev"
Requires-Dist: twine>=5.0.0; extra == "dev"
Dynamic: license-file

# 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)
