API Reference

Top-level package

The main interface for cliasi.

cliasi exports the Cliasi instance cli as well as

cliasi.cli global cli instance

A Cliasi CLI instance. Stores display settings and a minimum verbosity threshold.

cliasi.STDOUT_STREAM <_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>

standard output stream the library uses

cliasi.STDERR_STREAM <_io.TextIOWrapper name='<stderr>' mode='w' encoding='utf-8'>

Error stream the library uses

cliasi.SYMBOLS

Collection of useful symbols

Command line utility for coloring text and writing pretty things.

class cliasi.Cliasi(prefix: str = '', messages_stay_in_one_line: bool = False, colors: bool = True, min_verbose_level: int | None = None, seperator: str = '|')[source]

Bases: object

A Cliasi CLI instance. Stores display settings and a minimum verbosity threshold.

Initialize a cliasi instance.

Parameters:

  • prefix – Message Prefix [prefix] message

  • messages_stay_in_one_line – Have all messages appear in one line by default

  • colors – Enable color display

  • min_verbose_level – Only displays messages with verbose level higher than this value (default is logging.INFO), None will result in the verbosity level getting set to the value of the global instance which is by default 0

  • seperator – Seperator between prefix and message

class NonBlockingAnimationTask(message: str, stop_condition: Event, message_stays_in_one_line: bool)[source]

Bases: object

Defines a non-blocking animation task run on another Thread

stop() → None[source]

Stop the current animation task

Returns:

update(message: str | None = None) → None[source]

Update message of animation

Parameters:

message – Message to update to (None for no update)

Returns:

None

class NonBlockingProgressTask(message: str, stop_condition: Event, override_messages_stay_in_one_line: bool, progress: int)[source]

Bases: NonBlockingAnimationTask

Defines a non-blocking animation task with a progress bar run on another Thread

update(message: str | None = None, progress: int | None = None, *args: object, **kwargs: object) → None[source]

Update progressbar message and progress

Parameters:

  • message – Message to update to (None for no update)

  • progress – Progress to update to (None for no update)

Returns:

None

animate_message_blocking(message: str, time: int | float, verbosity: int = 20, interval: int | float = 0.25, unicorn: bool = False, override_messages_stay_in_one_line: bool | None = None) → None[source]

Display a loading animation for a fixed time This will block the main thread using time.sleep

Parameters:

  • message – Message to display

  • time – Time to display for

  • verbosity – Verbosity of this message

  • interval – Interval between changes in loading animation

  • unicorn – Enable unicorn mode

  • override_messages_stay_in_one_line – Override the message to stay in one line

Returns:

None

animate_message_download_non_blocking(message: str, verbosity: int = 20, interval: int | float = 0.25, unicorn: bool = False, override_messages_stay_in_one_line: bool | None = True) → NonBlockingAnimationTask | None[source]

Display a downloading animation in the background

Parameters:

  • message – Message to display

  • verbosity – Verbosity of message

  • interval – Interval for animation to play

  • unicorn – Enable unicorn mode

  • override_messages_stay_in_one_line – Override the message to stay in one line

Returns:

A NonBlockingAnimationTask if verbosity requirement is met.

animate_message_non_blocking(message: str, verbosity: int = 20, interval: int | float = 0.25, unicorn: bool = False, override_messages_stay_in_one_line: bool | None = None) → NonBlockingAnimationTask | None[source]

Display a loading animation in the background Stop animation by calling .stop() on the returned object

Parameters:

  • message – Message to display

  • verbosity – Verbosity of message

  • interval – Interval for animation to play

  • unicorn – Enable unicorn mode

  • override_messages_stay_in_one_line – Override the message to stay in one line

Returns:

NonBlockingAnimationTask if verbosity requirement is met.

ask(message: str, hide_input: bool = False, override_messages_stay_in_one_line: bool | None = None) → str[source]

Ask for input in format ? [prefix] message

Parameters:

  • message – Question to ask

  • hide_input – True hides user input

  • override_messages_stay_in_one_line – Override the message to stay in one line

Returns:

The user input as a string.

