termtools package¶
Submodules¶
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: str = 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: str, *, i: float = 0, n: float = 0, start_timing: bool = 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: str, i: int, n: int = 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.
- Args:
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 ‘
- ‘ 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
() → termtools.terminal.TerminalController[source]¶ Gets the built-in TerminalController object
Returns: TerminalController
-
under_complete_background
= 'black'¶
-
under_complete_color
= 'red'¶
-
update
(name: str = None, i: typing.Union[int, NoneType] = None, n: typing.Union[int, NoneType] = None, prefix: str = '<name><activity>', suffix: str = '<remaining>', bar_length: int = -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:
-
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
-
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:
-
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:
-
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