API

linotype.ansi_format(fg=None, bg=None, bold=False, underline=False) → typing.Tuple[str, str]

Get the appropriate ANSI escape sequences based on input.

Not all features are supported on all terminals.

Parameters:

• fg – The foreground color specification. This can be the name of one of the eight ANSI colors, an integer in the range 0-255 or a CSS-style hex value. ‘None’ means no formatting.
• bg – The background color specification. This can be the name of one of the eight ANSI colors, an integer in the range 0-255 or a CSS-style hex value. ‘None’ means no formatting.
• bold – Make the text bold.
• underline – Make the text underlined.

Raises:

ValueError – The given color spec was unrecognized.

Returns:

A tuple containing the starting and ending ANSI escape sequences.

class linotype.DefStyle

Styles for definition items.

PARAGRAPH, P

Display the message as a paragraph on a separate line from the term and argument string.

INLINE, I

Display the message on the same line as the term and argument string. Use a hanging indent if the message is too long.

ALIGNED, A

Display the message on the same line as the term and argument string and align the message with those of all other definitions that belong to the same parent item and have the style ALIGNED. Use a hanging indent if the message is too long.

OVERFLOW, O

Display the message on a separate line from the term and argument string and align the message with those of all other definitions that belong to the same parent item and have a style of ALIGNED. Use a hanging indent if the message is too long.

class linotype.Formatter(max_width=79, auto_width=True, indent_spaces=4, def_gap=2, def_style=<DefStyle.PARAGRAPH: 1>, auto_markup=True, manual_markup=True, visible=True, strong=('x1b[1m', 'x1b[0m'), em=('x1b[4m', 'x1b[0m')) → None

Control how the text output is formatted.

max_width

The maximum number of columns at which to wrap text in the text output.

auto_width

Wrap the text to the size of the terminal.

indent_spaces

The number of spaces to increase/decrease the indent level by for each level.

def_gap

The minimum number of spaces to leave between the argument string and message of each definition when they are on the same line.

def_style

A DefStyle instance representing the style of definition to use.

auto_markup

Automatically apply ‘strong’ and ‘emphasized’ formatting to certain text in the output.

manual_markup

Parse reST ‘strong’ and ‘emphasized’ inline markup.

visible

Make the text visible in the output.

strong

A 2-tuple containing the strings to print before and after strings marked up as ‘strong’. The default is ANSI bold.

em

A 2-tuple containing the strings to print before and after strings marked up as ‘emphasized’. The default is ANSI underlined.

class linotype.Item(formatter=<linotype.items.Formatter object>) → None

An item to be displayed in the output.

This class allows for formatting text output consisting of a tree of “items”. There are multiple types of items to choose from, and every item can contain other items which are indented relative to the parent item. Items at the same level are displayed at the order in which they were created.

This class is used to create a root-level item, and new child items can be created using its public methods. Every item has a Formatter instance which determines how it is formatted in the text output. Every item also has an ID which can be referenced in the Sphinx documentation or when formatting the text output.

Parameters:formatter – The Formatter object for the item tree.

content

The content to display in the output.

formatter

The Formatter object for the item tree.

id

The item ID.

current_level

The current indentation level.

parent

The parent Item object.

_format_func

The function used for formatting the text output.

_current_indent

The number of spaces that the item is currently indented.

children

A list of all Item objects belonging to this item.

add_def(term: str, args: str, message: str, formatter=None, item_id=None) → linotype.items.Item

Add a definition item to be printed.

This item displays a formatted definition in one of multiple styles. The style is set by the Formatter instance. Definitions consist of a term, an argument string and a message, any of which can be blank.

Parameters:

• term – The command, option, etc. to be defined. If auto markup is enabled, this is strong in the text output.
• args – The list of arguments for the thing being defined as a single string. If auto markup is enabled, arguments are emphasized in the text output. Arguments are consecutive strings of unicode word characters
• message – A description of the thing being defined, with arguments that appear in the argument string emphasized if auto markup is enabled.
• formatter – A Formatter instance for defining the formatting of the new item. If ‘None,’ it uses the formatter of its parent item.
• item_id – A unique ID for the item that can be referenced in the Sphinx documentation or when formatting the text output.

Returns:

The new Item object.

add_text(text: str, formatter=None, item_id=None) → linotype.items.Item

Add a text item to be printed.

This item displays the given text wrapped to the given width.

Parameters:

• text – The text to be printed.
• formatter – A Formatter object for defining the formatting of the new item. If ‘None,’ it uses the formatter of its parent item.
• item_id – A unique ID for the item that can be referenced in the Sphinx documentation or when formatting the text output.

Returns:

The new Item object.

format(levels=None, item_id=None) → str

Print a tree of items.

Parameters:

• levels – The number of levels of nested items to descend into.
• item_id – The ID of the root item. If ‘None,’ this defaults to the current item.

Returns:

The text output as a single string.