termtools.terminal module

This module exposes classes to control displaying text and progress bars at any place of the screen.

The two main classes are TerminalController and ProgressBarController

class termtools.terminal.ProgressBarController(barNames=None, barLength=50, align_bars=True)[source]

Bases: object

A set of progress bars.

A set of progress bars with custom pre and post text. It is mostly useful when you have several running threads or suprocesses and each needs its own bar. It allows prefixes and postfixes that can be changed using the following tags: <name> bar name <remaining> remaining time to completion estimate <activity> An indicator that the process represented by the bar is active

activate(name=None)[source]

Indicate that the given bar is active. If name is None, all bars are indicated to be active by progressing

Parameters:name (str) – bar name. If None is given then all bars are set to be active
Returns:self
activityChars = ['. ', ' . ', ' . ', ' .', ' . ', ' . ', '. ']
add_bar(name, *, i=0, n=0, start_timing=True)[source]

Adds a bar

Can control the name, starting progress (i) and total progress

Parameters:name (str) – name of bar
Kwargs:

i (int): current progress n (int): total progress start_timing (bool or None): Starts a timer for this bar, otherwise it uses the begTime member which

is common to all bars
Returns:self

Remarks:

barNames = None
begTime = None
completed_background = 'black'
completed_color = 'green'
current = None
get_remaining_time(name)[source]

Gets the time remaining till the end of execution (only an estimate)

Parameters:name – bar name
Returns:remaining time (ETA)
Return type:int
last_i = None
last_n = None
last_name_updated = None
over_complete_background = 'black'
over_complete_color = 'red'
remove_bar(name)[source]

Removes a bar given its name

Parameters:name (str) – bar name
Returns:self
running_background = 'black'
running_color = 'yellow'
set_progress(name, i, n=None)[source]

Sets progress for a specific bar, optionally setting its limit as well

Parameters:
  • name (str) – bar name
  • i (int) – current progress
  • n (int or None) – Limit (optional)
Returns:

self

show(name=None, prefix='<name>', suffix='<remaining>', bar_length=-1, from_line_beginning=True)[source]

Shows a specific bar just in the current place on the screen. We should have a new line before it

Args:

name (str or None): name of the bar prefix (str): prefix to write before the bar (see the class doc string for possible tag values) suffix (str): postfix (see prefix) bar_length (int): Bar length, if less than zero then the current length set during creation of the bar or

latest setting of its progess will be used.

from_line_beginning (bool): If true, a ‘

‘ and flushing will be outputed to set the bar to the beginning
of the line
Returns:
self
show_all(barname=None, i=None, n=None, clean_screen=True, prefix='<name><activity>', suffix='<remaining>', bar_length=-1, skip_rows=0)[source]

Shows a specific bar or all bars, possibly cleaning the screen

Parameters:
  • barname (str or None) – name of the bar
  • i (int or None) – optional progress value
  • n (int or None) – optional maximum value for the bar
  • clean_screen (bool) – Whether or not to clean the screen before drawing. Default is true
  • prefix (str) – prefix to write before the bar (see the class doc string for possible tag values)
  • suffix (str) – postfix (see prefix)
  • bar_length (int) – Bar length, if less than zero then the current length set during creation of the bar or latest setting of its progess will be used.
  • skip_rows (int) – the number of lines to skip between bars
  • from_line_beginning (bool) – If true, a r and flushing will be outputed to set the bar to the beginning of the line
Returns:

self

Remarks:

show_in_position(name=None, prefix='<name><activity>', suffix='<remaining>', bar_length=-1)[source]

Shows the named bar in its appropriate position without touching anything else in the screen

Parameters:
  • name (str) – bar name
  • clean_screen (bool) – Whether or not to clean the screen before drawing. Default is true
  • prefix (str) – prefix to write before the bar (see the class doc string for possible tag values)
  • suffix (str) – postfix (see prefix)
  • bar_length (int) – Bar length, if less than zero then the current length set during creation of the bar or latest setting of its progress will be used.
Returns:

self

start_timing(forNames=None)[source]

Starts timing for ETA calculation for the given bar names

Parameters:forNames (str or None) – The list of bar names. If None (Default), the beginning time of all bars is set to now
Returns:self
terminal()[source]

Gets the built-in TerminalController object

Return type:TerminalController
Returns:TerminalController
under_complete_background = 'black'
under_complete_color = 'red'
update(name=None, i=None, n=None, prefix='<name><activity>', suffix='<remaining>', bar_length=-1)[source]

Updates the progress value of a given bar and shows all the bars in their relative positions

Parameters:
  • name (str) – bar name
  • i (int or None) – optional progress value
  • n (int or None) – optional maximum value for the bar
  • clean_screen (bool) – Whether or not to clean the screen before drawing. Default is true
  • prefix (str) – prefix to write before the bar (see the class doc string for possible tag values)
  • suffix (str) – postfix (see prefix)
  • bar_length (int) – Bar length, if less than zero then the current length set during creation of the bar or latest setting of its progess will be used.
