ttystatus is a Python library for showing progress reporting and status updates on terminals, for (Unix) command line programs. Output is automatically adapted to the width of the terminal: truncated if it does not fit, and re-sized if the terminal size changes.
Output is provided via widgets. Each widgets formats some data into a suitable form for output. It gets the data either via its initializer, or from key/value pairs maintained by the master object. The values are set by the user. Every time a value is updated, widgets get updated (although the terminal is only updated every so often to give user time to actually read the output).
Here’s an example program that searches for symlinks in a directory tree:
import os
import sys
import ttystatus
ts = ttystatus.TerminalStatus(period=0.1)
ts.add(ttystatus.ElapsedTime())
ts.add(ttystatus.Literal(' Looking for files: '))
ts.add(ttystatus.Counter('pathname'))
ts.add(ttystatus.Literal(' found, currently in '))
ts.add(ttystatus.Pathname('dirname'))
pathnames = []
for dirname, subdirs, basenames in os.walk(sys.argv[1]):
ts['dirname'] = dirname
for basename in basenames:
pathname = os.path.join(dirname, basename)
ts['pathname'] = pathname
pathnames.append(pathname)
ts.clear()
ts.add(ttystatus.ElapsedTime())
ts.add(ttystatus.Literal(' Finding symlinks: '))
ts.add(ttystatus.Counter('symlink'))
ts.add(ttystatus.Literal(' found; now at '))
ts.add(ttystatus.Index('pathname', 'pathnames'))
ts.add(ttystatus.Literal(' ('))
ts.add(ttystatus.PercentDone('done', 'total', decimals=2))
ts.add(ttystatus.Literal(' done) '))
ts.add(ttystatus.RemainingTime('done', 'total'))
ts.add(ttystatus.Literal(' '))
ts.add(ttystatus.ProgressBar('done', 'total'))
ts['pathnames'] = pathnames
ts['done'] = 0
ts['total'] = len(pathnames)
for pathname in pathnames:
ts['pathname'] = pathname
if os.path.islink(pathname):
ts['symlink'] = pathname
ts.notify('Symlink! %s' % pathname)
ts['done'] += 1
ts.finish()
(See also the file example.py in the source distribution.)
Display the position of a value in a list of values.
Display data size in bytes, KiB, etc.
Display a progress bar.
Base class for ttystatus widgets.
Widgets are responsible for formatting part of the output. They get a value or values either directly from the user, or from the master TerminalStatus widget. They return the formatted string via __str__.
A widget’s value may be derived from values stored in the TerminalStatus widget (called master). Each such value has a key. Computing a widget’s value is a two-step process: when the values associated with keys are updated, the widget’s update() method is called to notify it of this. update() may compute intermediate values, such as maintain a counter of the number of changes. It should avoid costly operations that are only needed when the widget’s formatted value is needed. Those should go into the format() method instead. Thus, update() would update a counter, format() would create a string representing the counter.
This is necessary because actual on-screen updates only happen every so often, not every time a value in the master changes, and often the string formatting part is expensive.
Widgets must have an attribute ‘interesting_keys’, listing the keys it is interested in.
Format the current value.
This will be called only when the value actually needs to be formatted.
Update displayed value for widget, from values in master.
‘width’ gives the width for which the widget should aim to fit. It is OK if it does not: for some widgets there is no way to adjust to a smaller size.
Display data size in bytes, KiB, etc.
Display a count of how many times a value has changed.
Write messages to the terminal.
Show a notification message string to the user.
Notifications are meant for error messages and other things that do not belong in, say, progress bars. Whatever is currently on the terminal is wiped, then the notification message is shown, a new line is started, and the old message is restored.
Notifications are written even when the output is not going to a terminal.
Display elapsed time since widget was first updated.
Display a pathname.
If it won’t fit completely, truncate from the beginning of the string.
Display percent of task done.
Show status and progress information on a terminal.
All output is provided via widgets of various kinds. Many widgets format data that TerminalStatus stores. TerminalStatus provides a dict interface for setting and retrieving data items. Unlike a real dict, getting a value for a key that has not been set does not result in a KeyError exception, but in the empty string being returned.