maestral.utils.cli

Module to print neatly formatted tables and grids to the terminal.

class maestral.utils.cli.Align(value)[source]

Bases: enum.Enum

Text alignment in column

Left = 0

Right = 1

class maestral.utils.cli.Elide(value)[source]

Bases: enum.Enum

Elide directives

Leading = 0

Center = 1

Trailing = 2

class maestral.utils.cli.Prefix(value)[source]

Bases: enum.Enum

Prefix for command line output

Info = 0

Ok = 1

Warn = 2

NONE = 3

maestral.utils.cli.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 (maestral.utils.cli.Elide) – Which part to truncate.

Returns

Truncated text.

Return type

str

maestral.utils.cli.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 (maestral.utils.cli.Align) – Side to align the padded string: to the left or to the right.

Return type

str

maestral.utils.cli.get_term_width()[source]

Return type: int

class maestral.utils.cli.Field[source]

Bases: object

Base class to represent a field in a table.

property display_width: int: The requested total width of the content in characters when not wrapped or shortened in any way.

format(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.utils.cli.TextField(text, align=Align.Left, wraps=False, elide=Elide.Trailing, **style)[source]

Bases: maestral.utils.cli.Field

A text field for a table.

Parameters

text (str) – Text to represent.
align (maestral.utils.cli.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 (maestral.utils.cli.Elide) –

Elide

Truncation strategy: trailing, center or leading.

Return type

None

property display_width: int

format(width)[source]

Parameters: width (int) –
Return type: List[str]

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

Bases: maestral.utils.cli.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 to represent.
style – Styling passed on to click.style() when styling the text.

Return type

None

property display_width: int

format(width)[source]

Parameters: width (int) –
Return type: List[str]

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

Bases: object

A table column.

Parameters

title (Optional[str]) – Column title.
fields (List[maestral.utils.cli.Field]) – Fields in the table. Any sequence of objects can be given and will be converted to Field instances as appropriate.
align (maestral.utils.cli.Align) – How to align text inside the column. Will only be used for :class:`TextField`s.
wraps (bool) – Whether to wrap fields to fit into the column width instead of truncating them. Will only be used for :class:`TextField`s.
elide (maestral.utils.cli.Elide) – How to elide text which is too wide for a column. Will only be used for :class:`TextField`s.

Return type

None

fields: List[maestral.utils.cli.Field]

property display_width: int

property has_title

append(field)[source]

Parameters: field (Any) –
Return type: None

insert(index, field)[source]

Parameters

index (int) –
field (Any) –

Return type

None

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

Bases: object

A table which can be printed to stdout.

Parameters

columns (List[maestral.utils.cli.Column]) – Table columns. Can be a list of Column instances or table titles.
padding (int) – Padding between columns.

Return type

None

columns: List[maestral.utils.cli.Column]

property ncols: int: The number of columns

property nrows: int: The number of rows

append(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()[source]

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

Return type: List[List[maestral.utils.cli.Field]]

format_lines(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 (Optional[int]) – 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(width=None)[source]

Returns a fully formatted table as a string with linebreaks.

Parameters: width (Optional[int]) – Width to fit the table. Defaults to terminal width if not given.
Returns: Formatted table.
Return type: str

echo()[source]: Prints the table to the terminal.

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

Bases: object

A grid of fields which can be printed to stdout.

Parameters

fields (List[maestral.utils.cli.Field]) – A sequence of fields (strings, datetimes, any objects with a string representation).
padding (int) – Padding between fields.
align (maestral.utils.cli.Align) – Alignment of strings in the grid.

fields: List[maestral.utils.cli.Field]

append(field)[source]

Appends a field to the grid.

Parameters: field (Any) –
Return type: None

format_lines(width=None)[source]

Iterator over formatted lines of the grid.

Parameters: width (Optional[int]) – 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(width=None)[source]

Returns a fully formatted grid as a string with linebreaks.

Parameters: width (Optional[int]) – Width to fit the table. Defaults to terminal width if not given.
Returns: Formatted grid.
Return type: str

echo()[source]: Prints the grid to the terminal.

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

Parameters

message (str) –
nl (bool) –
prefix (maestral.utils.cli.Prefix) –

Return type

None

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

Parameters

message (str) –
nl (bool) –

Return type

None

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

Parameters

message (str) –
nl (bool) –

Return type

None

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

Parameters

message (str) –
nl (bool) –

Return type

None

maestral.utils.cli.prompt(message, default=None, validate=None)[source]

Parameters

message (str) –
default (Optional[str]) –
validate (Optional[Callable]) –

Return type

str

maestral.utils.cli.confirm(message, default=True)[source]

Parameters

message (str) –
default (Optional[bool]) –

Return type

bool

maestral.utils.cli.select(message, options, hint='')[source]

Parameters

message (str) –
options (Sequence[str]) –

Return type

int

maestral.utils.cli.select_multiple(message, options, hint='')[source]

Parameters

message (str) –
options (Sequence[str]) –

Return type

List[int]

maestral.utils.cli.select_path(message, default=None, validate=<function <lambda>>, exists=False, files_allowed=True, dirs_allowed=True)[source]

Parameters

message (str) –
default (Optional[str]) –
validate (Callable) –
exists (bool) –
files_allowed (bool) –
dirs_allowed (bool) –

Return type

str

exception maestral.utils.cli.CliException(message)[source]

Bases: click.exceptions.ClickException

Parameters: message (str) –
Return type: None

show(file=None)[source]

Return type: None