Terminal

These are helpers for application output on a terminal.

New in version 0.6.

class brownie.terminal.TerminalWriter(stream, prefix=u'', indent=' ', autoescape=True, ignore_options=None)

This is a helper for dealing with output to a terminal.

Parameters:

• stream – A stream which takes unicode for writing.
• prefix – A prefix used when an entire line is written.
• indent – String used for indentation.
• autoescape – Defines if everything written is escaped (unless explicitly turned off), see escape() for more information.
• ignore_options – Defines if options should be ignored or not, per default options are ignored if the stream is not a tty.

After each call resulting in visible characters to be written to the stream the stream is flushed, certain methods allow to override this behaviour.

default_width

Specifies the default terminal width.

classmethod from_bytestream(stream, encoding=None, errors='strict', **kwargs)

Returns a TerminalWriter for the given byte stream.

If an encoding cannot be determined from the stream it will fallback to the given encoding, if it is None sys.getdefaultencoding() will be used.

Should an error occur during encoding you can specify what should happen with the errors parameter:

'strict'

Raise an exception if an error occurs.

'ignore'

Ignore the characters for which the error occurs, these will be removed from the string.

'replace'

Replaces the characters for which the error occurs with ‘safe’ characters, usually ‘?’.

stream

The stream to which the output is written.

prefix

The prefix used by writeline().

indent_string

The string used for indentation.

autoescape

True if escaping should be done automatically.

escape(string)

Escapes all control characters in the given string.

This is useful if you are dealing with ‘untrusted’ strings you want to write to a file, stdout or stderr which may be viewed using tools such as cat which execute ANSI escape sequences.

See also

http://www.ush.it/team/ush/hack_httpd_escape/adv.txt

get_dimensions()

Returns a Dimensions object.

May raise NotImplementedError depending on the stream or platform.

get_width(default=None)

Returns the width of the terminal.

This falls back to the COLUMNS environment variable and if that fails to default_width unless default is not None, in which case default would be used.

Therefore the returned value might not not be at all correct.

get_usable_width(default_width=None)

Returns the width of the terminal remaining once the prefix and indentation has been written.

Parameters:default_width – The width which is assumed per default for the terminal, see get_width() for more information.

Warning

Tabs are considered to have a length of 1. This problem may be solved in the future until then it is recommended to avoid tabs.

indent()

Indent the following lines with the given indent.

dedent()

Dedent the following lines.

options(*args, **kwds)

A contextmanager which allows you to set certain options for the following writes.

Parameters:

• text_colour – The desired text colour.
• background_colour – The desired background colour.
• bold – If present the text is displayed bold.
• faint – If present the text is displayed faint.
• standout – If present the text stands out.
• underline – If present the text is underlined.
• blink – If present the text blinks.
• indentation – Adds a level of indentation if True.
• escape – Overrides the escaping behaviour for this block.

Note

The underlying terminal may support only certain options, especially the attributes (bold, faint, standout and blink) are not necessarily available.

The following colours are available, the exact colour varies between terminals and their configuration.

Colors
======
black  yellow teal
red    blue   white
green  purple

begin_line()

Writes the prefix and indentation to the stream.

line(*args, **kwds)

A contextmanager which can be used instead of writeline().

This is useful if you want to write a line with multiple different options.

newline()

Writes a newline to the stream.

should_escape(escape)

Returns autoescape if escape is None otherwise escape.

write(string, escape=None, flush=True, **options)

Writes the given string to the stream.

Parameters:

• escape – Overrides autoescape if given.
• options – Options for this operation, see options().
• flush – If True flushes the stream.

writeline(line, escape=None, flush=True, **options)

Writes the given line to the stream respecting indentation.

Parameters:

• escape – Overrides autoescape if given.
• options – Options for this operation, see options().
• flush – If True flushes the stream.

writelines(lines, escape=None, flush=True, **options)

Writes each line in the given iterable to the stream respecting indentation.

Parameters:

• escape – Overrides autoescape if given.
• options – Options for this operation, see options().
• flush – If True flushes the stream.

hr(character=u'-')

Writes a horizontal ruler with the width of the terminal to the stream.

Parameters:character – Specifies the character used for the ruler.

table(content, head=None, padding=1)

Writes a table using a list of rows (content) and an optional head.

Parameters:padding – Specifies the padding used for each cell to the left and right.

>>> import sys
>>> from brownie.terminal import TerminalWriter
>>> writer = TerminalWriter.from_bytestream(sys.stdout)
>>> writer.table([
...     [u'foo', u'bar'],
...     [u'spam', u'eggs']
... ])
foo  | bar
spam | eggs
<BLANKLINE>
>>> writer.table(
...     [
...         [u'foo', u'bar'],
...         [u'spam', u'eggs']
...     ],
...     [u'hello', u'world']
... )
hello | world
------+------
foo   | bar
spam  | eggs
<BLANKLINE>

progress(description, maxsteps=None, widgets=None)

Returns a ProgressBar object which can be used to write the current progress to the stream.

The progress bar is created from the description which is a string with the following syntax:

Widgets – the parts of the progress bar which are changed with each update – are represented in the form $[a-zA-Z]+.

Some widgets required that you provide an initial value, this can be done by adding :string where string is either [a-zA-Z]+ or a double-quoted string.

