A phone-tree like menu system for text-based interfaces
Project description
PhoneTree
PhoneTree is a Python framework for creating text-based menu systems, resembling phone tree systems or rudimentary chatbots. It allows you to easily create menus and actions, manage user input and output, and maintain state between interactions.
Features
- Simple decorator-based syntax for defining menus and actions
- Optional "ask" and "tell" callbacks for handling user input and output
- State management for passing data between menus and actions
Installation
To install PhoneTree, simply use pip:
pip install phonetree
Usage
Here's an example of how to use PhoneTree to create a simple menu system:
import phonetree
from phonetree import Ask, Tell
@phonetree.menu()
def main_menu(state: dict) -> dict:
"""Main menu."""
return {"interactions": state.get("interactions", 0) + 1}
@main_menu.menu("First Submenu")
def first_submenu(state: dict) -> dict:
"""First Submenu menu."""
# here goes the code that runs when you enter the submenu
...
return {"interactions": state.get("interactions", 0) + 1}
@first_submenu.action("Do something")
def do_something(state: dict, ask: Ask, tell: Tell) -> dict:
"""Some action"""
anything = ask("Is there anything you want to say?")
print("user answered: " + anything)
tell("Alright! Thank you!")
return {"interactions": state.get("interactions", 0) + 1}
@first_submenu.action("Do something else")
def do_something_else(state: dict, ask: Ask, tell: Tell) -> dict:
"""Some action"""
color = ask("What's your favorite color?")
print("User said " + color + " is their favorite color.")
tell("Alright! Nice to know!")
return {"interactions": state.get("interactions", 0) + 1, "favorite_color": color}
@main_menu.menu("Second submenu")
def second_submenu(state: dict, tell: Tell) -> dict:
"""Second submenu."""
tell("Welcome to second submenu!")
return {"interactions": state.get("interactions", 0) + 1}
Defining Menus and Actions
To define a menu, simply use the @phonetree.menu()
decorator on a function. The function should return a dictionary representing the new state of the menu. This state will be passed on to the next menu or action function call.
To define an action within a menu, use the @menu.action("Action Name")
decorator on a function. The function should also return a dictionary representing the new state of the menu.
Handling User Input and Output
Menu and action functions can take optional "ask" and "tell" callbacks.
The "ask" function sends some text to the user and expects an answer, returning the answer as the response of the function call. If the function returns None
, the program execution is ended.
The "tell" function just sends some text to the user and doesn't return anything back. Both functions are recognized by their names in the menu/action functions argument list.
State Management
Menu and action functions can also take a state variable, which can be called anything (except for "ask" and "tell"). This argument is optional, but if passed, should be the first argument of the function. This argument can receive a state of any type.
The function should return the new state of the menu, which will determine what will be passed on as the state for the next menu/action function call. This state can be any object, including None
, if the user doesn't need to keep any state.
Running the Application
To run the application defined by the menu, call the communicate
method for the menu, passing the state, ask, and tell callbacks:
# communicate(state, ask, tell)
main_menu.communicate({"interactions": 0}, input, print)
This will start the menu system and handle user interactions according to the defined menu and action functions.
License
PhoneTree is released under the MIT License.
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for phonetree-1.3.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | be5ded5402b982c4630838839b280656eba4683bd8b48d236514671d59d74190 |
|
MD5 | 9100bce1adde7990a9385e1f4e0c031c |
|
BLAKE2b-256 | 76ba774a52377af584a6c6114d7f2582e3be2bed3551baf06cfda9a4f2bd8f55 |