fail(message: str, verbosity: int = 50, override_messages_stay_in_one_line: bool | None = None) → None[source]

Send a failure message in format X [prefix] message

Parameters:

  • message – Message to send

  • verbosity – Verbosity of this message

  • override_messages_stay_in_one_line – Override the message to stay in one line

Returns:

None

info(message: str, verbosity: int = 20, override_messages_stay_in_one_line: bool | None = None) → None[source]

Print an informational message. Send an info message in format i [prefix] message

Parameters:

  • message – Message to send

  • verbosity – Verbosity of this message

  • override_messages_stay_in_one_line – Override the message to stay in one line

Returns:

None

list(message: str, verbosity: int = 20, override_messages_stay_in_one_line: bool | None = None) → None[source]

Send a list style message in format * [prefix] message

Parameters:

  • message – Message to send

  • verbosity – Verbosity of this message

  • override_messages_stay_in_one_line – Override the message to stay in one line

Returns:

None

log(message: str, verbosity: int = 10, override_messages_stay_in_one_line: bool | None = None) → None[source]

Send a log message in format LOG [prefix] message

Parameters:

  • message – Message to log

  • verbosity – Verbosity of this message

  • override_messages_stay_in_one_line – Override the message to stay in one line

Returns:

None

log_small(message: str, verbosity: int = 10, override_messages_stay_in_one_line: bool | None = None) → None[source]

Send a log message in format LOG [prefix] message

Parameters:

  • message – Message to log

  • verbosity – Verbosity of this message

  • override_messages_stay_in_one_line – Override the message to stay in one line

Returns:

None

message(message: str, verbosity: int = 20, override_messages_stay_in_one_line: bool | None = None) → None[source]

Send a message in format # [prefix] message

Parameters:

  • message – Message to send

  • verbosity – Verbosity of this message

  • override_messages_stay_in_one_line – Override the message to stay in one line

Returns:

None

static newline() → None[source]

Print a newline.

Returns:

None

progressbar(message: str, verbosity: int = 20, progress: int = 0, override_messages_stay_in_one_line: bool | None = True, show_percent: bool = False) → None[source]

Display a progress bar with specified progress This requires grabbing correct terminal width This is not animated. Call it multiple times to update

Parameters:

  • message – Message to display

  • verbosity – Verbosity to display

  • progress – Progress to display

  • override_messages_stay_in_one_line – Override the message to stay in one line

  • show_percent – Show percent next to the progressbar

Returns:

None

progressbar_animated_download(message: str, verbosity: int = 20, progress: int = 0, interval: int | float = 0.25, show_percent: bool = False, unicorn: bool = False, override_messages_stay_in_one_line: bool | None = True) → NonBlockingProgressTask[source]

Display an animated progressbar Update progress using the returned Task object

Parameters:

  • message – Message to display

  • verbosity – Verbosity of message

  • interval – Interval between animation frames

  • progress – Current Progress to display

  • show_percent – Show percent next to the progressbar

  • unicorn – Enable unicorn mode

  • override_messages_stay_in_one_line – Override the message to stay in one line

Returns:

NonBlockingProgressTask on which you can call update() and stop()

Return type:

NonBlockingProgressTask

progressbar_animated_normal(message: str, verbosity: int = 20, progress: int = 0, interval: int | float = 0.25, show_percent: bool = False, unicorn: bool = False, override_messages_stay_in_one_line: bool | None = True) → NonBlockingProgressTask[source]

Display an animated progressbar Update progress using the returned Task object

Parameters:

  • message – Message to display

  • verbosity – Verbosity of message

  • interval – Interval between animation frames

  • progress – Current Progress to display

  • show_percent – Show percent next to the progressbar

  • unicorn – Enable unicorn mode

  • override_messages_stay_in_one_line – Override the message to stay in one line

Returns:

NonBlockingProgressTask on which you can call update() and stop()

Return type:

NonBlockingProgressTask

progressbar_download(message: str, verbosity: int = 20, progress: int = 0, show_percent: bool = False, override_messages_stay_in_one_line: bool | None = True) → None[source]

Display a download bar with specified progress This is not animated. Call it multiple times to update

