API Reference¶

Top-level package¶

The main interface for cliasi.

cliasi exports the Cliasi instance cli as well as

STDOUT_STREAM standard output stream the library uses
STDERR_STREAM error stream the library uses
SYMBOLS collection of useful symbols
TextColor color storage for terminal text
CursorPos to set position of cursor on interactive methods
PBCalculationMode progress bar calculation modes.
install_logger() (to install it your own way, is done automatically)

cliasi.cli global cli instance: Cliasi¶

cliasi.STDOUT_STREAM io.TextIOWrapper¶: standard output stream the library uses

cliasi.STDERR_STREAM: io.TextIOWrapper¶: Error stream the library uses

cliasi.SYMBOLS¶: Collection of useful symbols

Cliasi instance¶

The main cliasi instance exposes various parameters to control behavior:

messages_stay_in_one_line - whether messages should stay in one line, see Cliasi instances
min_verbose_level - verbosity level, see Cliasi instances
enable_colors - weather to use colored output
max_dead_space - maximum number of empty space between aligned messages max_dead_space parameter

class cliasi.cliasi.Cliasi(prefix: str = '', messages_stay_in_one_line: bool | None = None, colors: bool = True, min_verbose_level: int | None = None, seperator: str = '|', max_dead_space: int | None = 150)[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 Setting this to None will result in the flag getting set to the value of the global instance which is by default False
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
max_dead_space – Sets the maximum dead space (space characters) allowed when a message uses alignments. Too much dead space will cause people to not read aligned messages. Set to None to disable.

Bases: object

Defines a non-blocking animation task run on another Thread

stop() → None[source]¶

Stop the current animation task

Returns:

Update message of animation

Parameters:

message_left – Message or bool flag to update to (None for no update)
message_center – Message or bool flag to update to (None for no update)
message_right – Message or bool flag to update to (None for no update)

Returns:

None

Bases: NonBlockingAnimationTask

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

Update progressbar message and progress

Parameters:

message_left – Message or bool flag to update to (None for no update)
message_center – Message or bool flag to update to (None for no update)
message_right – Message or bool flag to update to (None for no update)
progress – Progress to update to (None for no update)

Returns:

None

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

Parameters:

message_left – Message to send or bool flag to print left-aligned. See message_center and message_right for details.
time – Time to display for
message_center – Message or bool flag to print centered to terminal If messages do not fit into their sections or messages are multiline, they will be outputted one after the other (except for right aligned content) thus destroying any alignment.
message_right – Message or bool flag to print on right side of terminal If messages do not fit into their sections or messages are multiline, they will be outputted one after the other (except for right aligned content) thus destroying any alignment.
verbosity – Verbosity of this message
interval – Interval between changes in loading animation
unicorn – Enable unicorn mode
messages_stay_in_one_line – Override the message to stay in one line (None to use cliasi instance setting)

Returns:

None

Display a downloading animation in the background

Parameters:

message_left – Message to send or bool flag to print left-aligned. See message_center and message_right for details.
message_center – Message or bool flag to print centered to terminal If messages do not fit into their sections or messages are multiline, they will be outputted one after the other (except for right aligned content) thus destroying any alignment.
message_right – Message or bool flag to print on right side of terminal If messages do not fit into their sections or messages are multiline, they will be outputted one after the other (except for right aligned content) thus destroying any alignment.
verbosity – Verbosity of message
interval – Interval for animation to play
unicorn – Enable unicorn mode
messages_stay_in_one_line – Override the message to stay in one line (None to use cliasi instance setting)

Returns:

A NonBlockingAnimationTask if verbosity requirement is met.

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

Parameters:

message_left – Message to send or bool flag to print left-aligned. See message_center and message_right for details.
message_center – Message or bool flag to print centered to terminal If messages do not fit into their sections or messages are multiline, they will be outputted one after the other (except for right aligned content) thus destroying any alignment.
message_right – Message or bool flag to print on right side of terminal If messages do not fit into their sections or messages are multiline, they will be outputted one after the other (except for right aligned content) thus destroying any alignment.
verbosity – Verbosity of message
interval – Interval for animation to play
unicorn – Enable unicorn mode
messages_stay_in_one_line – Override the message to stay in one line (None to use cliasi instance setting)

Returns:

NonBlockingAnimationTask if verbosity requirement is met.

Ask for input in format ? [prefix] message

Parameters:

message_left – Question to ask Can also be a bool flag to print left-aligned.
hide_input – True hides user input
message_center – Message or bool flag to print centered to terminal If messages do not fit into their sections or messages are multiline, they will be outputted one after the other (except for right aligned content) thus destroying any alignment.
message_right – Message or bool flag to print on right side of terminal If messages do not fit into their sections or messages are multiline, they will be outputted one after the other (except for right aligned content) thus destroying any alignment.
messages_stay_in_one_line – Override the message to stay in one line
cursor_position – Cursor position of input cursor Only available when output is not longer than one line OR if last line has space for message_right and the cursor position is LEFT or RIGHT

Returns:

The user input as a string.

enable_colors: bool¶

Send a failure message in format X [prefix] message

Parameters:

message_left – Message to send or bool flag to print left-aligned. See message_center and message_right for details.
verbosity – Verbosity of this message
message_center – Message or bool flag to print centered to terminal If messages do not fit into their sections or messages are multiline, they will be outputted one after the other (except for right aligned content) thus destroying any alignment.
message_right – Message or bool flag to print on right side of terminal If messages do not fit into their sections or messages are multiline, they will be outputted one after the other (except for right aligned content) thus destroying any alignment.
messages_stay_in_one_line – Override the message to stay in one line (None to use cliasi instance setting)

Returns:

None

infer_settings() → None[source]¶: Infer settings from the global cli instance.

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

Parameters:

message_left – Message to send or bool flag to print left-aligned. See message_center and message_right for details.
verbosity – Verbosity of this message
message_center – Message or bool flag to print centered to terminal If messages do not fit into their sections or messages are multiline, they will be outputted one after the other (except for right aligned content) thus destroying any alignment.
message_right – Message or bool flag to print on right side of terminal If messages do not fit into their sections or messages are multiline, they will be outputted one after the other (except for right aligned content) thus destroying any alignment.
messages_stay_in_one_line – Override the message to stay in one line (None to use cliasi instance setting)

Returns:

None

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

Parameters:

message_left – Message to send or bool flag to print left-aligned. See message_center and message_right for details.
verbosity – Verbosity of this message
message_center – Message or bool flag to print centered to terminal If messages do not fit into their sections or messages are multiline, they will be outputted one after the other (except for right aligned content) thus destroying any alignment.
message_right – Message or bool flag to print on right side of terminal If messages do not fit into their sections or messages are multiline, they will be outputted one after the other (except for right aligned content) thus destroying any alignment.
messages_stay_in_one_line – Override the message to stay in one line (None to use cliasi instance setting)

Returns:

None

Send a log message in format LOG [prefix] message

Parameters:

message_left – Message to send or bool flag to print left-aligned. See message_center and message_right for details.
verbosity – Verbosity of this message
message_center – Message or bool flag to print centered to terminal If messages do not fit into their sections or messages are multiline, they will be outputted one after the other (except for right aligned content) thus destroying any alignment.
message_right – Message or bool flag to print on right side of terminal If messages do not fit into their sections or messages are multiline, they will be outputted one after the other (except for right aligned content) thus destroying any alignment.
messages_stay_in_one_line – Override the message to stay in one line (None to use cliasi instance setting)

Returns:

None

Send a log message in format LOG [prefix] message

Parameters:

message_left – Message to send or bool flag to print left-aligned. See message_center and message_right for details.
verbosity – Verbosity of this message
message_center – Message or bool flag to print centered to terminal If messages do not fit into their sections or messages are multiline, they will be outputted one after the other (except for right aligned content) thus destroying any alignment.
message_right – Message or bool flag to print on right side of terminal If messages do not fit into their sections or messages are multiline, they will be outputted one after the other (except for right aligned content) thus destroying any alignment.
messages_stay_in_one_line – Override the message to stay in one line (None to use cliasi instance setting)

Returns:

None

max_dead_space: int | None¶

Send a message in format # [prefix] message

Parameters:

message_left – Message to send or bool flag to print left-aligned. See message_center and message_right for details.
verbosity – Verbosity of this message
message_center – Message or bool flag to print centered to terminal If messages do not fit into their sections or messages are multiline, they will be outputted one after the other (except for right aligned content) thus destroying any alignment.
message_right – Message or bool flag to print on right side of terminal If messages do not fit into their sections or messages are multiline, they will be outputted one after the other (except for right aligned content) thus destroying any alignment.
messages_stay_in_one_line – Override the message to stay in one line (None to use cliasi instance setting)

Returns:

None

messages_stay_in_one_line: bool¶

min_verbose_level: int¶

static newline() → None[source]¶

Print a newline.

Returns:: None

progressbar(message_left: str | bool | None, message_center: str | bool | None = False, message_right: str | bool | None = False, cover_dead_space_with_bar: bool = False, calculation_mode: PBCalculationMode = PBCalculationMode.FULL_WIDTH, verbosity: int = 20, progress: int = 0, messages_stay_in_one_line: bool | None = True, show_percent: bool = False) → None[source]¶

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

Parameters:

message_left – Message to display on the left side of the bar or bool flag to enable / disable
message_center – Message to display in the center of the bar or bool flag to enable / disable
message_right – Message to display on the right side of the bar or bool flag to enable / disable
cover_dead_space_with_bar – Cover the space between messages with the progressbar If True, looks like this: [=message== … ] If False, looks like this: [ message ===== … ]
calculation_mode – How to fill the progressbar. Set to FULL_WIDTH for bar to go trough messages. Set to ONLY_EMPTY to fill empty space between messages only. Set to FULL_WIDTH_OVERWRITE to overwrite messages with the bar.
verbosity – Verbosity to display
progress – Progress to display
messages_stay_in_one_line – Override the message to stay in one line (None to use cliasi instance setting)
show_percent – Show percent next to the progressbar

Returns:

None

progressbar_animated_download(message_left: str | bool | None, message_center: str | bool | None = False, message_right: str | bool | None = False, cover_dead_space_with_bar: bool = False, calculation_mode: PBCalculationMode = PBCalculationMode.FULL_WIDTH, verbosity: int = 20, progress: int = 0, interval: int | float = 0.25, show_percent: bool = False, unicorn: bool = False, messages_stay_in_one_line: bool | None = True) → NonBlockingProgressTask[source]¶

Display an animated progressbar Update progress using the returned Task object

Parameters:

message_left – Message to display on the left side of the bar or bool flag to enable / disable
message_center – Message to display in the center of the bar or bool flag to enable / disable
message_right – Message to display on the right side of the bar or bool flag to enable / disable
cover_dead_space_with_bar – Cover the space between messages with the progressbar If True, looks like this: [=message== … ] If False, looks like this: [ message ===== … ]
calculation_mode – How to fill the progressbar. Set to FULL_WIDTH for bar to go trough messages. Set to ONLY_EMPTY to fill empty space between messages only. Set to FULL_WIDTH_OVERWRITE to overwrite messages with the bar.
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
messages_stay_in_one_line – Override the message to stay in one line (None to use cliasi instance setting)

Returns:

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

Return type:

NonBlockingProgressTask

progressbar_animated_normal(message_left: str | bool | None, message_center: str | bool | None = False, message_right: str | bool | None = False, cover_dead_space_with_bar: bool = False, calculation_mode: PBCalculationMode = PBCalculationMode.FULL_WIDTH, verbosity: int = 20, progress: int = 0, interval: int | float = 0.25, show_percent: bool = False, unicorn: bool = False, messages_stay_in_one_line: bool | None = True) → NonBlockingProgressTask[source]¶

Display an animated progressbar Update progress using the returned Task object

Parameters:

message_left – Message to display on the left side of the bar or bool flag to enable / disable
message_center – Message to display in the center of the bar or bool flag to enable / disable
message_right – Message to display on the right side of the bar or bool flag to enable / disable
cover_dead_space_with_bar – Cover the space between messages with the progressbar If True, looks like this: [=message== … ] If False, looks like this: [ message ===== … ]
calculation_mode – How to fill the progressbar. Set to FULL_WIDTH for bar to go trough messages. Set to ONLY_EMPTY to fill empty space between messages only. Set to FULL_WIDTH_OVERWRITE to overwrite messages with the bar.
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
messages_stay_in_one_line – Override the message to stay in one line (None to use cliasi instance setting)

Returns:

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

Return type:

NonBlockingProgressTask

progressbar_download(message_left: str | bool | None, message_center: str | bool | None = False, message_right: str | bool | None = False, cover_dead_space_with_bar: bool = False, calculation_mode: PBCalculationMode = PBCalculationMode.FULL_WIDTH, verbosity: int = 20, progress: int = 0, show_percent: bool = False, 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_left – Message to display on the left side of the bar or bool flag to enable / disable
message_center – Message to display in the center of the bar or bool flag to enable / disable
message_right – Message to display on the right side of the bar or bool flag to enable / disable
cover_dead_space_with_bar – Cover the space between messages with the progressbar If True, looks like this: [=message== … ] If False, looks like this: [ message ===== … ]
calculation_mode – How to fill the progressbar. Set to FULL_WIDTH for bar to go trough messages. Set to ONLY_EMPTY to fill empty space between messages only. Set to FULL_WIDTH_OVERWRITE to overwrite messages with the bar.
verbosity – Verbosity to display
progress – Progress to display
show_percent – Show percent next to the progressbar
messages_stay_in_one_line – Override the message to stay in one line (None to use cliasi instance setting)

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

Send a success message in format ✔ [prefix] message

Parameters:

message_left – Message to send or bool flag to print left-aligned. See message_center and message_right for details.
verbosity – Verbosity of this message
message_center – Message or bool flag to print centered to terminal If messages do not fit into their sections or messages are multiline, they will be outputted one after the other (except for right aligned content) thus destroying any alignment.
message_right – Message or bool flag to print on right side of terminal If messages do not fit into their sections or messages are multiline, they will be outputted one after the other (except for right aligned content) thus destroying any alignment.
messages_stay_in_one_line – Override the message to stay in one line (None to use cliasi instance setting)

Returns:

None

Send a warning message in format ! [prefix] message

Parameters:

message_left – Message to send or bool flag to print left-aligned. See message_center and message_right for details.
verbosity – Verbosity of this message
message_center – Message or bool flag to print centered to terminal If messages do not fit into their sections or messages are multiline, they will be outputted one after the other (except for right aligned content) thus destroying any alignment.
message_right – Message or bool flag to print on right side of terminal If messages do not fit into their sections or messages are multiline, they will be outputted one after the other (except for right aligned content) thus destroying any alignment.
messages_stay_in_one_line – Override the message to stay in one line (None to use cliasi instance setting)

Returns:

None

cliasi.cliasi.STDERR_STREAM: TextIO = <_io.TextIOWrapper name='<stderr>' mode='w' encoding='utf-8'>¶: Default stderr stream for cliasi messages. Used by all Cliasi instances

cliasi.cliasi.STDOUT_STREAM: TextIO = <_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>¶: Default stdout stream for cliasi messages. Used by all Cliasi instances

cliasi.cliasi.cli: Cliasi = <cliasi.cliasi.Cliasi object>¶: Default Cliasi instance (shows INFO and above by default)

Constants (Animations)¶

Constants used across the cliasi library.

This module defines animations and default settings for the CLI.

class cliasi.constants.CursorPos(*values)[source]¶

Bases: StrEnum

Cursor positions for user input Useful in ask() method.

CENTER = 'CENTER'¶

LEFT = 'LEFT'¶

RIGHT = 'RIGHT'¶

cliasi.constants.DEFAULT_TERMINAL_SIZE: int = 80¶: Default terminal size used for CLI rendering.

class cliasi.constants.PBCalculationMode(*values)[source]¶

Bases: StrEnum

Progressbar calculation modes for the CLI progress bars.

FULL_WIDTH_OVERWRITE:
The progress characters go all the way from left to right and overwrite any text
FULL_WIDTH:

The progress characters go all the way from left to right but
don’t overwrite any text.
ONLY_EMPTY:
The progress characters only fill the empty space between the text.

FULL_WIDTH = 'FULL_WIDTH'¶

FULL_WIDTH_OVERWRITE = 'FULL_WIDTH_OVERWRITE'¶

ONLY_EMPTY = 'ONLY_EMPTY'¶

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