pymenu-cli 1.0.7

A Python library for creating interactive CLI menus

pymenu-cli

pymenu-cli is a Python library that simplifies the creation of interactive command-line interface (CLI) menus. It provides a convenient way to define hierarchical menu structures and associate actions with menu items.

Your browser does not support the video tag.

Features

• Define menus and submenus using a simple JSON file format
• Automatically generate navigation options (e.g., "Back" and "Exit")
• Execute specific functions based on user selections
• Customizable menu titles and item labels
• Flexible and extensible architecture
• Execute menus directly from the command line
• Support for color customization of menu titles and items
• Display a banner using ASCII art with customizable text and font

Installation

pip install pymenu-cli

Usage

1. Define your menu structure in a JSON file (menu.json)
2. Implement the corresponding action functions in a separate Python file (actions.py)

Using the Python API

from pymenu_cli.menu import load_menu

# Define the 'menu' and the 'action' files 
menu_file_path = 'menu.json'
actions_file_path = 'actions.py'

# Init the menu with this files
main_menu = load_menu(menu_file_path, actions_file_path)

# Display the menu
main_menu.display()

Using the Command Line

pymenu-cli --menu menu.json --actions actions.py

pymenu-cli takes care of the menu navigation, menu stying, user input handling, and execution of the associated actions based on the user's selections.

Menu JSON Format

The menu.json file defines the structure of your menu. Here's an example:

{
  "banner": {
    "title": "HELLO",
    "font": "white_bubble"
  },
  "title": "Main Menu",
  "color": {
    "text": "light_blue",
    "background": "black"
  },
  "items": [
    {
      "title": "Option 1",
      "color": {
        "text": "yellow",
        "background": "blue"
      },
      "action": "action_function_1"
    },
    {
      "title": "Option 2",
      "color": {
        "text": "black",
        "background": "light_yellow"
      },
      "submenu": {
        "title": "Submenu",
        "items": [
          {
            "title": "Submenu Option 1",
            "action": "action_function_2"
          },
          {
            "title": "Submenu Option 2",
            "action": "action_function_3"
          }
        ]
      }
    }
  ]
}

In the menu.json file, you can specify the following properties:

• banner (optional): The banner configuration for the menu.
  • title: The text to display in the banner.
  • font (optional): The font to use for the banner. If not specified, the default font will be used.
• title: The title of the menu or submenu.
• color (optional): The color settings for the menu or submenu title.
  • text: The color of the text (e.g., "red", "light_blue").
  • background: The color of the background (e.g., "white", "black").
• items: An array of menu items, each with its own properties:
  • title: The title of the menu item.
  • color (optional): The color settings for the menu item title.
  • action (optional): The name of the action function to execute when the item is selected.
  • submenu (optional): A nested submenu with its own title and items.

Banner Customization

PyMenu CLI supports displaying a banner using ASCII art. The banner can be customized by specifying the banner property in the menu.json file. The banner property has the following sub-properties:

• title: The text to display in the banner.
• font (optional): The font to use for the banner. If not specified, the default font will be used.

PyMenu CLI uses the art library to generate the ASCII art for the banner. You can choose from a wide range of available fonts provided by the art library. Here are some font options:

• "standard"

 _____                _   
|  ___|  ___   _ __  | |_ 
| |_    / _ \ | '_ \ | __|
|  _|  | (_) || | | || |_ 
|_|     \___/ |_| |_| \__|

• "block"

 .----------------.  .----------------.  .-----------------. .----------------. 
| .--------------. || .--------------. || .--------------. || .--------------. |
| |  _________   | || |     ____     | || | ____  _____  | || |  _________   | |
| | |_   ___  |  | || |   .'    `.   | || ||_   \|_   _| | || | |  _   _  |  | |
| |   | |_  \_|  | || |  /  .--.  \  | || |  |   \ | |   | || | |_/ | | \_|  | |
| |   |  _|      | || |  | |    | |  | || |  | |\ \| |   | || |     | |      | |
| |  _| |_       | || |  \  `--'  /  | || | _| |_\   |_  | || |    _| |_     | |
| | |_____|      | || |   `.____.'   | || ||_____|\____| | || |   |_____|    | |
| |              | || |              | || |              | || |              | |
| '--------------' || '--------------' || '--------------' || '--------------' |
 '----------------'  '----------------'  '----------------'  '----------------' 

• "bubble"

  _    _    _    _  
 / \  / \  / \  / \ 
( F )( o )( n )( t )
 \_/  \_/  \_/  \_/ 

• "white_bubble"

Ⓕⓞⓝⓣ

• "black_bubble"

🅕🅞🅝🅣

• "digital"

+-++-++-++-+
|f||o||n||t|
+-++-++-++-+

