consolekit.utils

Utility functions.

Changed in version 1.0.0: traceback_handler() and handle_tracebacks() moved to consolekit.tracebacks. They will still be importable from here until v2.0.0

Classes:

TerminalRenderer(​*extras)

Mistletoe markdown renderer for terminals.

Functions:

abort(​message[, colour])

Aborts the program execution.

coloured_diff(​a, b[, fromfile, tofile, …])

Compare two sequences of lines; generate the delta as a unified diff.

hidden_cursor(​)

Context manager to hide the cursor for the scope of the with block.

hide_cursor(​)

Hide the cursor.

import_commands(​[source, entry_point])

Returns a list of all commands.

is_command(​obj)

Return whether obj is a click command.

long_echo(​text[, use_pager, colour])

Echo text to the terminal, optionally via a pager.

overtype(​*objects[, sep, end, file, flush])

Print objects to the text stream file, starting with "\r", separated by sep and followed by end.

show_cursor(​)

Show the cursor.

Data:

braille_spinner

itertools.cycle() of braille characters to use as a loading spinner.

snake_spinner

itertools.cycle() of braille characters to use as a loading spinner which looks like a snake.

solidus_spinner

itertools.cycle() of characters to use as a loading spinner.

class TerminalRenderer(*extras)[source]

Bases: BaseRenderer

Mistletoe markdown renderer for terminals.

Tested in Gnome Terminal and Terminator (both libVTE-based), and PyCharm. libVTE has the best support. PyCharm’s support for italics and strikethrough is poor. Support on Windows is, as expected, poor.

Not tested on other terminals, but contributions are welcome to improve support.

New in version 0.8.0.

Methods:

render(​token)

Render the given token for display in a terminal.

render_emphasis(​token)

Render emphasis (*emphasis*).

render_inline_code(​token)

Render inline code (`code`).

render_line_break(​token)

Render a line break in a multiline paragraph.

render_list(​token)

Render a markdown list.

render_list_item(​token)

Render a markdown list item.

render_paragraph(​token)

Render a paragraph.

render_strikethrough(​token)

Render strikethrough (~~strikethrough~~).

render_strong(​token)

Render strong (**strong**).

render(token)[source]

Render the given token for display in a terminal.

Parameters

token

Return type

str

render_emphasis(token)[source]

Render emphasis (*emphasis*).

Parameters

token (Emphasis) – The token to render.

Return type

str

render_inline_code(token)[source]

Render inline code (`code`).

Parameters

token (InlineCode) – The token to render.

Return type

str

static render_line_break(token)[source]

Render a line break in a multiline paragraph.

Parameters

token

render_list(token)[source]

Render a markdown list.

Parameters

token (List) – The token to render.

Return type

str

render_list_item(token)[source]

Render a markdown list item.

Parameters

token (ListItem)

Return type

str

render_paragraph(token)[source]

Render a paragraph.

Parameters

token (Paragraph) – The token to render.

Return type

str

render_strikethrough(token)[source]

Render strikethrough (~~strikethrough~~).

Parameters

token (Strikethrough) – The token to render.

Return type

str

render_strong(token)[source]

Render strong (**strong**).

Parameters

token (Strong) – The token to render.

Return type

str

abort(message, colour=None)[source]

Aborts the program execution.

Parameters
  • message (str)

  • colour (Optional[bool]) – Whether to use coloured output. Default auto-detect.

Changed in version 1.0.1: Added the colour option.

Return type

Exception

braille_spinner = <itertools.cycle object>

Type:    cycle()

itertools.cycle() of braille characters to use as a loading spinner.

New in version 0.7.0.

coloured_diff(a, b, fromfile='', tofile='', fromfiledate='', tofiledate='', n=3, lineterm='\n', removed_colour='\x1b[31m', added_colour='\x1b[32m')[source]

Compare two sequences of lines; generate the delta as a unified diff.

Unified diffs are a compact way of showing line changes and a few lines of context. The number of context lines is set by n which defaults to three.

