Class MonoTable

Links:

__init__() table() bordered_table() row_strings() cotable() cobordered_table() Title string syntax, Format directive string syntax, Format directives, Auto-alignment

class monotable.table.MonoTable(indent='')

Create an aligned and formatted text table from a grid of cells.

Call table() passing a sequence of heading strings, a sequence of format strings, a sequence of sequence of cells, and a title string. The return value is a string ready for printing.

Call cotable() passing a sequence of tuples of (heading, format, list of cells in the column); one tuple for each column; and a title string. The prefix co stands for column oriented.

Call bordered_table() with the same arguments as table() to format a table with character borders.

Call cobordered_table() with the same arguments as cotable() to format a table with character borders.

Call row_strings() passing a sequence of heading strings, a sequence of format strings, a sequence of sequence of cells to return a tuple of lists of formatted headings and list of list of cells.

Heading strings, title strings, and formatted cells may contain newlines.

Cells that inherit from numbers.Number are Auto-Aligned to the right and all other cell types are auto aligned to the left.

Definitions:

Align_spec:One of the characters ‘<’, ‘^’, ‘>’. The characters indicate left, center, and right justification. To configure, override the class variable align_spec_chars. Heading String:[align_spec]string Format String:[align_spec][directives][format_spec] Title String:[align_spec][wrap_spec]string

• The format directive string syntax is described by the table() argument formats below.

Auto-alignment:

• Heading alignment is determined by this decision order:

  1. align_spec if present in the heading string.
  2. align_spec if present in the format string.
  3. Auto-Alignment for the cell in the first row.

• Cell alignment is determined by this decision order:

  1. align_spec if present in the format string.
  2. Auto-Alignment for the cell.

• The title is auto-aligned to center.

Note:The align_spec prefix may be omitted, but is required if the rest of the string starts with one of the align_spec_chars. Or the user can put in an empty directives for example ‘()’. Note:align_spec scanning/parsing can be disabled by setting the class variable align_spec_chars to the empty string.

There is one format string for each column of cells.

Formatting, by default, is done by <built-in function format>.

• The user can specify a different default format function for the table by overriding the class variable format_func.
• In directives the user can specify a format function for a column which takes precedence over the table default format function. They are listed here: Format directives.
• Any user defined function in the dict assigned to the class variable format_func_map may be selected by putting its key as a formatting directive.

Here is the data flow through the formatting engine:

                    text              MonoBlock
cell -> format_func ---> (parentheses) ------> width control,
        format_spec      (zero=)          |    justification
                                          |      (width=)
cell is None ------------(none=)----------+      (max)
                                                 (wrap)
                                                 (fixed)

* format directives are shown enclosed by ().
* format_func may be selected by a format function directive.
* user can plug in new format function directives.

• If cell is None an empty string is formatted. Configure for a column by using the none= format directive in directives. Configure for the whole table by overriding class variable format_none_as.
• If a cell is type float, and format_spec is an empty string, and the format function is <built-in function format>, the cell is formatted using class variable default_float_format_spec.

directives can contain the format directives lsep= and rsep= which sets the separator string placed before/after the column.

If wrap_spec_char is present in table title the title is text wrapped to the width of the table. To change the wrap_spec_char or disable wrap_spec_char scanning, see the class variable wrap_spec_char. Title is auto-aligned to center by default.

A format error produces an exception object which identifies the offending cell. Format error handling is configurable by overriding class variable format_exc_callback.

All the class variables can be overridden in ether a subclass or on an instance. For the complete list please see section MonoTable Class Variables.

MonoTable.__init__(indent='')

Parameters:indent (str) – String added to the beginning of each line in the text table.

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

Format printable text table. It is pretty in monospaced font.

Parameters:

• headings – Iterable of strings for each column heading.
• formats – Iterable of format strings of the form [align_spec][directives][format_spec]. Format directive string syntax
• cellgrid – representing table cells.
• title – [align_spec][wrap_spec]string. Text to be aligned and printed above the text table. Title string syntax

Returns:

The text table as a single string.

Raises:

MonoTableCellError

Here is an example of non-bordered text table:

Int, Float, String                        <-- title
--------------------------------------    <-- top guideline
      Int        Float  String            <-- heading row
--------------------------------------    <-- heading guideline
123456789     3.141593  Hello World       <-- cell row
        2  2718.281828  another string    <-- cell row
--------------------------------------    <-- bottom guideline

         ^^           ^^
          |            |
       sep/rsep     sep/rsep

This example has 6 sep strings of 2 spaces each. The seps are placed between columns in the heading line and between the columns in each of the 2 cell rows.

Title string syntax:

[align_spec][wrap_spec]string

align_spec

One of the characters ‘<’, ‘^’, ‘>’ to override auto-alignment.

wrap_spec

Character ‘=’ to indicate the title should be text wrapped to the width of the table.

Format directive string syntax:

[align_spec][directives][format_spec].

align_spec

One of the characters ‘<’, ‘^’, ‘>’ to override auto-alignment.

directives

One or more of format directives enclosed by ‘(‘ and ‘)’ separated by ‘;’.

format_spec

String passed to the format function.

Format directives:

The format string directives described here apply to all MonoTable methods and monotable convenience functions that take format strings.

• At most, one format function directive is allowed.
• Each directive is allowed once.
• Spacing before ‘=’ is always ignored.
• Spacing after ‘=’ is significant for none, zero, lsep, and rsep.

width=N

Truncate each formatted cell text line(s) to width N and insert the class variable more_marker if text was omitted.

fixed

Used with width=N formats text to exactly width = N columns.

wrap

Used with width=N does textwrap of formatted cell to width = N.

lsep=ccc

Characters after ‘lsep=’ are the column separator on the left hand side of the column. Use lsep with care because it will silently overwrite the rsep specified for the column to the left. It has no effect if specified on the left-most column.

rsep=ccc

Characters after ‘rsep=’ are the column separator on the right hand side of the column. It has no effect if specified on the right-most column.

sep=ccc

Same as rsep. sep is an alias for rsep since version 2.1.0. New code should use rsep=ccc since the meaning is more explicit.

Format function directives:

boolean

Convert boolean cell truth value to one of two strings supplied by the format_spec. Implemented by monotable.plugin.boolean()

none=ccc

Specifies the formatted text for None cell value.

zero=ccc

For cells that are numbers, when all digits in formatted text are zero replace the formatted text with ccc. 0.00e00 -> ccc.

parentheses

For cells that are numbers, when formatted text starts with a minus sign, remove the minus sign and add enclosing parentheses. -100.1 -> (100.1). Maintains alignment with numbers not enclosed by parentheses.

thousands

Select format function that divides by 10.0e3 before applying the format_spec. monotable.plugin.thousands()

millions

Select format function that divides by 10.0e6 before applying the format_spec. monotable.plugin.millions()

billions

Select format function that divides by 10.0e9 before applying the format_spec. monotable.plugin.billions()

trillions

Select format function that divides by 10.0e12 before applying the format_spec. monotable.plugin.trillions()

milli

Select format function that multiplies by 10.0e3 before applying the format_spec. monotable.plugin.milli()

micro

Select format function that multiplies by 10.0e6 before applying the format_spec. monotable.plugin.micro()

nano

Select format function that multiplies by 10.0e9 tbefore applying the format_spec. monotable.plugin.nano()

pico

Select format function that multiplies by 10.0e12 before applying the format_spec. monotable.plugin.pico()

kibi

Select format function that divides by 1024 before applying the format_spec. monotable.plugin.kibi()

mebi

Select format function that divides by 1024^2 before applying the format_spec. monotable.plugin.mebi()

gibi

Select format function that divides by 1024^3 before applying the format_spec. monotable.plugin.gibi()

tebi

Select format function that divides by 1024^4 before applying the format_spec. monotable.plugin.tebi()

mformat

Select format function that selects values from a dictionary. monotable.plugin.mformat()

pformat

Select format function adapter to percent operator %. monotable.plugin.pformat()

sformat

Select format function adapter to str.format(). monotable.plugin.sformat()

tformat

Select format function adapter to string.Template.substitute(). monotable.plugin.tformat()

function-name

Select format function with key function-name in the dictionary supplied by class variable format_func_map.

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

Format printable text table with individual cell borders.

Parameters:

• headings – Iterable of strings for each column heading.
• formats – Iterable of format strings of the form [align_spec][directives][format_spec]. Format directive string syntax
• cellgrid – representing table cells.
• title – [align_spec][wrap_spec]string. Text to be aligned and printed above the text table. Title string syntax

Returns:

The text table as a single string.

Raises:

MonoTableCellError

Here is an example of bordered text table:

+----------------------+------------------+  <-- top guideline
| format string        | format string    |  <-- heading row
| "%Y-%m-%d--%I:%M:%S" | "week-%U-day-%j" |
+======================+==================+  <-- heading guideline
| 2016-01-10--07:35:18 | week-02-day-010  |  <-- cell row
+----------------------+------------------+  <-- bottom guideline

MonoTable.row_strings(headings: Iterable[str] = (), formats: Iterable[str] = (), cellgrid: Iterable[Iterable[Any]] = ((), ), strip: bool = False) → List[List[str]]

Format and justify table. Return rows of the strings.

Parameters:

• headings – Iterable of strings for each column heading.
• formats – Iterable of format strings of the form [align_spec][directives][format_spec]. Format directive string syntax
• cellgrid – representing table cells.
• strip – If True remove leading and trailing spaces.

Returns:

First row is headings, following rows are formatted cell strings.

Return type:

list of rows of string

Raises:

MonoTableCellError

When strip=False, each heading and all cells in each column are justified and are the same length.

MonoTable.cotable(column_tuples: Sequence[Tuple[str, str, Sequence[T_co]]] = (), title: str = '') → str

Format printable text table from tuples describing columns.

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 table() under the parameter formats. 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. Title string syntax

Returns:

The text table as a single string.

Raises:

MonoTableCellError

MonoTable.cobordered_table(column_tuples: Sequence[Tuple[str, str, Sequence[T_co]]] = (), title: str = '') → str

Format printable bordered text table from tuples describing columns.

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 table() under the parameter formats. 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. Title string syntax

Returns:

The text table as a single string.

Raises:

MonoTableCellError