• "isometric1"

      ___           ___           ___           ___     
     /\  \         /\  \         /\__\         /\  \    
    /::\  \       /::\  \       /::|  |        \:\  \   
   /:/\:\  \     /:/\:\  \     /:|:|  |         \:\  \  
  /::\~\:\  \   /:/  \:\  \   /:/|:|  |__       /::\  \ 
 /:/\:\ \:\__\ /:/__/ \:\__\ /:/ |:| /\__\     /:/\:\__\
 \/__\:\ \/__/ \:\  \ /:/  / \/__|:|/:/  /    /:/  \/__/
      \:\__\    \:\  /:/  /      |:/:/  /    /:/  /     
       \/__/     \:\/:/  /       |::/  /     \/__/      
                  \::/  /        /:/  /                 
                   \/__/         \/__/                  

• "letters"

FFFFFFF                tt    
FF       oooo  nn nnn  tt    
FFFF    oo  oo nnn  nn tttt  
FF      oo  oo nn   nn tt    
FF       oooo  nn   nn  tttt 

• "arrow"

>=======>                        >=>   
>=>                              >=>   
>=>          >=>     >==>>==>  >=>>==> 
>=====>    >=>  >=>   >=>  >=>   >=>   
>=>       >=>    >=>  >=>  >=>   >=>   
>=>        >=>  >=>   >=>  >=>   >=>   
>=>          >=>     >==>  >=>    >=>  

• "slant"

    ______                  __ 
   / ____/  ____    ____   / /_
  / /_     / __ \  / __ \ / __/
 / __/    / /_/ / / / / // /_  
/_/       \____/ /_/ /_/ \__/  

For a complete list of available fonts, please refer to the art library documentation. If no font is specified in the banner configuration, PyMenu CLI will use the default font provided by the art library.

Color Customization

PyMenu CLI supports color customization of menu titles and items using the colorama library. You can specify the color of the text and background for each menu and item in the menu.json file. The available color options are defined in the TextColors and BackgroundColors enums:

TextColors

RED, LIGHT_RED, BLUE, LIGHT_BLUE, YELLOW, LIGHT_YELLOW, GREEN, LIGHT_GREEN, CYAN, LIGHT_CYAN, MAGENTA, LIGHT_MAGENTA, BLACK, LIGHT_BLACK, WHITE, LIGHT_WHITE

BackgroundColors

RED, LIGHT_RED, BLUE, LIGHT_BLUE, YELLOW, LIGHT_YELLOW, GREEN, LIGHT_GREEN, CYAN, LIGHT_CYAN, MAGENTA, LIGHT_MAGENTA, BLACK, LIGHT_BLACK, WHITE, LIGHT_WHITE

To apply colors to a menu or item, add the color property with the desired text and background colors in the menu.json file.

Color Example

Here's an example of how the menu with colors would look like:

• View Color Examples

Actions Python File

The actions.py file contains the functions that are executed when a menu item is selected. Here's an example:

def action_function_1():
    print("Executing action 1")

def action_function_2():
    print("Executing action 2")

def action_function_3():
    print("Executing action 3")

Examples

Explore the examples directory for sample menu configurations and action implementations. To run an example, follow these steps:

1. Clone the project repository.
2. Open your command line and navigate to the examples directory.
3. Execute the example by running the following command:

python3 menu_example.py

License

This project is licensed under the MIT License.

Contributors

Contributing to pymenu-cli

Thank you for considering contributing to pymenu-cli! We welcome all contributions, whether they are bug reports, feature requests, or code improvements. Please take a moment to review this document before submitting your contributions.

How to Contribute

Reporting Bugs

If you find a bug, please report it by opening an issue. Include as much detail as possible to help us reproduce and fix the issue quickly. Make sure to include:

• A clear and descriptive title.
• A detailed description of the problem.
• Steps to reproduce the issue.
• Any relevant logs or screenshots.

Suggesting Enhancements

We welcome suggestions for new features and enhancements. To suggest an enhancement, please open an issue and provide:

• A clear and descriptive title.
• A detailed description of the proposed enhancement.
• Any relevant examples or mockups.

Submitting Pull Requests

To submit a pull request (PR), follow these steps:

1. Fork the repository: Click the "Fork" button at the top of this page to create a copy of the repository on your GitHub account.

2. Clone your fork: Clone the forked repository to your local machine using the following command:

   git clone https://github.com/moraneus/pymenu-cli.git
   cd pymenu-cli
   

3. Create a new branch: Create a new branch for your work. Use a descriptive name for the branch:

   git checkout -b feature/my-new-feature
   

4. Make your changes: Make your changes in the new branch.

5. Commit your changes: Commit your changes with a clear and concise commit message:

   git add .
   git commit -m "Add feature: my new feature"
   

6. Push to your fork: Push your changes to your forked repository:

   git push origin feature/my-new-feature
   

7. Open a pull request: Go to the original repository and open a pull request from your forked repository. Provide a clear and descriptive title and description for your PR.

Code Style and Guidelines

• Follow the existing code style and conventions.
• Write clear and concise commit messages.
• Write tests for new features and bug fixes.
• Ensure your code passes all existing tests.

Running Tests

Before submitting your PR, make sure all tests pass. You can run the tests using the following commands:

# Install dependencies
pip install -r requirements.txt

# Run tests
pytest