Returns:

self

class termtools.terminal.TerminalController[source]

Bases: object

A class for controlling where to print on a screen and the attributes of text to be printed.

attrib(attrib='keep')[source]
sets the text attributes
Parameters:attrib – one of [‘bright’,’dim’,’underscore’,’blink’,’reverse’,’hidden’]
Return type:TerminalController
background(background='keep')[source]
sets the text background color
Parameters:background – one of [‘black’,’red’,’green’,’yellow’,’blue’,’magenta’,’cyan’,’white’]
Return type:TerminalController
bookmark()[source]
saves current cursor position
Return type:TerminalController
clear()[source]
clears the screen
Return type:TerminalController
color(color='keep')[source]
sets the text foreground color
Parameters:color – one of [‘black’,’red’,’green’,’yellow’,’blue’,’magenta’,’cyan’,’white’]
Return type:TerminalController
down(n=1)[source]
goes down the specified number of rows
Parameters:n – The number of rows to go down (a negative number goes up)
Return type:TerminalController
eraseDown()[source]
erases all text from currnt line to the end of the screen
Return type:TerminalController
eraseLine()[source]
erases all text from currnt line
Return type:TerminalController
eraseToBOL()[source]
erases all text from currnt location to the beginning of the line
Return type:TerminalController
eraseToEOL()[source]
erases all text from currnt location to the end of the line
Return type:TerminalController
eraseUp()[source]
erases all text from currnt line to the beginning of the screen
Return type:TerminalController
goto(x=0, y=0)[source]
goes to the specified x-y coordingates on the screen
Parameters:
  • x – x coordinate from the left to right
  • y – y coordinate from the top to bottom
Return type:

TerminalController

goto_bookmark()[source]
goes to current bookmarked position (must use bookmark() before it)
Return type:TerminalController
home(erase_screen=False)[source]
gets the cursor to the top of the screen
Return type:TerminalController
left(n=1)[source]
goes left the specified number of rows
Parameters:n – The number of rows to go up (a negative number goes right)
Return type:TerminalController
print(*args, **kwargs)[source]
printat(txt, x=0, y=0)[source]
goes to the specified x-y coordingates on the screen and prints the text.
Parameters:
  • x – x coordinate from the left to right
  • y – y coordinate from the top to bottom
Return type:

TerminalController

reset_attributes()[source]
resets all text attributes to their defaults
Return type:TerminalController
right(n=1)[source]
goes right the specified number of rows
Parameters:n – The number of rows to go up (a negative number goes left)
Return type:TerminalController
set_attribute(attrib='keep')[source]
sets the text attributes
Parameters:attrib – one of [‘bright’,’dim’,’underscore’,’blink’,’reverse’,’hidden’]
Return type:TerminalController
set_attributes(color='keep', background='keep', attrib='keep')[source]
sets the text attributes to be used by new prints. a value of “keep” keeps the current set
Parameters:
  • color – one of [‘black’,’red’,’green’,’yellow’,’blue’,’magenta’,’cyan’,’white’]
  • background – one of [‘black’,’red’,’green’,’yellow’,’blue’,’magenta’,’cyan’,’white’]
  • attrib – one of [‘bright’,’dim’,’underscore’,’blink’,’reverse’,’hidden’]
Return type:

TerminalController

set_background(background='keep')[source]
sets the text background color
Parameters:background – one of [‘black’,’red’,’green’,’yellow’,’blue’,’magenta’,’cyan’,’white’]
Return type:TerminalController
set_foreground(color='keep')[source]

sets the text foreground color

Parameters:color – one of [‘black’,’red’,’green’,’yellow’,’blue’,’magenta’,’cyan’,’white’]
Return type:TerminalController
up(n=1)[source]
goes up the specified number of rows
Parameters:n – The number of rows to go up (a negative number goes down)
Return type:TerminalController
termtools.terminal.humanize_time(secs, align=False, always_show_all_units=False)[source]

Prints time that is given as seconds in human readable form. Useful only for times >=1sec.

Parameters:
  • float (secs) – number of seconds
  • bool, optional (always_show_all_units) – whether to align outputs so that they all take the same size (not implemented)
  • bool, optional – Whether to always show days, hours, and minutes even when they are zeros. default False
Returns:

str formated string with the humanized form

termtools.terminal.print_progress(iteration, total, prefix='', suffix='', decimals=2, barLength=50, limit_range=True)[source]

Call in a loop to create terminal progress bar

Parameters:
  • int (barLength) – current iteration
  • int – total iterations
  • str (suffix) – prefix string
  • str – suffix string
  • int – positive number of decimals in percent complete
  • int – character length of bar