Parameters:

  • message – Message to display

  • verbosity – Verbosity to display

  • progress – Progress to display

  • show_percent – Show percent next to the progressbar

  • override_messages_stay_in_one_line – Override the message to stay in one line

Returns:

None

set_prefix(prefix: str) → None[source]

Update the message prefix of this instance. Prefixes should be three letters long but do as you wish.

Parameters:

prefix – New message prefix without brackets []

Returns:

None

set_seperator(seperator: str) → None[source]

Set the seperator between prefix and message

Parameters:

seperator – Seperator, usually only one character

Returns:

None

success(message: str, verbosity: int = 20, override_messages_stay_in_one_line: bool | None = None) → None[source]

Send a success message in format ✔ [prefix] message

Parameters:

  • message – Message to send

  • verbosity – Verbosity of this message

  • override_messages_stay_in_one_line – Override the message to stay in one line

Returns:

None

warn(message: str, verbosity: int = 30, override_messages_stay_in_one_line: bool | None = None) → None[source]

Send a warning message in format ! [prefix] message

Parameters:

  • message – Message to send

  • verbosity – Verbosity of this message

  • override_messages_stay_in_one_line – Override the message to stay in one line

Returns:

None

class cliasi.TextColor(*values)[source]

Bases: StrEnum

Different terminal colors to be used in the CLI.

Constants (Animations)

Constants used across the cliasi library.

This module defines animations and default settings for the CLI.

cliasi.constants.DEFAULT_TERMINAL_SIZE: int = 80

Default terminal size used for CLI rendering.

cliasi.constants.SYMBOLS: dict[str, str] = {'download': '⤓', 'success': '✔'}

Useful symbols to show in cli

class cliasi.constants.TextColor(*values)[source]

Bases: StrEnum

Different terminal colors to be used in the CLI.

BLACK = '\x1b[30m'
BLUE = '\x1b[34m'
BRIGHT_BLACK = '\x1b[90m'
BRIGHT_BLUE = '\x1b[94m'
BRIGHT_CYAN = '\x1b[96m'
BRIGHT_GREEN = '\x1b[92m'
BRIGHT_MAGENTA = '\x1b[95m'
BRIGHT_RED = '\x1b[91m'
BRIGHT_WHITE = '\x1b[97m'
BRIGHT_YELLOW = '\x1b[93m'
CYAN = '\x1b[36m'
DIM = '\x1b[2m'
GREEN = '\x1b[32m'
MAGENTA = '\x1b[35m'
RED = '\x1b[31m'
RESET = '\x1b[0m'
WHITE = '\x1b[37m'
YELLOW = '\x1b[33m'
cliasi.constants.UNICORN = ['\x1b[91m', '\x1b[93m', '\x1b[92m', '\x1b[96m', '\x1b[94m', '\x1b[95m']

Colors used for unicorn animation in the CLI.

logging handler

Logging handler for cliasi.

This module provides a custom logging handler that integrates with the Cliasi instance.

class cliasi.logging_handler.CLILoggingHandler(cli_instance: Cliasi)[source]

Bases: Handler

Logging handler that forwards records to the cliasi.cli Cliasi instance

Initialize the logging handler with a Cliasi instance

Parameters:

cli_instance – Cliasi instance (default cli instance)

cli: Cliasi
emit(record: LogRecord) → None[source]

Emit a log record to the Cliasi instance

Parameters:

record – logging.LogRecord

Returns:

None

cliasi.logging_handler.install_exception_hook(cli_instance: Cliasi) → None[source]

Install a global exception hook that logs uncaught exceptions to the Cliasi instance

Parameters:

cli_instance – Cliasi instance (default cli instance)

cliasi.logging_handler.install_logger(cli_instance: Cliasi, replace_root_handlers: bool = False) → None[source]

Install the CLILoggingHandler to the root logger

Parameters:

  • cli_instance – Cliasi instance (default cli instance)

  • replace_root_handlers – If True, existing StreamHandlers will be removed from the root logger so that only cliasi will print to the console. If False, existing StreamHandlers are left unchanged.

Returns:

None