Message types and animations

You can view example output of the library using the python scripts in the provided examples directory.

Basic Message Types

cliasi provides several methods for common message types, each with its own symbol and color.

Here is how they look in the console:

examples/basic_messages.py

from cliasi import cli

cli.info("Starting process...")
cli.success("Process completed!")
cli.warn("Disk space is low.")
cli.fail("Failed to connect to server.")
cli.log("Debug info")
cli.list("List item")

Warning

The actual colors and symbols below may vary depending on your terminal and its settings.

i [CLI] | Starting process...
✔ [CLI] | Process completed!
! [CLI] | Disk space is low.
X [CLI] | Failed to connect to server.
LOG [CLI] | Debug info
- [CLI] | List item

Exception and Traceback Formatting

If an exception is raised or a traceback is logged, it will be formatted using the fail message style:

examples/exception_message.py

import cliasi

# Importing cliasi automatically installs the logging handler
raise ValueError("An example error")

X [CLI] | Uncaught exception:
X [CLI] | Traceback (most recent call last):
        |   File "examples/exception_message.py", line 7, in <module>
        |     raise ValueError("An example error")
        | ValueError: An example error

Animations and Progress Bars

Blocking Animation

Blocking animations run in the main thread and block further execution until complete.

Note

Animated messages trim overflowing text to the current terminal width as animations only work when the text is one line long.

examples/blocking_animation.py

from cliasi import cli
import time

cli.animate_message_blocking("Saving...", time=3, message_right="[CTRL-C] to stop")
# You cant do anything else while the animation is running
# Useful if you save something to a file at the end of a program
# User can CTRL-C while this is running
cli.success("Data saved!")

Tip

For more information about alignment of messages, see Message alignment.

Non-Blocking Animation

examples/non_blocking_animation.py

import time

from cliasi import cli

cli.messages_stay_in_one_line = True  # To hide animation after finished.
task = cli.animate_message_non_blocking("Processing...")
# Do other stuff while the animation is running
time.sleep(3)  # Simulate a long task
task.stop()  # Stop the animation when done
cli.success("Done!")

Progress Bars

Note

Progress bars (animated and static) trim overflowing text to the current terminal width. They work when the text is one line long.

examples/progress_bar.py

import time

from cliasi import cli

for i in range(101):
    cli.progressbar("Calculating", message_center=True, progress=i, show_percent=True)
    time.sleep(0.02)
cli.newline()  # Add a newline after the progress bar is complete
cli.success("Calculation complete.")
# Use cli.progressbar_download() for download-style progress bars.

Animated Progress Bars

examples/animated_progress_bar.py

import time

from cliasi import cli

task = cli.progressbar_animated_download(
    message_left="downloading",
    message_right="please wait",
)
for i in range(100):
    time.sleep(0.05)  # Simulate work
    task.update(progress=i)    # Update progress by 1
task.stop()        # Finish the progress bar
cli.success("Download complete.")

Progress bar customization options

Progress bars can be customized with several parameters:

• show_percent: Whether to show the percentage completed.

• cover_dead_space_with_bar: Whether to fill alignment space of messages (there is always a space before message_left) with the bar or just with spaces. False by default.

• calculation_mode: PBCalculationMode to customize the way the progress bar renders progress. Look at the enum documentation for details.

Example usage of calculation modes:

examples/calculation_modes_demo.py

from time import sleep
from cliasi import PBCalculationMode, cli

for i in range(100):
    sleep(0.025)
    # Fills across the full width but skips text
    cli.progressbar(
        "progress goes",
        message_right="under text",
        progress=i,
        calculation_mode=PBCalculationMode.FULL_WIDTH,
        show_percent=True,
    )

for i in range(100):
    sleep(0.025)
    # Fills only empty space between text segments
    cli.progressbar_download(
        message_left="progress goes between here",
        message_right="and there",
        progress=i,
        calculation_mode=PBCalculationMode.ONLY_EMPTY,
    )

for i in range(100):
    sleep(0.025)
    # Overwrites text when the bar reaches it (useful for dense bars)
    cli.progressbar(
        message_left=None,
        message_right="This text will be overwritten",
        progress=i,
        calculation_mode=PBCalculationMode.FULL_WIDTH_OVERWRITE,
    )

User Input

You can ask for user input, including passwords.

If you use any form of alignment, you can use the cursor_position parameter to specify where the input cursor should be placed after the text has been printed.

examples/user_input_interactive.py

from cliasi import cli

name = cli.ask("What is your name?")
code = cli.ask("Enter your secret code:", hide_input=True, message_right="[login]")

cli.info(f"Hello, {name} with code {code}")

Message alignment

You can align messages to the left, right, or center of the terminal.

All message types support alignment with the message_left, message_right, and message_center parameters.

You can either set the corresponding parameters to True, or set the parameters themselves to the desired text.

Note

If the left message goes too far and covers the middle one or is too long or has newlines, all aligned will be printed one after the other with as many lines as it takes.

Cliasi will attempt to put message_right to the right at the end of messages that go over multiple lines, but this is not always possible.

examples/message_alignment.py

from cliasi import cli

cli.info("This is a left-aligned message.")  # Default is left-aligned
cli.success("This is a right-aligned message.", message_right=True)
cli.warn(False, message_center="This is a centered message.")
# False because parameter message_left is required to be set. Can also use ""
cli.info("From left", message_center="to the middle", message_right="to the right")

Warning

The actual colors and symbols below may vary depending on your terminal and its settings.

i [CLI] | This is a left-aligned message.

✔ [CLI] | This is a right-aligned message.

! [CLI] | This is a centered message.

i [CLI] | From left to the middle to the right

max_dead_space parameter

If you send a short message with short left text and short right text they might end up very far apart on wide terminals. Users might not read the text on the right.

To prevent this you can set the max_dead_space parameter to a number of characters. If the dead space between left and right aligned text exceeds this number, the right or center aligned text put next to the left aligned text.

If you deliberately disable the left aligned text or set max_dead_space to None the check will be skipped