framed_text package

Submodules

framed_text.framed_header module

class framed_text.framed_header.FramedHeader(title: str = '', frame_color: str | tuple[int, int, int] = '', title_color: str | tuple[int, int, int] = '', divider: str = '─', attrs: list[str] | None = None)[source]

Bases: object

__init__(title: str = '', frame_color: str | tuple[int, int, int] = '', title_color: str | tuple[int, int, int] = '', divider: str = '─', attrs: list[str] | None = None)[source]

Creates a string with a customizable divider. Can include a title. Matches the style of FramedText.

Attributes:

All termcolor attributes are supported: "bold", "dark", "italic", "underline", "reverse", "concealed", "strike"

Parameters:

title – Title to display in the header
frame_color – Color of the frame. Valid colors based off of termcolor’s color options: string color code or RGB tuple
title_color – Color of the title. Valid colors based off of termcolor’s color options: string color code or RGB tuple
divider – Divider to use. Will be repeated to fill the terminal width
attrs – Attributes to apply to the title. See list above for valid attributes

framed_text.framed_text module

Bases: object

Creates a string with a customizable frame around it. Frame is based off of prompt_toolkit’s show_frame option, but with more customization and designed for print statements.

Cutoff Modes:

char: Cutoff char at end of text (The quick brown fox jumped ove…)
word: Cutoff word at end of text (The quick brown fox jumped…)
middle: Cutoff chars at middle of text (The quick brown…the lazy dog)

Frame Sizes: - full: Frame will be the size of the terminal - dynamic: Frame will be the size of the text based on longest line.

Attributes:

All termcolor attributes are supported: "bold", "dark", "italic", "underline", "reverse", "concealed", "strike"

NOTE: allow_ansi only applies to strings

Parameters:

text – Text to be framed. Can be a regular string or a LabeledData object
title – Title of the frame
mode – Mode for cutoff. “char” for character cutoff, “word” for word cutoff, “middle” for middle cutoff
frame_color – Color of the frame. Valid colors based off of termcolor’s color options: string color code or RGB tuple
title_color – Color of the title. Valid colors based off of termcolor’s color options: string color code or RGB tuple
cutoff – If true, cut off text if it exceeds terminal width. Default is True (Recommended)
allow_ansi – If True, Allows ANSI on long lines (Highly experimental. Use at your own risk). If False, removes all ANSI from non-LabeledData objects on long lines.
center_text – If True, centers the text inside frame. Centers whole frame if frame_size="dynamic"
frame_size – Size of the frame. “full” for terminal size, “dynamic” for text size
attrs – Attributes to apply to the title. See list above for valid attributes

framed_text.framed_text.frame_draw_bottom(frame_color: str | tuple[int, int, int] | None = None, frame_size: Literal['full', 'dynamic'] = 'full', line_len: int = -1) → str[source]: Draw the bottom half of the frame :param frame_color: Optional frame color :param frame_size: Size of the frame. “full” for terminal size, “dynamic” for text size :param line_len: Length of the longest line of the text. Used with frame_size="dynamic" :return: Bottom half of the frame

framed_text.framed_text.frame_draw_top(title: str | None = None, title_len: int = 0, frame_size: Literal['full', 'dynamic'] = 'full', line_len: int = -1, frame_color: str | tuple[int, int, int] | None = None) → str[source]: Draw the top half of the frame :param title: Optional title :param title_len: Length of the title :param frame_size: Size of the frame. “full” for terminal size, “dynamic” for text size :param line_len: Length of the longest line of the text. Used with frame_size="dynamic" :param frame_color: Optional frame color :return: Top half of the frame

framed_text.labeled_data module

class framed_text.labeled_data.LabeledData[source]

Bases: object

Class for creating a string with a label and different types of data. Each item can be configured to include colored text.

class Boolean(label: str, value: bool, suffix: str = '', t_color: str | tuple[int, int, int] | None = 'green', f_color: str | tuple[int, int, int] | None = 'red', label_color: str | tuple[int, int, int] | None = None, suffix_color: str | tuple[int, int, int] | None = None, t_text: str = 'True', f_text: str = 'False', quotes: bool = False, colon_match: bool = True, no_colon: bool = False, val_attrs: list[str] | None = None, label_attrs: list[str] | None = None, suffix_attrs: list[str] | None = None)[source]

Bases: object

__init__(label: str, value: bool, suffix: str = '', t_color: str | tuple[int, int, int] | None = 'green', f_color: str | tuple[int, int, int] | None = 'red', label_color: str | tuple[int, int, int] | None = None, suffix_color: str | tuple[int, int, int] | None = None, t_text: str = 'True', f_text: str = 'False', quotes: bool = False, colon_match: bool = True, no_colon: bool = False, val_attrs: list[str] | None = None, label_attrs: list[str] | None = None, suffix_attrs: list[str] | None = None)[source]

Creates a string with a label and boolean value

Parameters:

label – Label for boolean value
value – Boolean value
suffix – Optional text to appear after the value
t_color – Color of true value.
f_color – Color of false value.
label_color – Color of label.
suffix_color – Color of suffix.
t_text – Text to display for true value
f_text – Text to display for false value
quotes – If true, wrap text in single quotes (‘)
colon_match – If true, the colon will match the style of the label.
no_colon – If true, the colon will be removed. Overrides colon_match
val_attrs – Attributes to apply to the value.
label_attrs – Attributes to apply to the label.
suffix_attrs – Attributes to apply to the suffix.

cutoff_text(limit: int) → str[source]

Cuts off text if it exceeds limit. Will first try to shorten bool value. If there isn’t enough space for just an ellipsis, it will try to shorten the label, so that the output will be 50/50 (label: value).

Parameters:: limit – Maximum length of text
Returns:: Shortened text

class Bytes(label: str, value: int, suffix: str = '', suffix_color: str | tuple[int, int, int] | None = None, val_color: str | tuple[int, int, int] | None = 'yellow', label_color: str | tuple[int, int, int] | None = None, unit_color: str | tuple[int, int, int] | None = None, quotes: bool = False, colon_match: bool = True, unit_match: bool = True, no_colon: bool = False, show_unit: bool = True, unit_type: Literal['iec', 'si'] = 'iec', val_attrs: list[str] | None = None, label_attrs: list[str] | None = None, suffix_attrs: list[str] | None = None, unit_attrs: list[str] | None = None)[source]

Bases: object

__init__(label: str, value: int, suffix: str = '', suffix_color: str | tuple[int, int, int] | None = None, val_color: str | tuple[int, int, int] | None = 'yellow', label_color: str | tuple[int, int, int] | None = None, unit_color: str | tuple[int, int, int] | None = None, quotes: bool = False, colon_match: bool = True, unit_match: bool = True, no_colon: bool = False, show_unit: bool = True, unit_type: Literal['iec', 'si'] = 'iec', val_attrs: list[str] | None = None, label_attrs: list[str] | None = None, suffix_attrs: list[str] | None = None, unit_attrs: list[str] | None = None)[source]

Creates a string with a label and bytes value

Parameters:

label – Label for string value
value – Integer value. Value MUST be in bytes
suffix – Optional text to appear after the value
val_color – Color of string value.
label_color – Color of label.
unit_color – Color of unit. Overrides unit_match.
quotes – If true, wrap text in single quotes (‘)
colon_match – If true, the colon will match the style of the label.
unit_match – If true, the unit will match the style of the value.
no_colon – If true, the colon will be removed. Overrides colon_match
show_unit – If true, the unit will be shown.
unit_type – Unit type: IEC is base 2, SI is base 10
val_attrs – Attributes to apply to the value.
label_attrs – Attributes to apply to the label.
unit_attrs – Attributes to apply to the unit. Overrides unit_match.