If you want to escape a $ you simply precede it with another $, so $$foo` will not be treated as a widget and in the progress bar ``$foo will be shown.

Quotes (") in strings can be escaped with a backslash (\).

The following widgets are available:

hint

Shows a string of text that can be given using the hint argument at any update performed with ProgressBar.init(), ProgressBar.next() or ProgressBar.finish(). If the argument is not given an empty string is used instead.

percentage

Shows the progress in percent; this requires maxsteps to be set.

bar

Shows a simple bar which moves which each update not corresponding with the progress being made. This is useful if you just want to show that something is happening.

sizedbar

Shows a simple progress bar which is being filled corresponding to the percentage of progress. This requires maxsteps to be set.

step

Shows the current at maximum number of steps as step of steps, this method takes an initial value determining the unit of each step e.g. if each step represents a byte and you choose bytes as a unit a reasonable prefix will be chosen.

Supported units:

• bytes - Uses a binary prefix.

This requires maxsteps to be set.

time

Shows the elapsed time in hours, minutes and seconds.

speed

Shows the speed in bytes (or with a reasonable prefix) per seconds, this assumes that each step represents a byte.

If you want to implement your own widget(s) take a look at brownie.terminal.progress.Widget, you can use them by passing them in a dictionary (mapping the name to the widget class) via the widgets argument. You might also want to take a look at the source code of the built-in widgets.

There are two things you have to look out for: ProgressBar objects are not reusable if you need another object, call this method again. If you attempt to write to the stream while using a progress bar the behaviour is undefined.

class brownie.terminal.Dimensions

A namedtuple representing the dimensions of a terminal.

Parameters:

• height – The height of the terminal.
• width – The width of the terminal.

Progress Bar

This is the ‘low-level’ progress bar implementation used by TerminalWriter.progress().

class brownie.terminal.progress.ProgressBar(widgets, writer, maxsteps=None)

A progress bar which acts as a container for various widgets which may be part of a progress bar.

Initializing and finishing can be done by using the progress bar as a context manager instead of calling init() and finish().

Parameters:

• widgets – An iterable of widgets which should be used.
• writer – A TerminalWriter which is used by the progress bar.
• maxsteps – The number of steps, not necessarily updates, which are to be made.

classmethod from_string(string, writer, maxsteps=None, widgets=None)

Returns a ProgressBar from a string.

The string is used as a progressbar, $[a-zA-Z]+ is substituted with a widget as defined by widgets.

$ can be escaped with another $ e.g. $$foo will not be substituted.

Initial values as required for the HintWidget are given like this $hint:initial, if the initial value is supposed to contain a space you have to use a quoted string $hint:"foo bar"; quoted can be escaped using a backslash.

If you want to provide your own widgets or overwrite existing ones pass a dictionary mapping the desired names to the widget classes to this method using the widgets keyword argument. The default widgets are:

Name	Class	Requires maxsteps
text	TextWidget	No
hint	HintWidget	No
percentage	Percentage	Yes
bar	BarWidget	No
sizedbar	PercentageBarWidget	Yes
step	StepWidget	Yes
time	TimeWidget	No
speed	DataTransferSpeedWidget	No

get_widgets_by_priority()

Returns an iterable of tuples consisting of the position of the widget and the widget itself ordered by each widgets priority.

get_usable_width()

Returns the width usable by all widgets which don’t provide a size hint.

init(**kwargs)

Writes the initial progress bar to the terminal.

next(**kwargs)

Writes an updated version of the progress bar to the terminal.

If the update corresponds to multiple steps, pass the number of steps which have been made as an argument. If step is larger than maxsteps a ValueError is raised.

finish(**kwargs)

Writes the finished version of the progress bar to the terminal.

This method may be called even if maxsteps has not been reached or has not been defined.

class brownie.terminal.progress.Widget

Represents a part of a progress bar.

priority

The priority of the widget defines in which order they are updated. The default priority is 0.

This is important as the first widget being updated has the entire line available.

requires_fixed_size

Should be True if this widget depends on ProgressBar.maxsteps being set to something other than None.

size_hint(progressbar)

Should return the required size or None if it cannot be given.

init(progressbar, remaining_width, **kwargs)

Called when the progress bar is initialized.

Should return the output of the widget as string.

update(progressbar, remaining_width, **kwargs)

Called when the progress bar is updated, not necessarily with each step.

Should return the output of the widget as string.

finish(progressbar, remaining_width, **kwargs)

Called when the progress bar is finished, not necessarily after maxsteps has been reached, per default this calls update().

Should return the output of the widget as string.

class brownie.terminal.progress.TextWidget(text)

Represents static text in a progress bar.

class brownie.terminal.progress.HintWidget(initial_hint=u'')

Represents a ‘hint’, changing text passed with each update, in a progress bar.

Requires that ProgressBar.next() is called with a hint keyword argument.

This widget has a priority of 1.

class brownie.terminal.progress.PercentageWidget

Represents a string showing the progress as percentage.

class brownie.terminal.progress.BarWidget

A simple bar which moves with each update not corresponding with the progress being made.

The bar is enclosed in brackets, progress is visualized by tree hashes ### moving forwards or backwards with each update; the rest of the bar is filled with dots ..

class brownie.terminal.progress.PercentageBarWidget

A simple bar which shows the progress in terms of a bar being filled corresponding to the percentage of progress.

The bar is enclosed in brackets, progress is visualized with hashes # the remaining part uses dots ..

class brownie.terminal.progress.StepWidget(unit=None)

Shows at which step we are currently at and how many are remaining as step of steps.

Parameters:unit – If each step represents something other than a simple task e.g. a byte when doing file transactions, you can specify a unit which is used.

Supported units:

• ‘bytes’ - binary prefix only, SI might be added in the future

class brownie.terminal.progress.TimeWidget

Shows the elapsed time in hours, minutes and seconds as $hours:$minutes:$seconds.

This widget has a priority of 2.

class brownie.terminal.progress.DataTransferSpeedWidget

Shows the data transfer speed in bytes per second using SI prefixes.

This widget has a priority of 2.