Terminal¶
These are helpers for application output on a terminal.
New in version 0.6.
-
class
brownie.terminal.
TerminalWriter
(stream=<open file '<stdout>', mode 'w'>, fallback_encoding='ascii', prefix=u'', indent=' ', autoescape=True, ignore_options=None)[source]¶ This is a helper for dealing with output to a terminal.
Parameters: - stream – The stream to which the output is written, per default sys.stdout.
- fallback_encoding – The encoding used if stream doesn’t provide one.
- 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
= 80¶ Specifies the default terminal width.
-
stream
= None¶ The stream to which the output is written.
-
prefix
= None¶ The prefix used by
writeline()
.
-
indent_string
= None¶ The string used for indentation.
-
autoescape
= None¶ True
if escaping should be done automatically.
-
encoding
¶ The encoding provided by the stream or
fallback_encoding
.
-
escape
(string)[source]¶ 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.
-
get_dimensions
()[source]¶ Returns a
Dimensions
object.May raise
NotImplementedError
depending on the stream or platform.
-
get_width
(default=None)[source]¶ 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)[source]¶ 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.
-
options
(*args, **kwds)[source]¶ 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
-
line
(*args, **kwds)[source]¶ A contextmanager which can be used instead of
writeline()
.This is useful if you want to write a line with multiple different options.
-
should_escape
(escape)[source]¶ Returns
autoescape
if escape is None otherwise escape.
-
write
(string, escape=None, flush=True, **options)[source]¶ 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.
- escape – Overrides
-
writeline
(line, escape=None, flush=True, **options)[source]¶ 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.
- escape – Overrides
-
writelines
(lines, escape=None, flush=True, **options)[source]¶ 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.
- escape – Overrides
-
hr
(character=u'-')[source]¶ 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)[source]¶ 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 >>> writer.table( ... [ ... [u'foo', u'bar'], ... [u'spam', u'eggs'] ... ], ... [u'hello', u'world'] ... ) hello | world ------+------ foo | bar spam | eggs
-
progress
(description, maxsteps=None, widgets=None)[source]¶ 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()
orProgressBar.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 thestream
while using a progress bar the behaviour is undefined.See also
-
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)[source]¶ 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()
andfinish()
.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)[source]¶ 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
()[source]¶ Returns an iterable of tuples consisting of the position of the widget and the widget itself ordered by each widgets priority.
-
get_usable_width
()[source]¶ Returns the width usable by all widgets which don’t provide a size hint.
-
next
(**kwargs)[source]¶ 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.
-
class
brownie.terminal.progress.
Widget
[source]¶ Represents a part of a progress bar.
-
priority
= 0¶ 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
= False¶ Should be
True
if this widget depends onProgressBar.maxsteps
being set to something other thanNone
.
-
init
(progressbar, remaining_width, **kwargs)[source]¶ Called when the progress bar is initialized.
Should return the output of the widget as string.
-
-
class
brownie.terminal.progress.
HintWidget
(initial_hint=u'')[source]¶ 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
[source]¶ Represents a string showing the progress as percentage.
-
class
brownie.terminal.progress.
BarWidget
[source]¶ 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
[source]¶ 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)[source]¶ 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