cutoff_text(limit: int) → str[source]

Cuts off text if it exceeds limit. Will NOT shorten the value, only suffix (if there is one). If there isn’t enough space for just an ellipsis, it will try to shorten the label, so that the output will be 50/50 (label: value).

Parameters:: limit – Maximum length of text
Returns:: Shortened text

class Date(label: str, value: str | datetime = '', suffix: str = '', strftime: str = '%Y-%m-%d %H:%M:%S', suffix_color: str | tuple[int, int, int] | None = None, val_color: str | tuple[int, int, int] | None = 'blue', label_color: str | tuple[int, int, int] | None = None, quotes: bool = True, colon_match: bool = True, no_colon: bool = False, val_attrs: list[str] | None = None, label_attrs: list[str] | None = None, suffix_attrs: list[str] | None = None)[source]

Bases: object

__init__(label: str, value: str | datetime = '', suffix: str = '', strftime: str = '%Y-%m-%d %H:%M:%S', suffix_color: str | tuple[int, int, int] | None = None, val_color: str | tuple[int, int, int] | None = 'blue', label_color: str | tuple[int, int, int] | None = None, quotes: bool = True, colon_match: bool = True, no_colon: bool = False, val_attrs: list[str] | None = None, label_attrs: list[str] | None = None, suffix_attrs: list[str] | None = None)[source]

Creates a string with a label and a date value

If no value is passed, will print current time using strftime parameter :param label: Label for string value :param value: Value, either as a datetime object or string :param suffix: Optional text to appear after the value :param strftime: Formatter for datetime value :param val_color: Color of string value. :param label_color: Color of label. :param quotes: If true, wrap text in single quotes (‘) :param colon_match: If true, the colon will match the style of the label. :param no_colon: If true, the colon will be removed. Overrides colon_match :param val_attrs: Attributes to apply to the value. :param label_attrs: Attributes to apply to the label.

cutoff_text(limit: int) → str[source]

Cuts off text if it exceeds limit. Will first try to shorten string. If there isn’t enough space for just an ellipsis, it will try to shorten the label, so that the output will be 50/50 (label: value).

Parameters:: limit – Maximum length of text
Returns:: Shortened text

Bases: object

Creates a string with a label and number value

Parameters:

label – Label for number value
value – Number value
suffix – Optional text to appear after the value
round_to – Number of decimal places to round to. Leave blank to not round.
leading_zeros – Number of leading zeros to add to the number. Leave blank to not add leading zeros.
int_no_round – If true, displays number as integer without rounding. Overrides round_to
val_color – Color of number value.
label_color – Color of label.
suffix_color – Color of suffix.
quotes – If true, wrap text in single quotes (‘)
colon_match – If true, the colon will match the style of the label.
no_colon – If true, the colon will be removed. Overrides colon_match
val_attrs – Attributes to apply to the value.
label_attrs – Attributes to apply to the label.

cutoff_text(limit: int) → str[source]

Cuts off text if it exceeds limit. Will NOT shorten the number, only the suffix (if there is one). If there isn’t enough space for just an ellipsis, it will try to shorten the label, so that the output will be 50/50 (label: value).

Parameters:: limit – Maximum length of text
Returns:: Shortened text

Bases: object

Creates a string with a label and path to a file or directory

Parameters:

label – Label for path
value – Path to file or directory
suffix – Optional text to appear after the value
quotes – If true, wrap path in single quotes (‘)
val_color – Color of path value.
label_color – Color of label.
suffix_color – Color of suffix.
colon_match – If true, the colon will match the style of the label.
no_colon – If true, the colon will be removed. Overrides colon_match
val_attrs – Attributes to apply to the value.
label_attrs – Attributes to apply to the label.
suffix_attrs – Attributes to apply to the suffix.

cutoff_text(limit: int, mode: Literal['char', 'word', 'middle'] = 'char') → str[source]

Shortens path to limit.

Modes: - char: Cutoff char at end of string (/path/to/a/f…) - word: Cutoff path at end, preserve the deepest directory/file (/path/to/…/file.txt) - middle: Cutoff chars at middle of string (/long/path/t…/an/file.txt)

Parameters:

limit – Character limit for full labeled path string
mode – How to cut off path.

Returns:

LabeledData.Path string with shortened path if it exceeds limit, else returns original string

class String(label: str, value: str, suffix: str = '', suffix_color: str | tuple[int, int, int] | None = None, val_color: str | tuple[int, int, int] | None = 'cyan', label_color: str | tuple[int, int, int] | None = None, quotes: bool = True, colon_match: bool = True, no_colon: bool = False, val_attrs: list[str] | None = None, label_attrs: list[str] | None = None, suffix_attrs: list[str] | None = None)[source]

Bases: object

__init__(label: str, value: str, suffix: str = '', suffix_color: str | tuple[int, int, int] | None = None, val_color: str | tuple[int, int, int] | None = 'cyan', label_color: str | tuple[int, int, int] | None = None, quotes: bool = True, colon_match: bool = True, no_colon: bool = False, val_attrs: list[str] | None = None, label_attrs: list[str] | None = None, suffix_attrs: list[str] | None = None)[source]

Creates a string with a label and string value

Parameters:

label – Label for string value
value – String value
suffix – Optional text to appear after the value
val_color – Color of string value.
label_color – Color of label.
quotes – If true, wrap text in single quotes (‘)
colon_match – If true, the colon will match the style of the label.
no_colon – If true, the colon will be removed. Overrides colon_match
val_attrs – Attributes to apply to the value.
label_attrs – Attributes to apply to the label.

cutoff_text(limit: int, mode: Literal['char', 'word', 'middle'] = 'char') → str[source]

Cuts off text if it exceeds limit. Will first try to shorten string. If there isn’t enough space for just an ellipsis, it will try to shorten the label, so that the output will be 50/50 (label: value).

Modes: - char: Cutoff char at end of string (The quick brown fox jumped ove…) - word: Cutoff word at end of string (The quick brown fox jumped…) - middle: Cutoff words at middle of string (The quick brown…the lazy dog)

Parameters:

limit – Maximum length of text
mode – How to cut off value text

Returns:

Shortened text

framed_text.progress_bar module

class framed_text.progress_bar.ProgressBar(value: int, total: int, label: str = '', show_frame: bool = False, show_percent: bool = True, show_values: bool = False, progress_icon: str = '#', empty_icon: str = '.', brackets: tuple[str, str] = ('[', ']'), value_color: str | tuple[int, int, int] | None = None, label_color: str | tuple[int, int, int] | None = None, percent_color: str | tuple[int, int, int] | None = None, progress_color: str | tuple[int, int, int] | None = None, brackets_color: str | tuple[int, int, int] | None = None, frame_color: str | tuple[int, int, int] | None = None, safe_mode: bool = False, skip_init: bool = False)[source]

Bases: object

__init__(value: int, total: int, label: str = '', show_frame: bool = False, show_percent: bool = True, show_values: bool = False, progress_icon: str = '#', empty_icon: str = '.', brackets: tuple[str, str] = ('[', ']'), value_color: str | tuple[int, int, int] | None = None, label_color: str | tuple[int, int, int] | None = None, percent_color: str | tuple[int, int, int] | None = None, progress_color: str | tuple[int, int, int] | None = None, brackets_color: str | tuple[int, int, int] | None = None, frame_color: str | tuple[int, int, int] | None = None, safe_mode: bool = False, skip_init: bool = False)[source]

Display a progress bar that shows the progress from a value to a total.