By default, the diff control lines (those with ---, +++, or @@) are created with a trailing newline. This is helpful so that inputs created from file.readlines() result in diffs that are suitable for file.writelines() since both the inputs and outputs have trailing newlines.

For inputs that do not have trailing newlines, set the lineterm argument to '' so that the output will be uniformly newline free.

The unidiff format normally has a header for filenames and modification times. Any or all of these may be specified using strings for fromfile, tofile, fromfiledate, and tofiledate. The modification times are normally expressed in the ISO 8601 format.

New in version 0.3.0.

Example:

>>> for line in coloured_diff(
...     'one two three four'.split(),
...     'zero one tree four'.split(), 'Original', 'Current',
...     '2005-01-26 23:30:50', '2010-04-02 10:20:52',
...     lineterm='',
...     ):
...     print(line)                 
--- Original        2005-01-26 23:30:50
+++ Current         2010-04-02 10:20:52
@@ -1,4 +1,4 @@
+zero
one
-two
-three
+tree
four
Parameters
  • a (Sequence[str])

  • b (Sequence[str])

  • fromfile (str) – Default ''.

  • tofile (str) – Default ''.

  • fromfiledate (str) – Default ''.

  • tofiledate (str) – Default ''.

  • n (int) – Default 3.

  • lineterm (str) – Default '\n'.

  • removed_colour (Colour) – The Colour to use for lines that were removed. Default '\x1b[31m'.

  • added_colour (Colour) – The Colour to use for lines that were added. Default '\x1b[32m'.

Return type

str

hidden_cursor()[source]

Context manager to hide the cursor for the scope of the with block.

New in version 0.7.0.

Changed in version 0.9.0: Moved to consolekit.utils.

Return type

Iterator

hide_cursor()[source]

Hide the cursor.

To show it again use show_cursor(), or use the hidden_cursor() context manager.

New in version 0.7.0.

import_commands(source=None, entry_point=None)[source]

Returns a list of all commands.

Commands can be defined locally in the module given in source, or by third party extensions who define an entry point in the following format:

<name (can be anything)> = <module name>:<command>
Parameters
Return type

List[Command]

is_command(obj)[source]

Return whether obj is a click command.

Parameters

obj

Return type

bool

long_echo(text, use_pager=None, colour=None)[source]

Echo text to the terminal, optionally via a pager.

New in version 1.2.0.

Parameters
  • text (Union[str, StringList, Iterable[str]])

  • use_pager (Optional[bool]) – If True, forces the use of the pager. If False the pager is never used. If None the pager is used if sys.stdout` is a TTY and the number of lines is less than the terminal height. Default None.

  • colour (Optional[bool]) – Whether to use coloured output. Default auto-detect.

Tip

Allow the user to control the value of use_pager with the no_pager_option() decorator.

overtype(*objects, sep=' ', end='', file=None, flush=False)[source]

Print objects to the text stream file, starting with "\r", separated by sep and followed by end.

sep, end, file and flush, if present, must be given as keyword arguments

All non-keyword arguments are converted to strings like str does and written to the stream, separated by sep and followed by end. If no such arguments are given, overtype() will just write "\r".

Parameters
  • objects – A list of strings or string-like objects to write to the terminal.

  • sep (str) – String to separate the objects with. Default '␣'.

  • end (str) – String to end with. Default ''.

  • file (Optional[IO]) – An object with a write(string) method. Default sys.stdout.

  • flush (bool) – If True, the stream is forcibly flushed. Default False.

show_cursor()[source]

Show the cursor.

See also

The hidden_cursor() context manager.

New in version 0.7.0.

snake_spinner = <itertools.cycle object>

Type:    cycle()

itertools.cycle() of braille characters to use as a loading spinner which looks like a snake.

New in version 1.1.0.

solidus_spinner = <itertools.cycle object>

Type:    cycle()

itertools.cycle() of characters to use as a loading spinner.

New in version 0.7.0.