BeauPy

A Python library of interactive CLI elements you have been looking for

---

For documentation but more and prettier see here

Acknowledgment

BeauPy stands on the shoulders of giants. It is based on another library with which it shares some of the source code, cutie, developed by Kamik423. It has begun as a fork but has since diverged into its own thing and as such, detached from the original repository.

Overview

BeauPy implements a number of common interactive elements:

Function	Functionality
select	Prompt to pick a choice from a list
select_multiple	Prompt to select one or multiple choices from a list
confirm	Prompt with a question and yes/no options
prompt	Prompt that takes free input with optional validation, type conversion and input hiding

TUI elements shown in the above gif are the result of the following code:

import time
from beaupy import confirm, prompt, select, select_multiple
from beaupy.spinners import *
from rich.console import Console

console = Console()

# Confirm a dialog
if confirm("Will you take the ring to Mordor?"):
    names = [
        "Frodo Baggins",
        "Samwise Gamgee",
        "Legolas",
        "Aragorn",
        "[red]Sauron[/red]",
    ]
    console.print("Who are you?")
    # Choose one item from a list
    name = select(names, cursor="🢧", cursor_style="cyan")
    console.print(f"Alámenë, {name}")


    item_options = [
        "The One Ring",
        "Dagger",
        "Po-tae-toes",
        "Lightsaber (Wrong franchise! Nevermind, roll with it!)",
    ]
    console.print("What do you bring with you?")
    # Choose multiple options from a list
    items = select_multiple(item_options, tick_character='🎒', ticked_indices=[0], maximal_count=3)

    potato_count = 0
    if "Po-tae-toes" in items:
        # Prompt with type conversion and validation
        potato_count = prompt('How many potatoes?', target_type=int, validator=lambda count: count > 0)

    # Spinner to show while doing some work
    spinner = Spinner(DOTS, "Packing things...")
    spinner.start()

    time.sleep(2)

    spinner.stop()
    # Get input without showing it being typed
    if "friend" == prompt("Speak, [blue bold underline]friend[/blue bold underline], and enter", secure=True).lower():

        # Custom spinner animation
        spinner_animation = ['▉▉', '▌▐', '  ', '▌▐', '▉▉']
        spinner = Spinner(spinner_animation, "Opening the Door of Durin...")
        spinner.start()

        time.sleep(2)

        spinner.stop()
    else:
        spinner_animation = ['🐙🌊    ⚔️ ', '🐙 🌊   ⚔️ ', '🐙  🌊  ⚔️ ', '🐙   🌊 ⚔️ ', '🐙    🌊⚔️ ']
        spinner = Spinner(spinner_animation, "Getting attacked by an octopus...")
        spinner.start()

        time.sleep(2)

        spinner.stop()

    if 'The One Ring' in items:
        console.print("[green]You throw The One Ring to a lava from an eagle![/green]")
    else:
        console.print("[red]You forgot the ring and brought Middle-Earth to its knees![/red]")
    console.print(f"And you brought {potato_count} taters!")

For more information refer to more examples or definitive, but much less exciting API documentation

Installation

From PyPI:

pip install beaupy

From Conda (kindly set up and maintained by @thewchan):

conda config --add channels conda-forge
conda config --set channel_priority strict
conda install beaupy

From source:

git clone https://github.com/petereon/beaupy.git
poetry build
pip install ./dist/beaupy-{{some-version}}-py3-none-any.whl

Roadmap

This repository has a associated GitHub project where work that is currently done can be seen.

Contributing

If you would like to contribute, please feel free to suggest features or implement them yourself.

Also please report any issues and bugs you might find!

Development

To start development you can clone the repository:

git clone https://github.com/petereon/beaupy.git

Change the directory to the project directory:

cd ./beaupy/

This project uses poetry as a dependency manager. You can install the dependencies using:

poetry install

For testing, this project relies on ward. It is included as a development dependency, so after installing the dependencies you can simply execute the following:

poetry run poe test

Making sure the code follows quality standards and formatting can be ensured by executing

poetry run poe lint

You can also have the tests and lints run after every saved change by executing a respective watch command

poetry run poe test:watch

or

poetry run poe lint:watch

After you have made your changes, create a pull request towards a master branch of this repository

Looking forward to your pull requests!

Compatibility

Internal logic of beaupy is supported for all the major platforms (Windows, Linux, macOS).

• For user input from console, beaupy relies on petereon/yakh, which is tested against all the major platforms and Python versions.
• For printing to console beaupy relies on Textualize/rich, which supports all the major platforms.

Known Issues

• From version 0.1.7 the CLI elements cause issue with displaying pdb prompt (#93).
• From version 2.0.0 arrow keys reportedly don't always work on Windows. Resolved in 3.0.0.
• From version 3.5.0 there were various option display bugs in select and select_multiple. Resolved in 3.5.4.
• From version 3.9.0, the CLI elements default to persisting in the terminal after they finish executing. Resolved in 3.9.2.

Awesome projects using beaupy

• therealOri/Genter: A strong password generator and built in password manager made with python3!
• therealOri/byte: Steganography Image/Data Injector. For artists or people to inject their own Datamark "Watermark" into their images/art or files!
• AnirudhG07/ntfyme: A notification tool to notify you about status of your long running processes on termination via local-notification, Gmail, Telergram, etc.

License

The project is licensed under the MIT License.