The progress bar will snap to the bottom of the terminal.

Parameters:

value – Current value
total – Total value
label – Optional label for the Progress Bar
show_frame – If true, will show a frame around the progress bar, similar to FramedText
show_percent – If true, will show percentage of progress. Will replace values display unless show_values is true
show_values – If true, will show current value and total value. If false and show_percent is false, will not display any values
progress_icon – Icon used for the progress display
empty_icon – Icon used for the empty space in the progress display
brackets – Brackets to surround the progress display. First value is the left bracket, second value is the right bracket
value_color – Color of the label
label_color – Color of the label
percent_color – Color of the percentage
progress_color – Color of the progress display
brackets_color – Color of the brackets
frame_color – Color of the frame
safe_mode – If true, will clear the terminal and move cursor to top to ensure room for progress bar and any other data.
skip_init – If true, will only initialize when display or update_progress is called

display()[source]: Display the progress bar

static force_reset(show_frame: bool = False, label: bool = False)[source]

Force resets the terminal. This should only be used in the except block of a try-except block.

Make sure to pass the same values to this function that were passed to the ProgressBar constructor, otherwise the reset may not work as expected.

NOTE: This method does not change ProgressBar._term_is_init. If you plan to re-use the progress bar after a force reset, you will need to call ProgressBar._init_term manually.

This function behaves like ProgressBar.reset

Parameters:

show_frame – Whether show_frame was enabled for the progress bar.
label – Whether label was enabled for the progress bar.

reset()[source]

update_progress(value: int | None = None, total: int | None = None)[source]

framed_text.shorten_text module

Bases: object

Shorten text to a specified limit. Supports LabeledData, Status and regular strings.

Modes

char: Cutoff char at end of text (The quick brown fox jumped ove…)
word: Cutoff word at end of text (The quick brown fox jumped…)
middle: Cutoff chars at middle of text (The quick brown…the lazy dog)

Parameters:

text – Text to shorten
limit – Limit. Text will be shortened to this length. If no limit is passed, will default to the width of the terminal.
allow_ansi – If true, allow ANSI codes in the text. This parameter only applies to regular strings.
mode – Mode to use to shorten text. See above for more info.

framed_text.spinner module

Bases: object

