`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, **kwargs)

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.
`echo`(message, *lines[, file, err, color])	Print the given line(s), separated by newlines, to stdout or a file.
`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, **kwargs)[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
Return type: str

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=<Colour('\x1b[31m', name='RED')>, added_colour=<Colour('\x1b[32m', name='GREEN')>)[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 <Colour('\x1b[31m', name='RED')>.
added_colour (Colour) – The Colour to use for lines that were added. Default <Colour('\x1b[32m', name='GREEN')>.

Return type

str

echo(message, *lines, file=None, err=False, color=None)[source]

Print the given line(s), separated by newlines, to stdout or a file.

Parameters

message (Union[str, Sequence[str]]) – The message to print.
*lines (str) – Additional lines to print.
file (Optional[IO]) – The file to write to. Defaults to stdout. Default None.
err (bool) – Write to stderr instead of stdout. Default False.
color (Optional[bool]) – Force showing or hiding colors and other styles. By default Click will remove color if the output does not look like an interactive terminal. Default None.

New in version 1.12.0.

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

source (Optional[ModuleType]) – Default None.
entry_point (Optional[str]) – Default None.

Return type

List[Command]

is_command(obj)[source]

Return whether obj is a click command.

Parameters: obj (Any)
Return type: TypeGuard[Command]

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.

consolekit.utils

`consolekit.utils`