maestral.cli.output

This module provides classes and methods for beautifully formatted output to stdout. This includes printing tables and grids, formatting dates and eliding strings.

Module Contents

class maestral.cli.output.Align[source]

Bases: enum.Enum

Text alignment in column

Left = 0[source]
Right = 1[source]
class maestral.cli.output.Elide[source]

Bases: enum.Enum

Elide directives

Leading = 0[source]
Center = 1[source]
Trailing = 2[source]
class maestral.cli.output.Prefix[source]

Bases: enum.Enum

Prefix for command line output

Info = 0[source]
Ok = 1[source]
Warn = 2[source]
NONE = 3[source]
maestral.cli.output.elide(text, width, placeholder='...', elide=Elide.Trailing)[source]

Elides a string to fit into the given width.

Parameters

  • text (str) – Text to truncate.

  • width (int) – Target width.

  • placeholder (str) – Placeholder string to indicate truncated text.

  • elide (Elide) – Which part to truncate.

Returns

Truncated text.

Return type

str

maestral.cli.output.adjust(text, width, align=Align.Left)[source]

Pads a string with spaces up the desired width. Preserves ANSI color codes without counting them towards the width.

This function is similar to str.ljust and str.rjust.

Parameters

  • text (str) – Initial string.

  • width (int) – Target width. If smaller than the given text, nothing is done.

  • align (Align) – Side to align the padded string: to the left or to the right.

Return type

str

class maestral.cli.output.Field[source]

Base class to represent a field in a table.

property display_width(self)[source]

The requested total width of the content in characters when not wrapped or shortened in any way.

Return type

int

abstract format(self, width)[source]

Returns the field content formatted to fit the requested width.

Parameters

width (int) – Width to fit.

Returns

Shortened or wrapped string.

Return type

list[str]

class maestral.cli.output.TextField(text, align=Align.Left, wraps=False, elide=Elide.Trailing, **style)[source]

Bases: Field

A text field for a table.

Parameters

  • text (str) – Text to represent.

  • align (Align) – Text alignment: right or left.

  • wraps (bool) – Whether to wrap the text instead of truncating it to fit into a requested width.

  • style – Styling passed on to click.style() when styling the text.

  • elide (Elide) –

Elide

Truncation strategy: trailing, center or leading.

property display_width(self)[source]

The requested total width of the content in characters when not wrapped or shortened in any way.

Return type

int

format(self, width)[source]

Returns the field content formatted to fit the requested width.

Parameters

width (int) – Width to fit.

Returns

Shortened or wrapped string.

Return type

list[str]

class maestral.cli.output.DateField(dt, **style)[source]

Bases: Field

A datetime field for a table. The formatting of the datetime will be adjusted depending on the available width. Does not currently support localisation.

Parameters

  • dt (datetime.datetime) – Datetime to represent.

  • style – Styling passed on to click.style() when styling the text.

property display_width(self)[source]

The requested total width of the content in characters when not wrapped or shortened in any way.

Return type

int

format(self, width)[source]

Returns the field content formatted to fit the requested width.

Parameters

width (int) – Width to fit.

Returns

Shortened or wrapped string.

Return type

list[str]

class maestral.cli.output.Column(title, fields=(), align=Align.Left, wraps=False, elide=Elide.Trailing)[source]

A table column.

Parameters

  • title (str | None) – Column title.

  • fields (Sequence) – Fields in the table. Any sequence of objects can be given and will be converted to Field instances as appropriate.

  • align (Align) – How to align text inside the column. Will only be used for TextField.

  • wraps (bool) – Whether to wrap fields to fit into the column width instead of truncating them. Will only be used for TextField.

  • elide (Elide) – How to elide text which is too wide for a column. Will only be used for TextField.

fields :list[Field][source]
property display_width(self)[source]
Return type

int

property has_title(self)[source]
append(self, field)[source]
Parameters

field (Any) –

Return type

None

insert(self, index, field)[source]
Parameters

  • index (int) –

  • field (Any) –

Return type

None

class maestral.cli.output.Table(columns, padding=2)[source]

A table which can be printed to stdout.

Parameters

  • columns (list[Column | str]) – Table columns. Can be a list of Column instances or table titles.

  • padding (int) – Padding between columns.

columns :list[Column][source]
property ncols(self)[source]

The number of columns

Return type

int

property nrows(self)[source]

The number of rows

Return type

int

append(self, row)[source]

Appends a new row to the table.

Parameters

row (Sequence) – List of fields to append to each column. Length must match the number of columns.

Return type

None

rows(self)[source]

Returns a list of rows in the table. Each row is a list of fields.

Return type

list[list[Field]]

format_lines(self, width=None)[source]

Iterator over formatted lines of the table. Fields may span multiple lines if they are set to wrap instead of truncate.

Parameters

width (int | None) – Width to fit the table. Defaults to terminal width if not given.

Returns

Iterator over lines which can be printed to the terminal.

Return type

Iterator[str]

format(self, width=None)[source]

Returns a fully formatted table as a string with linebreaks.

Parameters

width (int | None) – Width to fit the table. Defaults to terminal width if not given.

Returns

Formatted table.

Return type

str

echo(self)[source]

Prints the table to the terminal.

class maestral.cli.output.Grid(fields=(), padding=2, align=Align.Left)[source]

A grid of fields which can be printed to stdout.

Parameters

  • fields (Sequence) – A sequence of fields (strings, datetimes, any objects with a string representation).

  • padding (int) – Padding between fields.

  • align (Align) – Alignment of strings in the grid.

fields :list[Field][source]
append(self, field)[source]

Appends a field to the grid.

Parameters

field (Any) –

Return type

None

format_lines(self, width=None)[source]

Iterator over formatted lines of the grid.

Parameters

width (int | None) – Width to fit the grid. Defaults to terminal width if not given.

Returns

Iterator over lines which can be printed to the terminal.

Return type

Iterator[str]

format(self, width=None)[source]

Returns a fully formatted grid as a string with linebreaks.

Parameters

width (int | None) – Width to fit the table. Defaults to terminal width if not given.

Returns

Formatted grid.

Return type

str

echo(self)[source]

Prints the grid to the terminal.

maestral.cli.output.echo(message, nl=True, prefix=Prefix.NONE)[source]

Print a message to stdout.

Parameters

  • message (str) – The string to output.

  • nl (bool) – Whether to end with a new line.

  • prefix (Prefix) – Any prefix to output before the message,

Return type

None

maestral.cli.output.info(message, nl=True)[source]

Print an info message to stdout. Will be prefixed with a dash.

Parameters

  • message (str) – The string to output.

  • nl (bool) – Whether to end with a new line.

Return type

None

maestral.cli.output.warn(message, nl=True)[source]

Print a warning to stdout. Will be prefixed with an exclamation mark.

Parameters

  • message (str) – The string to output.

  • nl (bool) – Whether to end with a new line.

Return type

None

maestral.cli.output.ok(message, nl=True)[source]

Print a confirmation to stdout. Will be prefixed with a checkmark.

Parameters

  • message (str) – The string to output.

  • nl (bool) – Whether to end with a new line.

Return type

None