BUILTIN_ICONS: dict[str, list[str]] = {'cube': ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'], 'default': ['/', '-', '\\', '|'], 'dots': [' ', '. ', '.. ', '...'], 'dots2': [' ', '. ', '.. ', '...', ' ..', ' .']}

Draws a spinner on a screen

Position

"start": The spinner will be placed at the start of the line.
"end": The spinner will be placed at the end of the line.

Parameters:

text – Text to display next to the spinner. Omit for no text.
icons_id – ID string of one of the built-in icon sets from Spinner.BUILTIN_ICONS
done_icon – Icon to use for when the spinner is complete
custom_icons – A list of strings to use as the spinner icon. Overrides icons_id
interval – The delay between spinner icon updates.
position – Where the spinner should be placed on a line.
indent – How many spaces the line should be indented.
spinner_color – Color of the spinner icon while active.
done_color – Color for the spinner icon when stopped.

start(text: str = '')[source]

Start the spinner

Parameters:: text – Text to display next to the spinner. Omit for no text.

stop(done_icon: str | None = None, done_color: str | tuple[int, int, int] | None = None)[source]

Stop the spinner

Optionally, allow custom done icon and color for the current spinner. :param done_icon: Icon to use for when the spinner is complete :param done_color: Color for the done icon

Update values for the spinner.

Some values can only be updated when the spinner is not running.

Position

"start": The spinner will be placed at the start of the line.
"end": The spinner will be placed at the end of the line.

Parameters:

text – Text to display next to the spinner. Omit for no text.
icons_id – ID string of one of the built-in icon sets from Spinner.BUILTIN_ICONS
done_icon – Icon to use for when the spinner is complete
custom_icons – A list of strings to use as the spinner icon. Overrides icons_id
interval – The delay between spinner icon updates.
position – Where the spinner should be placed on a line.
indent – How many spaces the line should be indented.
spinner_color – Color of the spinner icon while active.
done_color – Color for the spinner icon when stopped.

framed_text.status module

Bases: object

Status base class. Can be used to create custom status classes.

Predefined Status classes are available in the Status class.

Parameters:

msg – Message to display after the icon
icon – Character(s) to use as the icon. Icon can be any size. If no icon, seperator is not used.
icon_color – Color of the icon. Can be a termcolor color code or an RGB tuple
icon_attrs – Attributes of the icon. Can be a list of termcolor attributes
sep – Seperator between icon and message. Will only be used when message is provided.
msg_color – Color of the message. Can be a termcolor color code or an RGB tuple
msg_attrs – Attributes of the message. Can be a list of termcolor attributes
overwrite – If true, will overwrite the previous line with a new status.

cutoff_text(limit: int, mode: Literal['char', 'word', 'middle'] = 'char') → str[source]

Cutoffs text if it exceeds limit. Icon and seperator will always be shortened by character.

Modes

char: Cutoff char at end of text (The quick brown fox jumped ove…)
word: Cutoff word at end of text (The quick brown fox jumped…)
middle: Cutoff chars at middle of text (The quick brown…the lazy dog)

Parameters:

limit – Maximum length of text
mode – Mode to use for shortening. See above for info.

Returns:

Cutoff text

class framed_text.status.Status[source]

Bases: object

Predefined Status classes. Can be used with LabeledData and regular strings. Each Status optionally takes a message and text color which creates a string in the format: <icon> <message>

Custom Status classes can be created from the BaseStatus class.

Bases: BaseStatus

Parameters:

msg – Message to display after the icon
icon – Character(s) to use as the icon. Icon can be any size.
icon_color – Color of the icon. Can be a termcolor color code or an RGB tuple
icon_attrs – Attributes to apply to the icon. Can be a list of termcolor attributes
sep – Seperator between icon and message. Will only be used when message is provided.
msg_color – Color of the message. Can be a termcolor color code or an RGB tuple
msg_attrs – Attributes to apply to the message. Can be a list of termcolor attributes
overwrite – If true, will overwrite the previous line with a new status.

Status base class. Can be used to create custom status classes.

Predefined Status classes are available in the Status class.

Parameters:

msg – Message to display after the icon
icon – Character(s) to use as the icon. Icon can be any size. If no icon, seperator is not used.
icon_color – Color of the icon. Can be a termcolor color code or an RGB tuple
icon_attrs – Attributes of the icon. Can be a list of termcolor attributes
sep – Seperator between icon and message. Will only be used when message is provided.
msg_color – Color of the message. Can be a termcolor color code or an RGB tuple
msg_attrs – Attributes of the message. Can be a list of termcolor attributes
overwrite – If true, will overwrite the previous line with a new status.

Bases: BaseStatus

Parameters:

msg – Message to display after the icon
icon – Character(s) to use as the icon. Icon can be any size.
icon_color – Color of the icon. Can be a termcolor color code or an RGB tuple
icon_attrs – Attributes to apply to the icon. Can be a list of termcolor attributes
sep – Seperator between icon and message. Will only be used when message is provided.
msg_color – Color of the message. Can be a termcolor color code or an RGB tuple
msg_attrs – Attributes to apply to the message. Can be a list of termcolor attributes
overwrite – If true, will overwrite the previous line with a new status.

Status base class. Can be used to create custom status classes.

Predefined Status classes are available in the Status class.

Parameters:

msg – Message to display after the icon
icon – Character(s) to use as the icon. Icon can be any size. If no icon, seperator is not used.
icon_color – Color of the icon. Can be a termcolor color code or an RGB tuple
icon_attrs – Attributes of the icon. Can be a list of termcolor attributes
sep – Seperator between icon and message. Will only be used when message is provided.
msg_color – Color of the message. Can be a termcolor color code or an RGB tuple
msg_attrs – Attributes of the message. Can be a list of termcolor attributes
overwrite – If true, will overwrite the previous line with a new status.

Bases: BaseStatus

A special status which shows the text in a dark color. An alternative to Status.Action

Parameters:

msg – Message to display after the icon
icon – Character(s) to use as the icon. Icon can be any size.
icon_color – Color of the icon. Can be a termcolor color code or an RGB tuple
icon_attrs – Attributes to apply to the icon. Can be a list of termcolor attributes
sep – Seperator between icon and message. Will only be used when message is provided.
msg_color – Color of the message. Can be a termcolor color code or an RGB tuple
msg_attrs – Attributes to apply to the message. Can be a list of termcolor attributes
overwrite – If true, will overwrite the previous line with a new status.

Status base class. Can be used to create custom status classes.

Predefined Status classes are available in the Status class.

Parameters:

msg – Message to display after the icon
icon – Character(s) to use as the icon. Icon can be any size. If no icon, seperator is not used.
icon_color – Color of the icon. Can be a termcolor color code or an RGB tuple
icon_attrs – Attributes of the icon. Can be a list of termcolor attributes
sep – Seperator between icon and message. Will only be used when message is provided.
msg_color – Color of the message. Can be a termcolor color code or an RGB tuple
msg_attrs – Attributes of the message. Can be a list of termcolor attributes
overwrite – If true, will overwrite the previous line with a new status.

Bases: BaseStatus

Parameters:

msg – Message to display after the icon
icon – Character(s) to use as the icon. Icon can be any size.
icon_color – Color of the icon. Can be a termcolor color code or an RGB tuple
icon_attrs – Attributes to apply to the icon. Can be a list of termcolor attributes
sep – Seperator between icon and message. Will only be used when message is provided.
msg_color – Color of the message. Can be a termcolor color code or an RGB tuple
msg_attrs – Attributes to apply to the message. Can be a list of termcolor attributes
overwrite – If true, will overwrite the previous line with a new status.

Status base class. Can be used to create custom status classes.

Predefined Status classes are available in the Status class.

Parameters:

msg – Message to display after the icon
icon – Character(s) to use as the icon. Icon can be any size. If no icon, seperator is not used.
icon_color – Color of the icon. Can be a termcolor color code or an RGB tuple
icon_attrs – Attributes of the icon. Can be a list of termcolor attributes
sep – Seperator between icon and message. Will only be used when message is provided.
msg_color – Color of the message. Can be a termcolor color code or an RGB tuple
msg_attrs – Attributes of the message. Can be a list of termcolor attributes
overwrite – If true, will overwrite the previous line with a new status.

Bases: BaseStatus

Parameters:

msg – Message to display after the icon
icon – Character(s) to use as the icon. Icon can be any size.
icon_color – Color of the icon. Can be a termcolor color code or an RGB tuple
icon_attrs – Attributes to apply to the icon. Can be a list of termcolor attributes
sep – Seperator between icon and message. Will only be used when message is provided.
msg_color – Color of the message. Can be a termcolor color code or an RGB tuple
msg_attrs – Attributes to apply to the message. Can be a list of termcolor attributes
overwrite – If true, will overwrite the previous line with a new status.

Status base class. Can be used to create custom status classes.

Predefined Status classes are available in the Status class.

Parameters:

msg – Message to display after the icon
icon – Character(s) to use as the icon. Icon can be any size. If no icon, seperator is not used.
icon_color – Color of the icon. Can be a termcolor color code or an RGB tuple
icon_attrs – Attributes of the icon. Can be a list of termcolor attributes
sep – Seperator between icon and message. Will only be used when message is provided.
msg_color – Color of the message. Can be a termcolor color code or an RGB tuple
msg_attrs – Attributes of the message. Can be a list of termcolor attributes
overwrite – If true, will overwrite the previous line with a new status.

Bases: BaseStatus

Parameters:

msg – Message to display after the icon
icon – Character(s) to use as the icon. Icon can be any size.
icon_color – Color of the icon. Can be a termcolor color code or an RGB tuple
icon_attrs – Attributes to apply to the icon. Can be a list of termcolor attributes
sep – Seperator between icon and message. Will only be used when message is provided.
msg_color – Color of the message. Can be a termcolor color code or an RGB tuple
msg_attrs – Attributes to apply to the message. Can be a list of termcolor attributes
overwrite – If true, will overwrite the previous line with a new status.

Status base class. Can be used to create custom status classes.

Predefined Status classes are available in the Status class.

Parameters:

msg – Message to display after the icon
icon – Character(s) to use as the icon. Icon can be any size. If no icon, seperator is not used.
icon_color – Color of the icon. Can be a termcolor color code or an RGB tuple
icon_attrs – Attributes of the icon. Can be a list of termcolor attributes
sep – Seperator between icon and message. Will only be used when message is provided.
msg_color – Color of the message. Can be a termcolor color code or an RGB tuple
msg_attrs – Attributes of the message. Can be a list of termcolor attributes
overwrite – If true, will overwrite the previous line with a new status.

class framed_text.status.StatusColors[source]

Bases: object

A collection of the default colors used by the Status classes. Pre-formatted

Available Icons

INFO: '?'
ACTION: '➤'
SUCCESS: '✔'
FAIL: '✗'
WARN: '⚠️'
HIDDEN: '➤'

ACTION: str = 'blue'

FAIL: str = 'red'

HIDDEN: tuple[int, int, int] = (125, 125, 125)

INFO: str = 'yellow'

SUCCESS: str = 'green'

WARN: tuple[int, int, int] = (239, 202, 19)

class framed_text.status.StatusIcons[source]

Bases: object

A collection of the default icons used by the Status classes. Pre-formatted

Available Icons

INFO: '?'
ACTION: '➤'
SUCCESS: '✔'
FAIL: '✗'
WARN: '⚠️'
HIDDEN: '➤'

ACTION: str = '➤'

FAIL: str = '✗'

HIDDEN: str = '➤'

INFO: str = '?'

SUCCESS: str = '✔'

WARN: str = '⚠️'

framed_text.utils module

class framed_text.utils.ANSIEscape[source]

Bases: object

ANSI Escape Codes used throughout framed-text

ALT_BUFFER_OFF: str = '\x1b[?1049l'

ALT_BUFFER_ON: str = '\x1b[?1049h'

ERASE_LINE: str = '\x1b[2K'

ERASE_SCREEN: str = '\x1b[2J'

HIDE_CURSOR: str = '\x1b[?25l'

RESTORE_POS: str = '\x1b8'

SAVE_POS: str = '\x1b7'

SHOW_CURSOR: str = '\x1b[?25h'

static move_down(lines: int = 1)[source]: ANSI Code to move a set number of lines down :param lines: number of lines. Must be greater than 1 :return: ANSI code

static move_to(line: int = 0, column: int = 0) → str[source]

ANSI Code to move to a specific line and column

Line and column must be positive :param line: Line to move to (row) :param column: Column to move to (char) :return: ANSI code

static move_to_col(column: int = 0) → str[source]

ANSI Code to move to a specific column on the same line

Line and column must be positive :param column: Column to move to (char) :return: ANSI code

static move_up(lines: int = 1) → str[source]: ANSI Code to move a set number of lines up :param lines: number of lines. Must be greater than 1 :return: ANSI code

static reset_scrollable_region() → str[source]: ANSI code to reset scrollable region :return: ANSI code

static set_scrollable_region(top: int, bottom: int) → str[source]

ANSI code to set a scrollable region.

Top and bottom must be positive :param top: Line number to be used as top region :param bottom: Line number to be used as bottom region :return: ANSI code

exception framed_text.utils.InvalidColorError(color: Any | None = None, message: str | None = None)[source]

Bases: Exception

__init__(color: Any | None = None, message: str | None = None)[source]

Exception raised for invalid colors

Parameters:

color – Invalid color
message – Exception message

Module contents

class framed_text.ANSIEscape[source]

Bases: object

ANSI Escape Codes used throughout framed-text

ALT_BUFFER_OFF: str = '\x1b[?1049l'

ALT_BUFFER_ON: str = '\x1b[?1049h'

ERASE_LINE: str = '\x1b[2K'

ERASE_SCREEN: str = '\x1b[2J'

HIDE_CURSOR: str = '\x1b[?25l'

RESTORE_POS: str = '\x1b8'

SAVE_POS: str = '\x1b7'

SHOW_CURSOR: str = '\x1b[?25h'

static move_down(lines: int = 1)[source]: ANSI Code to move a set number of lines down :param lines: number of lines. Must be greater than 1 :return: ANSI code

static move_to(line: int = 0, column: int = 0) → str[source]

ANSI Code to move to a specific line and column

Line and column must be positive :param line: Line to move to (row) :param column: Column to move to (char) :return: ANSI code

static move_to_col(column: int = 0) → str[source]

ANSI Code to move to a specific column on the same line

Line and column must be positive :param column: Column to move to (char) :return: ANSI code

static move_up(lines: int = 1) → str[source]: ANSI Code to move a set number of lines up :param lines: number of lines. Must be greater than 1 :return: ANSI code

static reset_scrollable_region() → str[source]: ANSI code to reset scrollable region :return: ANSI code

static set_scrollable_region(top: int, bottom: int) → str[source]

ANSI code to set a scrollable region.

Top and bottom must be positive :param top: Line number to be used as top region :param bottom: Line number to be used as bottom region :return: ANSI code

Bases: object

Status base class. Can be used to create custom status classes.

Predefined Status classes are available in the Status class.

Parameters:

msg – Message to display after the icon
icon – Character(s) to use as the icon. Icon can be any size. If no icon, seperator is not used.
icon_color – Color of the icon. Can be a termcolor color code or an RGB tuple
icon_attrs – Attributes of the icon. Can be a list of termcolor attributes
sep – Seperator between icon and message. Will only be used when message is provided.
msg_color – Color of the message. Can be a termcolor color code or an RGB tuple
msg_attrs – Attributes of the message. Can be a list of termcolor attributes
overwrite – If true, will overwrite the previous line with a new status.

cutoff_text(limit: int, mode: Literal['char', 'word', 'middle'] = 'char') → str[source]

Cutoffs text if it exceeds limit. Icon and seperator will always be shortened by character.

Modes

char: Cutoff char at end of text (The quick brown fox jumped ove…)
word: Cutoff word at end of text (The quick brown fox jumped…)
middle: Cutoff chars at middle of text (The quick brown…the lazy dog)

Parameters:

limit – Maximum length of text
mode – Mode to use for shortening. See above for info.

Returns:

Cutoff text

icon: str

icon_attrs: list[str] | None

icon_color: str | tuple[int, int, int] | None

message: str | String | Number | Boolean | Path | Date | Bytes | None

seperator: str

text: str

text_attrs: list[str] | None

text_color: str | tuple[int, int, int] | None

text_shorten: str

class framed_text.FramedHeader(title: str = '', frame_color: str | tuple[int, int, int] = '', title_color: str | tuple[int, int, int] = '', divider: str = '─', attrs: list[str] | None = None)[source]

Bases: object

__init__(title: str = '', frame_color: str | tuple[int, int, int] = '', title_color: str | tuple[int, int, int] = '', divider: str = '─', attrs: list[str] | None = None)[source]

Creates a string with a customizable divider. Can include a title. Matches the style of FramedText.

Attributes:

All termcolor attributes are supported: "bold", "dark", "italic", "underline", "reverse", "concealed", "strike"

Parameters:

title – Title to display in the header
frame_color – Color of the frame. Valid colors based off of termcolor’s color options: string color code or RGB tuple
title_color – Color of the title. Valid colors based off of termcolor’s color options: string color code or RGB tuple
divider – Divider to use. Will be repeated to fill the terminal width
attrs – Attributes to apply to the title. See list above for valid attributes

Bases: object

Creates a string with a customizable frame around it. Frame is based off of prompt_toolkit’s show_frame option, but with more customization and designed for print statements.

Cutoff Modes:

char: Cutoff char at end of text (The quick brown fox jumped ove…)
word: Cutoff word at end of text (The quick brown fox jumped…)
middle: Cutoff chars at middle of text (The quick brown…the lazy dog)

Frame Sizes: - full: Frame will be the size of the terminal - dynamic: Frame will be the size of the text based on longest line.

Attributes:

All termcolor attributes are supported: "bold", "dark", "italic", "underline", "reverse", "concealed", "strike"

NOTE: allow_ansi only applies to strings

Parameters:

text – Text to be framed. Can be a regular string or a LabeledData object
title – Title of the frame
mode – Mode for cutoff. “char” for character cutoff, “word” for word cutoff, “middle” for middle cutoff
frame_color – Color of the frame. Valid colors based off of termcolor’s color options: string color code or RGB tuple
title_color – Color of the title. Valid colors based off of termcolor’s color options: string color code or RGB tuple
cutoff – If true, cut off text if it exceeds terminal width. Default is True (Recommended)
allow_ansi – If True, Allows ANSI on long lines (Highly experimental. Use at your own risk). If False, removes all ANSI from non-LabeledData objects on long lines.
center_text – If True, centers the text inside frame. Centers whole frame if frame_size="dynamic"
frame_size – Size of the frame. “full” for terminal size, “dynamic” for text size
attrs – Attributes to apply to the title. See list above for valid attributes

exception framed_text.InvalidColorError(color: Any | None = None, message: str | None = None)[source]

Bases: Exception

__init__(color: Any | None = None, message: str | None = None)[source]

Exception raised for invalid colors

Parameters:

color – Invalid color
message – Exception message

class framed_text.LabeledData[source]

Bases: object

Class for creating a string with a label and different types of data. Each item can be configured to include colored text.

class Boolean(label: str, value: bool, suffix: str = '', t_color: str | tuple[int, int, int] | None = 'green', f_color: str | tuple[int, int, int] | None = 'red', label_color: str | tuple[int, int, int] | None = None, suffix_color: str | tuple[int, int, int] | None = None, t_text: str = 'True', f_text: str = 'False', quotes: bool = False, colon_match: bool = True, no_colon: bool = False, val_attrs: list[str] | None = None, label_attrs: list[str] | None = None, suffix_attrs: list[str] | None = None)[source]

Bases: object

__init__(label: str, value: bool, suffix: str = '', t_color: str | tuple[int, int, int] | None = 'green', f_color: str | tuple[int, int, int] | None = 'red', label_color: str | tuple[int, int, int] | None = None, suffix_color: str | tuple[int, int, int] | None = None, t_text: str = 'True', f_text: str = 'False', quotes: bool = False, colon_match: bool = True, no_colon: bool = False, val_attrs: list[str] | None = None, label_attrs: list[str] | None = None, suffix_attrs: list[str] | None = None)[source]

Creates a string with a label and boolean value

Parameters:

label – Label for boolean value
value – Boolean value
suffix – Optional text to appear after the value
t_color – Color of true value.
f_color – Color of false value.
label_color – Color of label.
suffix_color – Color of suffix.
t_text – Text to display for true value
f_text – Text to display for false value
quotes – If true, wrap text in single quotes (‘)
colon_match – If true, the colon will match the style of the label.
no_colon – If true, the colon will be removed. Overrides colon_match
val_attrs – Attributes to apply to the value.
label_attrs – Attributes to apply to the label.
suffix_attrs – Attributes to apply to the suffix.

cutoff_text(limit: int) → str[source]

Cuts off text if it exceeds limit. Will first try to shorten bool value. If there isn’t enough space for just an ellipsis, it will try to shorten the label, so that the output will be 50/50 (label: value).

Parameters:: limit – Maximum length of text
Returns:: Shortened text

class Bytes(label: str, value: int, suffix: str = '', suffix_color: str | tuple[int, int, int] | None = None, val_color: str | tuple[int, int, int] | None = 'yellow', label_color: str | tuple[int, int, int] | None = None, unit_color: str | tuple[int, int, int] | None = None, quotes: bool = False, colon_match: bool = True, unit_match: bool = True, no_colon: bool = False, show_unit: bool = True, unit_type: Literal['iec', 'si'] = 'iec', val_attrs: list[str] | None = None, label_attrs: list[str] | None = None, suffix_attrs: list[str] | None = None, unit_attrs: list[str] | None = None)[source]

Bases: object

__init__(label: str, value: int, suffix: str = '', suffix_color: str | tuple[int, int, int] | None = None, val_color: str | tuple[int, int, int] | None = 'yellow', label_color: str | tuple[int, int, int] | None = None, unit_color: str | tuple[int, int, int] | None = None, quotes: bool = False, colon_match: bool = True, unit_match: bool = True, no_colon: bool = False, show_unit: bool = True, unit_type: Literal['iec', 'si'] = 'iec', val_attrs: list[str] | None = None, label_attrs: list[str] | None = None, suffix_attrs: list[str] | None = None, unit_attrs: list[str] | None = None)[source]

Creates a string with a label and bytes value

Parameters:

label – Label for string value
value – Integer value. Value MUST be in bytes
suffix – Optional text to appear after the value
val_color – Color of string value.
label_color – Color of label.
unit_color – Color of unit. Overrides unit_match.
quotes – If true, wrap text in single quotes (‘)
colon_match – If true, the colon will match the style of the label.
unit_match – If true, the unit will match the style of the value.
no_colon – If true, the colon will be removed. Overrides colon_match
show_unit – If true, the unit will be shown.
unit_type – Unit type: IEC is base 2, SI is base 10
val_attrs – Attributes to apply to the value.
label_attrs – Attributes to apply to the label.
unit_attrs – Attributes to apply to the unit. Overrides unit_match.

cutoff_text(limit: int) → str[source]

Cuts off text if it exceeds limit. Will NOT shorten the value, only suffix (if there is one). If there isn’t enough space for just an ellipsis, it will try to shorten the label, so that the output will be 50/50 (label: value).

Parameters:: limit – Maximum length of text
Returns:: Shortened text

class Date(label: str, value: str | datetime = '', suffix: str = '', strftime: str = '%Y-%m-%d %H:%M:%S', suffix_color: str | tuple[int, int, int] | None = None, val_color: str | tuple[int, int, int] | None = 'blue', label_color: str | tuple[int, int, int] | None = None, quotes: bool = True, colon_match: bool = True, no_colon: bool = False, val_attrs: list[str] | None = None, label_attrs: list[str] | None = None, suffix_attrs: list[str] | None = None)[source]

Bases: object

__init__(label: str, value: str | datetime = '', suffix: str = '', strftime: str = '%Y-%m-%d %H:%M:%S', suffix_color: str | tuple[int, int, int] | None = None, val_color: str | tuple[int, int, int] | None = 'blue', label_color: str | tuple[int, int, int] | None = None, quotes: bool = True, colon_match: bool = True, no_colon: bool = False, val_attrs: list[str] | None = None, label_attrs: list[str] | None = None, suffix_attrs: list[str] | None = None)[source]

Creates a string with a label and a date value

If no value is passed, will print current time using strftime parameter :param label: Label for string value :param value: Value, either as a datetime object or string :param suffix: Optional text to appear after the value :param strftime: Formatter for datetime value :param val_color: Color of string value. :param label_color: Color of label. :param quotes: If true, wrap text in single quotes (‘) :param colon_match: If true, the colon will match the style of the label. :param no_colon: If true, the colon will be removed. Overrides colon_match :param val_attrs: Attributes to apply to the value. :param label_attrs: Attributes to apply to the label.

cutoff_text(limit: int) → str[source]

Cuts off text if it exceeds limit. Will first try to shorten string. If there isn’t enough space for just an ellipsis, it will try to shorten the label, so that the output will be 50/50 (label: value).

Parameters:: limit – Maximum length of text
Returns:: Shortened text

Bases: object

Creates a string with a label and number value

Parameters:

label – Label for number value
value – Number value
suffix – Optional text to appear after the value
round_to – Number of decimal places to round to. Leave blank to not round.
leading_zeros – Number of leading zeros to add to the number. Leave blank to not add leading zeros.
int_no_round – If true, displays number as integer without rounding. Overrides round_to
val_color – Color of number value.
label_color – Color of label.
suffix_color – Color of suffix.
quotes – If true, wrap text in single quotes (‘)
colon_match – If true, the colon will match the style of the label.
no_colon – If true, the colon will be removed. Overrides colon_match
val_attrs – Attributes to apply to the value.
label_attrs – Attributes to apply to the label.

cutoff_text(limit: int) → str[source]

Cuts off text if it exceeds limit. Will NOT shorten the number, only the suffix (if there is one). If there isn’t enough space for just an ellipsis, it will try to shorten the label, so that the output will be 50/50 (label: value).

Parameters:: limit – Maximum length of text
Returns:: Shortened text

Bases: object

Creates a string with a label and path to a file or directory

Parameters:

label – Label for path
value – Path to file or directory
suffix – Optional text to appear after the value
quotes – If true, wrap path in single quotes (‘)
val_color – Color of path value.
label_color – Color of label.
suffix_color – Color of suffix.
colon_match – If true, the colon will match the style of the label.
no_colon – If true, the colon will be removed. Overrides colon_match
val_attrs – Attributes to apply to the value.
label_attrs – Attributes to apply to the label.
suffix_attrs – Attributes to apply to the suffix.

cutoff_text(limit: int, mode: Literal['char', 'word', 'middle'] = 'char') → str[source]

Shortens path to limit.

Modes: - char: Cutoff char at end of string (/path/to/a/f…) - word: Cutoff path at end, preserve the deepest directory/file (/path/to/…/file.txt) - middle: Cutoff chars at middle of string (/long/path/t…/an/file.txt)

Parameters:

limit – Character limit for full labeled path string
mode – How to cut off path.

Returns:

LabeledData.Path string with shortened path if it exceeds limit, else returns original string

class String(label: str, value: str, suffix: str = '', suffix_color: str | tuple[int, int, int] | None = None, val_color: str | tuple[int, int, int] | None = 'cyan', label_color: str | tuple[int, int, int] | None = None, quotes: bool = True, colon_match: bool = True, no_colon: bool = False, val_attrs: list[str] | None = None, label_attrs: list[str] | None = None, suffix_attrs: list[str] | None = None)[source]

Bases: object

__init__(label: str, value: str, suffix: str = '', suffix_color: str | tuple[int, int, int] | None = None, val_color: str | tuple[int, int, int] | None = 'cyan', label_color: str | tuple[int, int, int] | None = None, quotes: bool = True, colon_match: bool = True, no_colon: bool = False, val_attrs: list[str] | None = None, label_attrs: list[str] | None = None, suffix_attrs: list[str] | None = None)[source]

Creates a string with a label and string value

Parameters:

label – Label for string value
value – String value
suffix – Optional text to appear after the value
val_color – Color of string value.
label_color – Color of label.
quotes – If true, wrap text in single quotes (‘)
colon_match – If true, the colon will match the style of the label.
no_colon – If true, the colon will be removed. Overrides colon_match
val_attrs – Attributes to apply to the value.
label_attrs – Attributes to apply to the label.

cutoff_text(limit: int, mode: Literal['char', 'word', 'middle'] = 'char') → str[source]

Cuts off text if it exceeds limit. Will first try to shorten string. If there isn’t enough space for just an ellipsis, it will try to shorten the label, so that the output will be 50/50 (label: value).

Modes: - char: Cutoff char at end of string (The quick brown fox jumped ove…) - word: Cutoff word at end of string (The quick brown fox jumped…) - middle: Cutoff words at middle of string (The quick brown…the lazy dog)

Parameters:

limit – Maximum length of text
mode – How to cut off value text

Returns:

Shortened text

class framed_text.ProgressBar(value: int, total: int, label: str = '', show_frame: bool = False, show_percent: bool = True, show_values: bool = False, progress_icon: str = '#', empty_icon: str = '.', brackets: tuple[str, str] = ('[', ']'), value_color: str | tuple[int, int, int] | None = None, label_color: str | tuple[int, int, int] | None = None, percent_color: str | tuple[int, int, int] | None = None, progress_color: str | tuple[int, int, int] | None = None, brackets_color: str | tuple[int, int, int] | None = None, frame_color: str | tuple[int, int, int] | None = None, safe_mode: bool = False, skip_init: bool = False)[source]

Bases: object

__init__(value: int, total: int, label: str = '', show_frame: bool = False, show_percent: bool = True, show_values: bool = False, progress_icon: str = '#', empty_icon: str = '.', brackets: tuple[str, str] = ('[', ']'), value_color: str | tuple[int, int, int] | None = None, label_color: str | tuple[int, int, int] | None = None, percent_color: str | tuple[int, int, int] | None = None, progress_color: str | tuple[int, int, int] | None = None, brackets_color: str | tuple[int, int, int] | None = None, frame_color: str | tuple[int, int, int] | None = None, safe_mode: bool = False, skip_init: bool = False)[source]

Display a progress bar that shows the progress from a value to a total.

The progress bar will snap to the bottom of the terminal.

Parameters:

value – Current value
total – Total value
label – Optional label for the Progress Bar
show_frame – If true, will show a frame around the progress bar, similar to FramedText
show_percent – If true, will show percentage of progress. Will replace values display unless show_values is true
show_values – If true, will show current value and total value. If false and show_percent is false, will not display any values
progress_icon – Icon used for the progress display
empty_icon – Icon used for the empty space in the progress display
brackets – Brackets to surround the progress display. First value is the left bracket, second value is the right bracket
value_color – Color of the label
label_color – Color of the label
percent_color – Color of the percentage
progress_color – Color of the progress display
brackets_color – Color of the brackets
frame_color – Color of the frame
safe_mode – If true, will clear the terminal and move cursor to top to ensure room for progress bar and any other data.
skip_init – If true, will only initialize when display or update_progress is called

display()[source]: Display the progress bar

static force_reset(show_frame: bool = False, label: bool = False)[source]

Force resets the terminal. This should only be used in the except block of a try-except block.

Make sure to pass the same values to this function that were passed to the ProgressBar constructor, otherwise the reset may not work as expected.

NOTE: This method does not change ProgressBar._term_is_init. If you plan to re-use the progress bar after a force reset, you will need to call ProgressBar._init_term manually.

This function behaves like ProgressBar.reset

Parameters:

show_frame – Whether show_frame was enabled for the progress bar.
label – Whether label was enabled for the progress bar.

reset()[source]

update_progress(value: int | None = None, total: int | None = None)[source]

Bases: object

Shorten text to a specified limit. Supports LabeledData, Status and regular strings.

Modes

char: Cutoff char at end of text (The quick brown fox jumped ove…)
word: Cutoff word at end of text (The quick brown fox jumped…)
middle: Cutoff chars at middle of text (The quick brown…the lazy dog)

Parameters:

text – Text to shorten
limit – Limit. Text will be shortened to this length. If no limit is passed, will default to the width of the terminal.
allow_ansi – If true, allow ANSI codes in the text. This parameter only applies to regular strings.
mode – Mode to use to shorten text. See above for more info.

Bases: object

BUILTIN_ICONS: dict[str, list[str]] = {'cube': ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'], 'default': ['/', '-', '\\', '|'], 'dots': [' ', '. ', '.. ', '...'], 'dots2': [' ', '. ', '.. ', '...', ' ..', ' .']}

Draws a spinner on a screen

Position

"start": The spinner will be placed at the start of the line.
"end": The spinner will be placed at the end of the line.

Parameters:

text – Text to display next to the spinner. Omit for no text.
icons_id – ID string of one of the built-in icon sets from Spinner.BUILTIN_ICONS
done_icon – Icon to use for when the spinner is complete
custom_icons – A list of strings to use as the spinner icon. Overrides icons_id
interval – The delay between spinner icon updates.
position – Where the spinner should be placed on a line.
indent – How many spaces the line should be indented.
spinner_color – Color of the spinner icon while active.
done_color – Color for the spinner icon when stopped.

start(text: str = '')[source]

Start the spinner

Parameters:: text – Text to display next to the spinner. Omit for no text.

stop(done_icon: str | None = None, done_color: str | tuple[int, int, int] | None = None)[source]

Stop the spinner

Optionally, allow custom done icon and color for the current spinner. :param done_icon: Icon to use for when the spinner is complete :param done_color: Color for the done icon

Update values for the spinner.

Some values can only be updated when the spinner is not running.

Position

"start": The spinner will be placed at the start of the line.
"end": The spinner will be placed at the end of the line.

Parameters:

text – Text to display next to the spinner. Omit for no text.
icons_id – ID string of one of the built-in icon sets from Spinner.BUILTIN_ICONS
done_icon – Icon to use for when the spinner is complete
custom_icons – A list of strings to use as the spinner icon. Overrides icons_id
interval – The delay between spinner icon updates.
position – Where the spinner should be placed on a line.
indent – How many spaces the line should be indented.
spinner_color – Color of the spinner icon while active.
done_color – Color for the spinner icon when stopped.

class framed_text.Status[source]

Bases: object

Predefined Status classes. Can be used with LabeledData and regular strings. Each Status optionally takes a message and text color which creates a string in the format: <icon> <message>

Custom Status classes can be created from the BaseStatus class.

Bases: BaseStatus

Parameters:

msg – Message to display after the icon
icon – Character(s) to use as the icon. Icon can be any size.
icon_color – Color of the icon. Can be a termcolor color code or an RGB tuple
icon_attrs – Attributes to apply to the icon. Can be a list of termcolor attributes
sep – Seperator between icon and message. Will only be used when message is provided.
msg_color – Color of the message. Can be a termcolor color code or an RGB tuple
msg_attrs – Attributes to apply to the message. Can be a list of termcolor attributes
overwrite – If true, will overwrite the previous line with a new status.

Status base class. Can be used to create custom status classes.

Predefined Status classes are available in the Status class.

Parameters:

msg – Message to display after the icon
icon – Character(s) to use as the icon. Icon can be any size. If no icon, seperator is not used.
icon_color – Color of the icon. Can be a termcolor color code or an RGB tuple
icon_attrs – Attributes of the icon. Can be a list of termcolor attributes
sep – Seperator between icon and message. Will only be used when message is provided.
msg_color – Color of the message. Can be a termcolor color code or an RGB tuple
msg_attrs – Attributes of the message. Can be a list of termcolor attributes
overwrite – If true, will overwrite the previous line with a new status.

Bases: BaseStatus

Parameters:

msg – Message to display after the icon
icon – Character(s) to use as the icon. Icon can be any size.
icon_color – Color of the icon. Can be a termcolor color code or an RGB tuple
icon_attrs – Attributes to apply to the icon. Can be a list of termcolor attributes
sep – Seperator between icon and message. Will only be used when message is provided.
msg_color – Color of the message. Can be a termcolor color code or an RGB tuple
msg_attrs – Attributes to apply to the message. Can be a list of termcolor attributes
overwrite – If true, will overwrite the previous line with a new status.

Status base class. Can be used to create custom status classes.

Predefined Status classes are available in the Status class.

Parameters:

msg – Message to display after the icon
icon – Character(s) to use as the icon. Icon can be any size. If no icon, seperator is not used.
icon_color – Color of the icon. Can be a termcolor color code or an RGB tuple
icon_attrs – Attributes of the icon. Can be a list of termcolor attributes
sep – Seperator between icon and message. Will only be used when message is provided.
msg_color – Color of the message. Can be a termcolor color code or an RGB tuple
msg_attrs – Attributes of the message. Can be a list of termcolor attributes
overwrite – If true, will overwrite the previous line with a new status.

Bases: BaseStatus

A special status which shows the text in a dark color. An alternative to Status.Action

Parameters:

msg – Message to display after the icon
icon – Character(s) to use as the icon. Icon can be any size.
icon_color – Color of the icon. Can be a termcolor color code or an RGB tuple
icon_attrs – Attributes to apply to the icon. Can be a list of termcolor attributes
sep – Seperator between icon and message. Will only be used when message is provided.
msg_color – Color of the message. Can be a termcolor color code or an RGB tuple
msg_attrs – Attributes to apply to the message. Can be a list of termcolor attributes
overwrite – If true, will overwrite the previous line with a new status.

Status base class. Can be used to create custom status classes.

Predefined Status classes are available in the Status class.

Parameters:

msg – Message to display after the icon
icon – Character(s) to use as the icon. Icon can be any size. If no icon, seperator is not used.
icon_color – Color of the icon. Can be a termcolor color code or an RGB tuple
icon_attrs – Attributes of the icon. Can be a list of termcolor attributes
sep – Seperator between icon and message. Will only be used when message is provided.
msg_color – Color of the message. Can be a termcolor color code or an RGB tuple
msg_attrs – Attributes of the message. Can be a list of termcolor attributes
overwrite – If true, will overwrite the previous line with a new status.

Bases: BaseStatus

Parameters:

msg – Message to display after the icon
icon – Character(s) to use as the icon. Icon can be any size.
icon_color – Color of the icon. Can be a termcolor color code or an RGB tuple
icon_attrs – Attributes to apply to the icon. Can be a list of termcolor attributes
sep – Seperator between icon and message. Will only be used when message is provided.
msg_color – Color of the message. Can be a termcolor color code or an RGB tuple
msg_attrs – Attributes to apply to the message. Can be a list of termcolor attributes
overwrite – If true, will overwrite the previous line with a new status.

Status base class. Can be used to create custom status classes.

Predefined Status classes are available in the Status class.

Parameters:

msg – Message to display after the icon
icon – Character(s) to use as the icon. Icon can be any size. If no icon, seperator is not used.
icon_color – Color of the icon. Can be a termcolor color code or an RGB tuple
icon_attrs – Attributes of the icon. Can be a list of termcolor attributes
sep – Seperator between icon and message. Will only be used when message is provided.
msg_color – Color of the message. Can be a termcolor color code or an RGB tuple
msg_attrs – Attributes of the message. Can be a list of termcolor attributes
overwrite – If true, will overwrite the previous line with a new status.

Bases: BaseStatus

Parameters:

msg – Message to display after the icon
icon – Character(s) to use as the icon. Icon can be any size.
icon_color – Color of the icon. Can be a termcolor color code or an RGB tuple
icon_attrs – Attributes to apply to the icon. Can be a list of termcolor attributes
sep – Seperator between icon and message. Will only be used when message is provided.
msg_color – Color of the message. Can be a termcolor color code or an RGB tuple
msg_attrs – Attributes to apply to the message. Can be a list of termcolor attributes
overwrite – If true, will overwrite the previous line with a new status.

Status base class. Can be used to create custom status classes.

Predefined Status classes are available in the Status class.

Parameters:

msg – Message to display after the icon
icon – Character(s) to use as the icon. Icon can be any size. If no icon, seperator is not used.
icon_color – Color of the icon. Can be a termcolor color code or an RGB tuple
icon_attrs – Attributes of the icon. Can be a list of termcolor attributes
sep – Seperator between icon and message. Will only be used when message is provided.
msg_color – Color of the message. Can be a termcolor color code or an RGB tuple
msg_attrs – Attributes of the message. Can be a list of termcolor attributes
overwrite – If true, will overwrite the previous line with a new status.

Bases: BaseStatus

Parameters:

msg – Message to display after the icon
icon – Character(s) to use as the icon. Icon can be any size.
icon_color – Color of the icon. Can be a termcolor color code or an RGB tuple
icon_attrs – Attributes to apply to the icon. Can be a list of termcolor attributes
sep – Seperator between icon and message. Will only be used when message is provided.
msg_color – Color of the message. Can be a termcolor color code or an RGB tuple
msg_attrs – Attributes to apply to the message. Can be a list of termcolor attributes
overwrite – If true, will overwrite the previous line with a new status.

Status base class. Can be used to create custom status classes.

Predefined Status classes are available in the Status class.

Parameters:

msg – Message to display after the icon
icon – Character(s) to use as the icon. Icon can be any size. If no icon, seperator is not used.
icon_color – Color of the icon. Can be a termcolor color code or an RGB tuple
icon_attrs – Attributes of the icon. Can be a list of termcolor attributes
sep – Seperator between icon and message. Will only be used when message is provided.
msg_color – Color of the message. Can be a termcolor color code or an RGB tuple
msg_attrs – Attributes of the message. Can be a list of termcolor attributes
overwrite – If true, will overwrite the previous line with a new status.

class framed_text.StatusColors[source]

Bases: object

A collection of the default colors used by the Status classes. Pre-formatted

Available Icons

INFO: '?'
ACTION: '➤'
SUCCESS: '✔'
FAIL: '✗'
WARN: '⚠️'
HIDDEN: '➤'

ACTION: str = 'blue'

FAIL: str = 'red'

HIDDEN: tuple[int, int, int] = (125, 125, 125)

INFO: str = 'yellow'

SUCCESS: str = 'green'

WARN: tuple[int, int, int] = (239, 202, 19)

class framed_text.StatusIcons[source]

Bases: object

A collection of the default icons used by the Status classes. Pre-formatted

Available Icons

INFO: '?'
ACTION: '➤'
SUCCESS: '✔'
FAIL: '✗'
WARN: '⚠️'
HIDDEN: '➤'

ACTION: str = '➤'

FAIL: str = '✗'

HIDDEN: str = '➤'

INFO: str = '?'

SUCCESS: str = '✔'

WARN: str = '⚠️'