Skip to main content

A collection of tools for building dynamic Command-Line applications

Project description

bestia

bestia is a library of functions and classes designed to help you build vibrant and dynamic applications for the command-line on Linux / Darwin systems. It allows you to create rich evolving TUI's for your terminal-based tools using a simple and readable programming interface.

installation

Please install bestia using pip:

$   python3 -m pip install bestia

The library does not require you to install any external dependencies.

available functions / classes

output.py

* echo
* FString
* Row
* tty_cursor
* tty_clear
* tty_up
* tty_rows
* tty_cols
* expand_seconds
* human_bytes
* remove_path
* obfuscate_random_chars
* ProgressBar
* ansi_esc_seq
* ansi_sgr_seq

iterate.py

* LoopedList
* items_are_equal
* iterable_to_string
* unique_random_items
* pop_random_item

api reference

Let's focus on the echo function, the FString class and the Row class which contain the core of this library's functionality.

>>> from bestia.output import echo, FString, Row

echo() function:

This is a very basic function which takes your string as first argument, followed by any number of effects that you may want to apply to your text. You can specify up to a maximum of 2 colors (1st: foreground, 2nd: background) and as many effects as you want.

Supported color values:
'black' 'red' 'green' 'yellow' 'blue' 'magenta' 'cyan' 'white'

Supported effect values:
'reset' 'bold' 'faint' 'underline' 'blink' 'reverse' 'conceal' 'cross' 'frame' 'circle' 'overline'

Not all terminal emulators support the same colors or effects so some of these may not work depending on what you are using.

The echo function also has an optional last keyword argument mode that alters how strings are rendered|terminated.

>>> echo("foo", mode='raw')
foo>>> 

The 'modern' mode is your standard printing mode.
The 'raw' mode prints strings without appending a newline char.
The 'retro' mode emulates the printing style of an 80's computer by adding a random amount of lag to each char that gets printed. It can make your applications have a real vintage feel to them.

Play with all of them and see what you like!

FString() class:

The FString class has all the "coloring" functionality of the echo function but requires you to explicitly use it's attributes fg: str, bg: str, fx: list. This added complexity allows for far more flexibility since you can specify these values when instantiating an object and modify them at will later. You can print your FString either by calling it's echo method or by printing the object itself.

Coloring is NOT however the main feature of this class, the most important functionality that FString provides is the ability to force strings into specific areas of your terminal space. It achieves this by dynamically padding your string with spaces (or any other char) so that it will be placed where needed on the horizontal plane.

>>> fs1 = FString('123', size=5, align='r')
>>> print(fs1)
  123
>>> fs1.size = 10
>>> print(fs1)
       123
>>> fs1.align = 'c'
>>> print(fs1)
   123    

Notice how the "123" string moves to the right by setting it's size and align attributes. The default value for align is 'l', but other possible values are:
'l' 'r' 'c' 'cl' 'cr'

FString can add space to your strings but it can also crop them if you set a size value lower than the string's actual length. This is extremely useful when you are dealing with dynamic text and you want to ensure it will not take more than a fixed amount of space in your application.

>>> fs2 = FString('Welcome to the Jungle!', size=10)
>>> fs2.echo()
Welcome to
>>> fs2.size = 16
>>> fs2.echo()
Welcome to the J

Dealing with empty spaces can make it hard to understand where our FStrings finish and begin. You can use the pad attribute for debugging purposes or to create more interesting TUI's:

>>> FString(' asd ', size=20, align='cl', pad=' ').echo(mode='modern')
        asd         
>>> FString(' asd ', size=20, align='cl', pad='|').echo(mode='modern')
||||||| asd ||||||||
>>> FString(' asd ', size=20, align='cr', pad='*').echo(mode='modern')
******** asd *******

The echo method of FString also has an optional mode argument which works exactly as in the echo function.

Row() class:

Row() is a class that accepts any number of str or FString objects as arguments and forces them to print on the same terminal row by automatically detecting the size of your terminal window and resizing each item accordingly. It will crop items if their total length is more than your terminal size or add spaces if their length is less. It is a fantastic tool for building dynamic textual user interfaces. First, let's check out some basics:

>>> r = Row( '123', FString('ABC', align='r') )
>>> r.echo(mode='retro')
123                                                                                   ABC

The size of your terminal is calculated on the fly just before rendering your strings. This means that Row objects work great at keeping your data neat and viewable even across terminal window resizes.

Most of the times you will want your Row instances to automatically size up to your terminal width but if for some reason you don't, you can always set their size attribute to a static size.

>>> r.size = 30
>>> r.echo()
123                        ABC

If you need any of the strings that make up your Row to NOT be resized, just init a FString and then set it's size attribute to a static value. That object will now keep it's size static and Row will resize all other items.

>>> Row(
...     FString('id', size=3, fg='cyan', align='l', bg='blue', fx=['bold', 'underline']),
...     FString('Location', size=None, fg='yellow', bg='blue', fx=['bold', 'underline']),
...     FString('Size', size=6, align='r', bg='blue', fx=['bold', 'underline']),
...     FString('Files', size=6, fg='green', align='r', bg='blue', fx=['bold', 'underline']),
...     FString('Users', size=6, fg='red', align='r', bg='blue', fx=['bold', 'underline']),
...     FString('Categories', size=15, align='r', bg='blue', fx=['bold', 'underline']),
...    ).echo(mode='retro')

In this example, all items will have a fixed size and Row will take care of making them fit exactly into the terminal width by shrinking/expanding the Location FString (the only one that has not a fixed size value). The mode parameter will take care of giving the rendering of the string a retro vibe.

Unfortunately MarkDown does not do a great job at showing off all the possibilities that this library gives you in terms of creating classy looking CLI tools. I will let the next screenshots section do some of the talking now with a couple of examples of applications built using bestia.

Enjoy!

screenshots

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

bestia-5.0.tar.gz (13.9 kB view details)

Uploaded Source

Built Distribution

bestia-5.0-py3-none-any.whl (11.7 kB view details)

Uploaded Python 3

File details

Details for the file bestia-5.0.tar.gz.

File metadata

  • Download URL: bestia-5.0.tar.gz
  • Upload date:
  • Size: 13.9 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.1 CPython/3.13.0

File hashes

Hashes for bestia-5.0.tar.gz
Algorithm Hash digest
SHA256 c9f9865ac8f4481f5864699d0f78365be115af3722d23a4eb812d8500ef51150
MD5 7517ff1aa5bb0212164bad4615cef6dd
BLAKE2b-256 91a52e8b428e3ad4bcb4badc5106ffe653fa33c73c820c532f3f0bcd272c2d05

See more details on using hashes here.

File details

Details for the file bestia-5.0-py3-none-any.whl.

File metadata

  • Download URL: bestia-5.0-py3-none-any.whl
  • Upload date:
  • Size: 11.7 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.1 CPython/3.13.0

File hashes

Hashes for bestia-5.0-py3-none-any.whl
Algorithm Hash digest
SHA256 c44201d967e7b9a20886aa82df52ec5d21c7806ec3945d50d681c986340ad85a
MD5 2fee066d27097d699f08d43c3a6392e9
BLAKE2b-256 9eb78728d51e6268925068c5a5ac76a0bac1475479337fa1bfaf903f63eb911b

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page