https://github.com/petereon/beaupy
A Python library of interactive CLI elements you have been looking for
https://github.com/petereon/beaupy
cli console interface python terminal
Last synced: 4 months ago
JSON representation
A Python library of interactive CLI elements you have been looking for
- Host: GitHub
- URL: https://github.com/petereon/beaupy
- Owner: petereon
- License: mit
- Created: 2022-08-06T19:56:01.000Z (over 3 years ago)
- Default Branch: master
- Last Pushed: 2025-07-31T09:51:01.000Z (5 months ago)
- Last Synced: 2025-08-19T03:50:24.307Z (4 months ago)
- Topics: cli, console, interface, python, terminal
- Language: Python
- Homepage: https://petereon.github.io/beaupy/
- Size: 14.7 MB
- Stars: 223
- Watchers: 3
- Forks: 14
- Open Issues: 14
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# BeauPy
> A Python library of interactive CLI elements you have been looking for
---
[](https://github.com/petereon/beaupy/actions/workflows/python-test.yml)
[](https://codecov.io/gh/petereon/beaupy)
[](https://sonarcloud.io/summary/new_code?id=petereon_beaupy)
[](https://sonarcloud.io/summary/new_code?id=petereon_beaupy)
For documentation but more and prettier see [**here**](https://petereon.github.io/beaupy/)
## Acknowledgment
BeauPy stands on the shoulders of giants. It is based on another library with which it shares some of the source code, [`cutie`](https://github.com/kamik423/cutie), developed by [Kamik423](https://github.com/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`](https://petereon.github.io/beaupy/api/#select) | Prompt to pick a choice from a list |
| [`select_multiple`](https://petereon.github.io/beaupy/api/#select_multiple) | Prompt to select one or multiple choices from a list |
| [`confirm`](https://petereon.github.io/beaupy/api/#confirm) | Prompt with a question and yes/no options |
| [`prompt`](https://petereon.github.io/beaupy/api/#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:
```python
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](https://petereon.github.io/beaupy/examples/) or definitive, but much less exciting [API documentation](https://petereon.github.io/beaupy/api/)
## Installation
From PyPI:
```sh
pip install beaupy
```
From [Conda](https://github.com/conda-forge/beaupy-feedstock) (kindly set up and maintained by [@thewchan](https://github.com/thewchan)):
```sh
conda config --add channels conda-forge
conda config --set channel_priority strict
conda install beaupy
```
From source:
```sh
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](https://github.com/users/petereon/projects/3/views/1) 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:
```sh
git clone https://github.com/petereon/beaupy.git
```
Change the directory to the project directory:
```sh
cd ./beaupy/
```
This project uses [`poetry`](https://python-poetry.org/) as a dependency manager. You can install the dependencies using:
```sh
poetry install
```
For testing, this project relies on pytest. It is included as a development dependency, so
after installing the dependencies you can simply execute the following:
```sh
poetry run poe test
```
Making sure the code follows quality standards and formatting can be ensured by executing
```sh
poetry run poe lint
```
You can also have the tests and lints run after every saved change by executing a respective watch command
```sh
poetry run poe test:watch
```
or
```sh
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](https://github.com/petereon/yakh), which is tested against all the major platforms and Python versions.
- For printing to console `beaupy` relies on [Textualize/rich](https://github.com/Textualize/rich), which [supports](https://github.com/Textualize/rich#compatibility) all the major platforms.
## Known Issues
- From version `0.1.7` the CLI elements cause issue with displaying `pdb` prompt ([#93](https://github.com/petereon/beaupy/issues/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](https://github.com/therealOri/Genter): A strong password generator and built in password manager made with python3!
- [therealOri/byte](https://github.com/therealOri/byte): Steganography Image/Data Injector. For artists or people to inject their own Datamark "Watermark" into their images/art or files!
- [AnirudhG07/ntfyme](https://github.com/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](https://raw.githubusercontent.com/petereon/beaupy/master/LICENSE).