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
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]
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
Return type

None

maestral.utils.cli.info(message, nl=True)[source]
Parameters
Return type

None

maestral.utils.cli.warn(message, nl=True)[source]
Parameters
Return type

None

maestral.utils.cli.ok(message, nl=True)[source]
Parameters
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