maestral.utils.cli

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

Module Contents

Classes

Align

Text alignment in column

Elide

Elide directives

Prefix

Prefix for command line output

Field

Base class to represent a field in a table.

TextField

A text field for a table.

DateField

A datetime field for a table. The formatting of the datetime will be adjusted

Column

A table column.

Table

A table which can be printed to stdout.

Grid

A grid of fields which can be printed to stdout.

loading

RemoteApiError

CliException

Functions

elide(text: str, width: int, placeholder: str = '…', elide: Elide = Elide.Trailing) → str

Elides a string to fit into the given width.

adjust(text: str, width: int, align: Align = Align.Left) → str

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

echo(message: str, nl: bool = True, prefix: Prefix = Prefix.NONE) → None

info(message: str, nl: bool = True) → None

warn(message: str, nl: bool = True) → None

ok(message: str, nl: bool = True) → None

prompt(message: str, default: str = '', validate: Optional[Callable] = None) → str

confirm(message: str, default: Optional[bool] = True) → bool

select(message: str, options: Sequence[str], hint='') → int

select_multiple(message: str, options: Sequence[str], hint='') → List[int]

select_path(message: str, default: str = '', validate: Callable = lambda x: True, exists: bool = False, only_directories: bool = False) → str

class maestral.utils.cli.Align[source]

Bases: enum.Enum

Text alignment in column

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

Bases: enum.Enum

Elide directives

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

Bases: enum.Enum

Prefix for command line output

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

Elides a string to fit into the given width.

Parameters
  • text – Text to truncate.

  • width – Target width.

  • placeholder – Placeholder string to indicate truncated text.

  • elide – Which part to truncate.

Returns

Truncated text.

maestral.utils.cli.adjust(text: str, width: int, align: Align = Align.Left)str[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 – Initial string.

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

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

class maestral.utils.cli.Field[source]

Base class to represent a field in a table.

property display_width(self)int[source]

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

abstract format(self, width: int) → List[str][source]

Returns the field content formatted to fit the requested width.

Parameters

width – Width to fit.

Returns

Shortened or wrapped string.

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

Bases: maestral.utils.cli.Field

A text field for a table.

Parameters
  • text – Text to represent.

  • align – Text alignment: right or left.

  • wraps – 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

Truncation strategy: trailing, center or leading.

property display_width(self)int[source]

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

format(self, width: int) → List[str][source]

Returns the field content formatted to fit the requested width.

Parameters

width – Width to fit.

Returns

Shortened or wrapped string.

class maestral.utils.cli.DateField(dt: datetime, **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 to represent.

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

property display_width(self)int[source]

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

format(self, width: int) → List[str][source]

Returns the field content formatted to fit the requested width.

Parameters

width – Width to fit.

Returns

Shortened or wrapped string.

class maestral.utils.cli.Column(title: Optional[str], fields: Sequence = (), align: Align = Align.Left, wraps: bool = False, elide: Elide = Elide.Trailing)[source]

A table column.

Parameters
  • title – Column title.

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

  • align – How to align text inside the column. Will only be used for :class:`TextField`s.

  • wraps – Whether to wrap fields to fit into the column width instead of truncating them. Will only be used for :class:`TextField`s.

  • elide – How to elide text which is too wide for a column. Will only be used for :class:`TextField`s.

fields :List[Field][source]
property display_width(self)int[source]
property has_title(self)[source]
append(self, field: Any)None[source]
insert(self, index: int, field: Any)None[source]
class maestral.utils.cli.Table(columns: List[Union[Column, str]], padding: int = 2)[source]

A table which can be printed to stdout.

Parameters
  • columns – Table columns. Can be a list of Column instances or table titles.

  • padding – Padding between columns.

columns :List[Column][source]
property ncols(self)int[source]

The number of columns

property nrows(self)int[source]

The number of rows

append(self, row: Sequence)None[source]

Appends a new row to the table.

Parameters

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

rows(self) → List[List[Field]][source]

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

format_lines(self, width: Optional[int] = None) → Iterator[str][source]

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

Parameters

width – Width to fit the table.

Returns

Iterator over lines which can be printed to the terminal.

format(self, width: Optional[int] = None)str[source]

Returns a fully formatted table as a string with linebreaks.

Parameters

width – Width to fit the table.

Returns

Formatted table.

echo(self)[source]

Prints the table to the terminal.

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

A grid of fields which can be printed to stdout.

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

  • padding – Padding between fields.

  • align – Alignment of strings in the grid.

fields :List[Field][source]
append(self, field: Any)None[source]

Appends a field to the grid.

format_lines(self, width: Optional[int] = None) → Iterator[str][source]

Iterator over formatted lines of the grid.

Parameters

width – Width to fit the grid.

Returns

Iterator over lines which can be printed to the terminal.

format(self, width: Optional[int] = None)str[source]

Returns a fully formatted grid as a string with linebreaks.

Parameters

width – Width to fit the table.

Returns

Formatted grid.

echo(self)[source]

Prints the grid to the terminal.

maestral.utils.cli.echo(message: str, nl: bool = True, prefix: Prefix = Prefix.NONE)None[source]
maestral.utils.cli.info(message: str, nl: bool = True)None[source]
maestral.utils.cli.warn(message: str, nl: bool = True)None[source]
maestral.utils.cli.ok(message: str, nl: bool = True)None[source]
maestral.utils.cli.orange = [source]
maestral.utils.cli.cyan = [source]
maestral.utils.cli.grey = [source]
maestral.utils.cli.bold = [source]
maestral.utils.cli.response_color[source]
maestral.utils.cli.focus_color[source]
class maestral.utils.cli.loading(iterable, prefix='Loading', animation=None, clear=True)[source]
maestral.utils.cli.prompt(message: str, default: str = '', validate: Optional[Callable] = None)str[source]
maestral.utils.cli.confirm(message: str, default: Optional[bool] = True)bool[source]
maestral.utils.cli.select(message: str, options: Sequence[str], hint='')int[source]
maestral.utils.cli.select_multiple(message: str, options: Sequence[str], hint='') → List[int][source]
maestral.utils.cli.select_path(message: str, default: str = '', validate: Callable = lambda x: ..., exists: bool = False, only_directories: bool = False)str[source]
class maestral.utils.cli.RemoteApiError(title: str, message: str)[source]

Bases: click.ClickException

format_message(self)str[source]
show(self, file=None)None[source]
class maestral.utils.cli.CliException[source]

Bases: click.ClickException

show(self, file=None)None[source]