ttystatus – a terminal status library

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).

Example

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.format('%ElapsedTime() Looking for files: %Counter(pathname) found, '
          'currently in %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.)

Reference manual

class ttystatus.Index(name, listname)

Display the position of a value in a list of values.

render(render)
update(master)
class ttystatus.ByteSpeed(name, duration=None)

Display data size in bytes, KiB, etc.

now()

Wrapper around time.time for unit tests to overrride.

render(width)
update(master)
class ttystatus.Literal(string)

Display a literal string.

render(width)
class ttystatus.ProgressBar(done_name, total_name)

Display a progress bar.

render(width)
update(master)
class ttystatus.Widget

Base class for ttystatus widgets.

Widgets display stuff on screen. The value may depend on data provided by the user (at creation time), or may be computed from one or more values in the TerminalStatus object to which the widget object belongs.

There are two steps:

  • the widget update method is called by TerminalStatus whenever any of the values change
  • the widget render method is called by TerminalStatus when it is time to display things

Widgets may have a static size, or their size may vary. The static_width property reveals this. This affects rendering: static sized widgets are rendered at their one static size; variable sized widgets are shrunk, if necessary, to make everything fit into the available space. If it’s not possible to shrink enough, widgets are rendered from beginning until the space is full: variable sized widgets are rendered as small as possible in this case.

render(width)

Format the current value.

width is the available width for the widget. It need not use all of it. If it’s not possible for the widget to render itself small enough to fit into the given width, it may return a larger string, but the caller will probably truncate it.

This will be called only when the value actually needs to be formatted.

update(terminal_status)

React to changes in values stored in a TerminalStatus.

class ttystatus.String(key)

Display a value as a string.

render(render)
update(master)
class ttystatus.ByteSize(name)

Display data size in bytes, KiB, etc.

render(width)
update(ts)
class ttystatus.Integer(key)

Display a value as an integer.

render(width)
update(master)
class ttystatus.Counter(name)

Display a count of how many times a value has changed.

render(width)
update(master)
class ttystatus.Messager(output=None, period=None, open_tty=None)

Write messages to the terminal.

clear()

Remove current message from terminal.

disable()

Disable all output.

enable()

Enable output to happen.

finish()

Finalize output.

notify(string, f)

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.

set_width(actual_width)
time_to_write()

Is it time to write now?

write(string)

Write raw data, always.

class ttystatus.ElapsedTime

Display elapsed time since widget was first updated.

get_time()

Wrapper around time.time() for unit tests to override.

render(width)
update(master)
class ttystatus.Pathname(key)

Display a pathname.

If it won’t fit completely, truncate from the beginning of the string.

render(width)
update(master)
class ttystatus.PercentDone(done_name, total_name, decimals=0)

Display percent of task done.

render(render)
update(master)
class ttystatus.TerminalStatus(output=None, period=None, messager=None)

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.

add(widget)

Add a new widget to the status display.

clear()

Remove all widgets.

disable()

Disable all output.

enable()

Enable output if it has been disabled.

error(msg)

Write an error message.

finish()

Finish status display.

flush()

Force an update of current state to the screen.

This happens even if it is not yet time to output the screen.

format(format_string)

Add new widgets based on format string.

The format string is taken literally, except that %% is a literal percent character, and %Foo(a,b,c) is a widget of type Foo with parameters a, b, and c. For example: format("hello, %String(name)").

get(key, default=None)

Like dict.get.

increase(key, delta)

Increase value for a key by a given amount.

notify(msg)

Show a message.

class ttystatus.RemainingTime(done_name, total_name)

Display an estimate of the remaining time.

get_time()

Return current time.

This is just a wrapper around time.time() so that it is easier to override during unit tests.

render(render)
update(master)

Indices and tables

Table Of Contents

This Page