zabgrab.ui.render

Rendering of command results for the terminal.

zabgrab.ui.render.ConfigLine

A line of TOML and the source of its value (None for structural lines).

Type:

type

zabgrab.ui.render.SOURCE_SEPARATOR

Separates the sources from the TOML in config show --sources.

Type:

str

zabgrab.ui.render.LAYER_STYLES

Styles of the source column in config show --sources, by layer. They avoid the colours used to highlight TOML, so the two can’t be confused.

Type:

dict

zabgrab.ui.render.ITEM_SORT_KEYS

How to sort items by each of items_table()’s columns.

Type:

dict

Functions

config_lines(loaded)

Write the merged config as lines of TOML, each with the source of its value.

config_to_toml(loaded)

Write the merged config as TOML.

config_with_sources(loaded)

Write the merged config as TOML, each line prefixed by its value's source.

explain_table(query)

Make a table of a query's settings, and where each came from.

file_groups_table(groups, tz, *[, repeated])

Make a table of the fetch groups in a file, for zabgrab info --groups.

file_items_table(series, tz)

Make a table of the items in a file, for zabgrab info.

format_age(age)

Format an age compactly, in its largest whole unit.

format_item_spec_safe(spec)

Format an item spec for display, including host choices.

format_time(time, tz)

Format a time for display.

highlighted_toml(text)

Highlight TOML's sections, keys, values and comments.

hosts_table(rows)

Make a table of hosts, with a server column if there's more than one server.

items_table(rows, *, now)

Make a table of items, with a server column if there's more than one server.

layers_table(layers)

Make a table of config layers, lowest priority first.

plan_table(jobs, resolution)

Make a table of the items that would be fetched (for --dry-run).

requests_table(query)

Make a table of what will be fetched, before items are looked up.

sort_items(rows[, column])

Sort items by a column of items_table(), then by item ID.

tokens_table(statuses[, results])

Make a table of servers and where their tokens come from.

Classes

DataTable(*headers[, title, caption, width, ...])

A table whose string cells are always plain text, never rich markup.
class zabgrab.ui.render.DataTable(*headers, title=None, caption=None, width=None, min_width=None, box=Box(...), safe_box=None, padding=(0, 1), collapse_padding=False, pad_edge=True, expand=False, show_header=True, show_footer=False, show_edge=True, show_lines=False, leading=0, style='none', row_styles=None, header_style='table.header', footer_style='table.footer', border_style=None, title_style=None, caption_style=None, title_justify='center', caption_justify='center', highlight=False)[source]

Bases: Table

A table whose string cells are always plain text, never rich markup.

Cells often hold data from servers or config (e.g. the item key vfs.fs.size[/,pfree]), which must be shown exactly as it is.

Parameters:

  • headers (Column | str)

  • title (str | Text | None)

  • caption (str | Text | None)

  • width (int | None)

  • min_width (int | None)

  • box (Box | None)

  • safe_box (bool | None)

  • padding (int | Tuple[int] | Tuple[int, int] | Tuple[int, int, int, int])

  • collapse_padding (bool)

  • pad_edge (bool)

  • expand (bool)

  • show_header (bool)

  • show_footer (bool)

  • show_edge (bool)

  • show_lines (bool)

  • leading (int)

  • style (str | Style)

  • row_styles (Iterable[str | Style] | None)

  • header_style (str | Style | None)

  • footer_style (str | Style | None)

  • border_style (str | Style | None)

  • title_style (str | Style | None)

  • caption_style (str | Style | None)

  • title_justify (JustifyMethod)

  • caption_justify (JustifyMethod)

  • highlight (bool)

add_row(*renderables, **kwargs)[source]

Add a row, as rich.table.Table.add_row() but with plain text cells.

Parameters:

  • renderables (ConsoleRenderable | RichCast | str | None)

  • kwargs (Any)

Return type:

None

zabgrab.ui.render.layers_table(layers)[source]

Make a table of config layers, lowest priority first.

Parameters:

layers (iterable of ConfigLayer) – The layers.

Returns:

rich.table.Table – The table.

Return type:

Table

zabgrab.ui.render.config_lines(loaded)[source]

Write the merged config as lines of TOML, each with the source of its value.

[defaults] keys have individual sources; each server and template takes the source of the file that defined it.

Parameters:

loaded (LoadedConfig) – The config and its layers.

Returns:

list of ConfigLine – The lines.

Return type:

list[tuple[str | None, str]]

zabgrab.ui.render.config_to_toml(loaded)[source]

Write the merged config as TOML.

Parameters:

loaded (LoadedConfig) – The config.

Returns:

str – The TOML.

Return type:

str

zabgrab.ui.render.highlighted_toml(text)[source]

Highlight TOML’s sections, keys, values and comments.

Parameters:

text (str) – The TOML.

Returns:

rich.text.Text – The highlighted text.

Return type:

Text

zabgrab.ui.render.config_with_sources(loaded)[source]

Write the merged config as TOML, each line prefixed by its value’s source.

The source column is as wide as the widest source, and styled by the layer the value came from (see LAYER_STYLES). The TOML is highlighted as by highlighted_toml().

Parameters:

loaded (LoadedConfig) – The config and its layers.

Returns:

rich.text.Text – The highlighted lines.

Return type:

Text

zabgrab.ui.render.format_age(age)[source]

Format an age compactly, in its largest whole unit.

Parameters:

age (timedelta) – The age; negative ages show as 0s.

Returns:

str – The age.

Return type:

str

Examples

>>> format_age(timedelta(minutes=150))
'2h'
zabgrab.ui.render.hosts_table(rows)[source]

Make a table of hosts, with a server column if there’s more than one server.

Parameters:

rows (sequence of tuple of Server and Host) – The hosts and the servers they’re on.

Returns:

rich.table.Table – The table.

Return type:

Table

zabgrab.ui.render.sort_items(rows, column='Item ID')[source]

Sort items by a column of items_table(), then by item ID.

The sort is stable, so the same item ID on several servers keeps the order the servers were queried in.

Parameters:

  • rows (iterable of tuple of Server and Item) – The items and the servers they’re on.

  • column (str, optional) – A key of ITEM_SORT_KEYS.

Returns:

list of tuple of Server and Item – The sorted rows.

Return type:

list[tuple[Server, Item]]

zabgrab.ui.render.items_table(rows, *, now)[source]

Make a table of items, with a server column if there’s more than one server.

Parameters:

  • rows (sequence of tuple of Server and Item) – The items and the servers they’re on.

  • now (datetime) – The current time, to show the ages of last values.

Returns:

rich.table.Table – The table.

Return type:

Table

zabgrab.ui.render.tokens_table(statuses, results=None)[source]

Make a table of servers and where their tokens come from.

Parameters:

  • statuses (sequence of TokenStatus) – The servers’ tokens.

  • results (sequence of CheckResult, optional) – The results of checking each token, shown in an extra column.

Returns:

rich.table.Table – The table.

Return type:

Table

zabgrab.ui.render.format_time(time, tz)[source]

Format a time for display.

Parameters:

  • time (datetime) – The time.

  • tz (tzinfo or None) – The timezone to show it in (None for local time).

Returns:

str – The time, with its timezone’s abbreviation.

Return type:

str

zabgrab.ui.render.explain_table(query)[source]

Make a table of a query’s settings, and where each came from.

Parameters:

query (Query) – The query.

Returns:

rich.table.Table – The table.

Return type:

Table

zabgrab.ui.render.requests_table(query)[source]

Make a table of what will be fetched, before items are looked up.

Parameters:

query (Query) – The query.

Returns:

rich.table.Table – The table.

Return type:

Table

zabgrab.ui.render.format_item_spec_safe(spec)[source]

Format an item spec for display, including host choices.

Parameters:

spec (ItemSpec) – The spec.

Returns:

str – The spec, as it would be written on the command line, with host choices written out.

Return type:

str

zabgrab.ui.render.plan_table(jobs, resolution)[source]

Make a table of the items that would be fetched (for –dry-run).

Parameters:

  • jobs (sequence of Job) – The items to fetch.

  • resolution (Resolution) – The resolution, to tell which items would be skipped.

Returns:

rich.table.Table – The table.

Return type:

Table

zabgrab.ui.render.file_items_table(series, tz)[source]

Make a table of the items in a file, for zabgrab info.

Parameters:

  • series (sequence of Series) – The items’ merged data.

  • tz (tzinfo or None) – The time zone to show times in (None for local time).

Returns:

rich.table.Table – The table, with a server column if there’s more than one server.

Return type:

Table

zabgrab.ui.render.file_groups_table(groups, tz, *, repeated=None)[source]

Make a table of the fetch groups in a file, for zabgrab info --groups.

Parameters:

  • groups (sequence of tuple) – Each group’s name, creation time (ISO 8601, if recorded), fetched range (in POSIX seconds), and number of items and points.

  • tz (tzinfo or None) – The time zone to show times in (None for local time).

  • repeated (sequence of int, optional) – If given, each group’s number of points that another group also holds, shown in a Repeated column.

Returns:

rich.table.Table – The table.

Return type:

Table