API

monotable.HR_ROW

Row containing a horizontal rule to use as a row in cellgrid.

monotable.VR_COL

Vertical rule column for use as a column_tuple with monocol().

monotable.MonoTable

Class to create an aligned and formatted text table from a grid of cells.

Functions

The convenience functions below are the quickest way to generate an Ascii table. They create and configure a temporary instance of the class MonoTable and call a member function.

monotable.mono(headings: Iterable[str] = (), formats: Iterable[str] = (), cellgrid: Iterable[Iterable[Any]] = ((),), title: str = '', *, bordered: bool = False, format_func_map: Mapping[str, Callable[[Any, str], str]] | None = None, guideline_chars: str = '---', indent: str = '') → str

Generate ASCII table from cellgrid.

Parameters:

  • headings – Iterable of strings for each column heading.

  • formats – Iterable of format strings of the form [align_spec][directives][format_spec]. Please see Format directive string syntax.

  • cellgrid – representing table cells.

  • title – [align_spec][wrap_spec]string. Text to be aligned and printed above the text table. Please see Title string syntax.

Keyword Arguments:

  • bordered – True means generate table with ASCII cell border characters.

  • format_func_map –

    Dictionary of format functions keyed by name. name, when used as a format directive in a format string, selects the corresponding function from the dictionary.

    If a key is one of the included format directive function names like ‘boolean’, ‘mformat’, etc. the included format directive function is hidden.

    This value overrides format_func_map in the MonoTable instance that generates the table.

  • guideline_chars – String of 0 to 3 characters to specify top, heading, and bottom guideline appearance. This value overrides guideline_chars in the MonoTable instance that generates the table.

  • indent – String added to the beginning of each line in the text table.

Returns:

The text table as a single string.

Raises:

MonoTableCellError –

monotable.monocol(column_tuples: Sequence[Tuple[str, str, Sequence[Any]]] = (), title: str = '', *, bordered: bool = False, format_func_map: Mapping[str, Callable[[Any, str], str]] | None = None, guideline_chars: str = '---', indent: str = '') → str

Generate ASCII table from column tuples.

Parameters:

  • column_tuples –

    List of tuple of (heading string, format string, iterable of cell objects).

    The heading string syntax is described here table() under the parameter headings. The column tuple has a single heading string.

    The format directive string syntax is described here Format directive string syntax. The column tuple has a single format string.

    Iterable of cell objects represent the cells in the column.

  • title – [align_spec][wrap_spec]string. Text to be aligned and printed above the text table. Please see Title string syntax.

Keyword Arguments:

  • bordered – True means generate table with ASCII cell border characters.

  • format_func_map –

    Dictionary of format functions keyed by name. name, when used as a format directive in a format string, selects the corresponding function from the dictionary.

    If a key is one of the included format directive function names like ‘boolean’, ‘mformat’, etc. the included format directive function is hidden.

    This value overrides format_func_map in the MonoTable instance that generates the table.

  • guideline_chars – String of 0 to 3 characters to specify top, heading, and bottom guideline appearance. This value overrides guideline_chars in the MonoTable instance that generates the table.

  • indent – String added to the beginning of each line in the text table.

Returns:

The text table as a single string.

Raises:

MonoTableCellError –

monotable.join_strings(multi_line_strings: List[str], *, title: str = '', rsep: str = '    ', valign: int = 10) → str

Join side-by-side multi-line strings preserving vertical alignment.

Parameters:

multi_line_strings – List of strings.

Keyword Arguments:

  • title – Text to be aligned and printed above the joined strings. Please see Title string syntax.

  • rsep – Text placed between each line of the multi-line strings on the right hand side. It is not applied to the right-most multi-line string.

  • valign – Alignment used for vertical justification of multi-line strings when the number of lines in the strings differ. Callers should use one of TOP, CENTER_TOP, CENTER_BOTTOM, or BOTTOM defined in monotable.alignment.

Dataclass to ASCII Table

monotable.datacls.dataclass_print(dataclass_instance: Any, *, max_depth: int | None = None, formats: Tuple[str, str] = ('', '>'), title: str = '', **monotable_kwargs: Any) → None

Print the dataclass in table form in two columns: name, value.

Dataclass field values are converted to strings and right justified.

Dataclass members with these field metadata keys have special meaning: “help”: The value is printed after the member name in the name column.

“spec”: The string value becomes a string format spec for the value. It is used in a replacement field in an f-string format string.

“spec”: If a callable, the function is called with the value. The string returned is printed in the value column.

If a field value is a dataclass that has metadata “spec” that is a callable, the function is called to format the value.

If a field value is a dataclass with no metadata “spec” (or metadata spec that is not callable) a new table is printed below the current one. Its title will have a dotted field name. Any given id(dataclass_instance) will only be printed once. The value “…” indicates not printing an already printed dataclass. This breaks a possible circular reference cycle.

Parameters:

dataclass_instance

Keyword Arguments:

  • max_depth – Print nested dataclasses this many levels deep. None means print all nested dataclasses.

  • formats – Described by the same named monotable.mono() positional arg.

  • title – String prepended to the classname in the title. Described by the same named monotable.mono() positional arg.

  • monotable_kwargs – These args are passed through to monotable.mono().

monotable.datacls.dataclass_format(dataclass_instance: Any, *, max_depth: int | None = None, formats: Tuple[str, str] = ('', '>'), title: str = '', **monotable_kwargs: Any) → str

Format a dataclass in table form in two columns: name, value. See dataclassprint() above for details.

Parameters:

dataclass_instance

Keyword Arguments:

  • max_depth – Print nested dataclasses this many levels deep. None means print all nested dataclasses.

  • formats – Described by the same named monotable.mono() positional arg.

  • title – String prepended to the classname in the title. Described by the same named monotable.mono() positional arg.

  • monotable_kwargs – These args are passed through to monotable.mono().

Returns:

The text table as a single string.

monotable.datacls.stow(**kwargs: Any) → Dict[str, Any]

Return dict to assign to a dataclass field metadata.

Keyword Arguments:

  • spec – The string value becomes a string format spec for the value. If a callable, the function is called with the value.

  • help – The value is printed after the member name in the name column.

Returns:

A dict with key “monotable” whose value is a dict contains the stow() keyword args.

Legacy Functions

Since v2.1.0 these functions are superseded by mono() and monocol() above. The details of the function parameters are provided in the class MonoTable docstrings located by following the links below.

monotable.table.table(headings: Iterable[str] = (), formats: Iterable[str] = (), cellgrid: Iterable[Iterable[Any]] = ((),), title: str = '') → str

Wrapper to monotable.table.MonoTable.table().

monotable.table.bordered_table(headings: Iterable[str] = (), formats: Iterable[str] = (), cellgrid: Iterable[Iterable[Any]] = ((),), title: str = '') → str

Wrapper to monotable.table.MonoTable.bordered_table().

monotable.table.cotable(column_tuples: Sequence[Tuple[str, str, Sequence[Any]]] = (), title: str = '') → str

Wrapper to monotable.table.MonoTable.cotable().

monotable.table.cobordered_table(column_tuples: Sequence[Tuple[str, str, Sequence[Any]]] = (), title: str = '') → str

Wrapper to monotable.table.MonoTable.cobordered_table().

Note

The prefix co in cotable and cobordered_table stands for column oriented.