cmd2.table_creator

class cmd2.table_creator.HorizontalAlignment

Horizontal alignment of text in a cell

CENTER = 2
LEFT = 1
RIGHT = 3
class cmd2.table_creator.VerticalAlignment

Vertical alignment of text in a cell

BOTTOM = 3
MIDDLE = 2
TOP = 1
class cmd2.table_creator.Column(header: str, *, width: Optional[int] = None, header_horiz_align: cmd2.table_creator.HorizontalAlignment = <HorizontalAlignment.LEFT: 1>, header_vert_align: cmd2.table_creator.VerticalAlignment = <VerticalAlignment.BOTTOM: 3>, style_header_text: bool = True, data_horiz_align: cmd2.table_creator.HorizontalAlignment = <HorizontalAlignment.LEFT: 1>, data_vert_align: cmd2.table_creator.VerticalAlignment = <VerticalAlignment.TOP: 1>, style_data_text: bool = True, max_data_lines: Union[int, float] = inf)

Table column configuration

__init__(header: str, *, width: Optional[int] = None, header_horiz_align: cmd2.table_creator.HorizontalAlignment = <HorizontalAlignment.LEFT: 1>, header_vert_align: cmd2.table_creator.VerticalAlignment = <VerticalAlignment.BOTTOM: 3>, style_header_text: bool = True, data_horiz_align: cmd2.table_creator.HorizontalAlignment = <HorizontalAlignment.LEFT: 1>, data_vert_align: cmd2.table_creator.VerticalAlignment = <VerticalAlignment.TOP: 1>, style_data_text: bool = True, max_data_lines: Union[int, float] = inf) → None

Column initializer

Parameters:
  • header – label for column header
  • width – display width of column. This does not account for any borders or padding which may be added (e.g pre_line, inter_cell, and post_line). Header and data text wrap within this width using word-based wrapping (defaults to actual width of header or 1 if header is blank)
  • header_horiz_align – horizontal alignment of header cells (defaults to left)
  • header_vert_align – vertical alignment of header cells (defaults to bottom)
  • style_header_text – if True, then the table is allowed to apply styles to the header text, which may conflict with any styles the header already has. If False, the header is printed as is. Table classes which apply style to headers must account for the value of this flag. (defaults to True)
  • data_horiz_align – horizontal alignment of data cells (defaults to left)
  • data_vert_align – vertical alignment of data cells (defaults to top)
  • style_data_text – if True, then the table is allowed to apply styles to the data text, which may conflict with any styles the data already has. If False, the data is printed as is. Table classes which apply style to data must account for the value of this flag. (defaults to True)
  • max_data_lines – maximum lines allowed in a data cell. If line count exceeds this, then the final line displayed will be truncated with an ellipsis. (defaults to INFINITY)
Raises:

ValueError if width is less than 1

Raises:

ValueError if max_data_lines is less than 1

class cmd2.table_creator.TableCreator(cols: Sequence[cmd2.table_creator.Column], *, tab_width: int = 4)

Base table creation class. This class handles ANSI style sequences and characters with display widths greater than 1 when performing width calculations. It was designed with the ability to build tables one row at a time. This helps when you have large data sets that you don’t want to hold in memory or when you receive portions of the data set incrementally.

TableCreator has one public method: generate_row()

This function and the Column class provide all features needed to build tables with headers, borders, colors, horizontal and vertical alignment, and wrapped text. However, it’s generally easier to inherit from this class and implement a more granular API rather than use TableCreator directly. There are ready-to-use examples of this defined after this class.

__init__(cols: Sequence[cmd2.table_creator.Column], *, tab_width: int = 4) → None

TableCreator initializer

Parameters:
  • cols – column definitions for this table
  • tab_width – all tabs will be replaced with this many spaces. If a row’s fill_char is a tab, then it will be converted to one space.
Raises:

ValueError if tab_width is less than 1

generate_row(row_data: Sequence[Any], is_header: bool, *, fill_char: str = ' ', pre_line: str = '', inter_cell: str = ' ', post_line: str = '') → str

Generate a header or data table row

Parameters:
  • row_data – data with an entry for each column in the row
  • is_header – True if writing a header cell, otherwise writing a data cell. This determines whether to use header or data alignment settings as well as maximum lines to wrap.
  • fill_char – character that fills remaining space in a cell. Defaults to space. If this is a tab, then it will be converted to one space. (Cannot be a line breaking character)
  • pre_line – string to print before each line of a row. This can be used for a left row border and padding before the first cell’s text. (Defaults to blank)
  • inter_cell – string to print where two cells meet. This can be used for a border between cells and padding between it and the 2 cells’ text. (Defaults to 2 spaces)
  • post_line – string to print after each line of a row. This can be used for padding after the last cell’s text and a right row border. (Defaults to blank)
Returns:

row string

Raises:

ValueError if row_data isn’t the same length as self.cols

Raises:

TypeError if fill_char is more than one character (not including ANSI style sequences)

Raises:

ValueError if fill_char, pre_line, inter_cell, or post_line contains an unprintable character like a newline

class cmd2.table_creator.SimpleTable(cols: Sequence[cmd2.table_creator.Column], *, column_spacing: int = 2, tab_width: int = 4, divider_char: Optional[str] = '-', header_bg: Optional[cmd2.ansi.BgColor] = None, data_bg: Optional[cmd2.ansi.BgColor] = None)

Implementation of TableCreator which generates a borderless table with an optional divider row after the header. This class can be used to create the whole table at once or one row at a time.

__init__(cols: Sequence[cmd2.table_creator.Column], *, column_spacing: int = 2, tab_width: int = 4, divider_char: Optional[str] = '-', header_bg: Optional[cmd2.ansi.BgColor] = None, data_bg: Optional[cmd2.ansi.BgColor] = None) → None

SimpleTable initializer

Parameters:
  • cols – column definitions for this table
  • column_spacing – how many spaces to place between columns. Defaults to 2.
  • tab_width – all tabs will be replaced with this many spaces. If a row’s fill_char is a tab, then it will be converted to one space.
  • divider_char – optional character used to build the header divider row. Set this to blank or None if you don’t want a divider row. Defaults to dash. (Cannot be a line breaking character)
  • header_bg – optional background color for header cells (defaults to None)
  • data_bg – optional background color for data cells (defaults to None)
Raises:

ValueError if tab_width is less than 1

Raises:

ValueError if column_spacing is less than 0

Raises:

TypeError if divider_char is longer than one character

Raises:

ValueError if divider_char is an unprintable character

apply_data_bg(value: Any) → str

If defined, apply the data background color to data text :param value: object whose text is to be colored :return: formatted data string

apply_header_bg(value: Any) → str

If defined, apply the header background color to header text :param value: object whose text is to be colored :return: formatted text

classmethod base_width(num_cols: int, *, column_spacing: int = 2) → int

Utility method to calculate the display width required for a table before data is added to it. This is useful when determining how wide to make your columns to have a table be a specific width.

Parameters:
  • num_cols – how many columns the table will have
  • column_spacing – how many spaces to place between columns. Defaults to 2.
Returns:

base width

Raises:

ValueError if column_spacing is less than 0

Raises:

ValueError if num_cols is less than 1

generate_data_row(row_data: Sequence[Any]) → str

Generate a data row

Parameters:row_data – data with an entry for each column in the row
Returns:data row string
Raises:ValueError if row_data isn’t the same length as self.cols
generate_divider() → str

Generate divider row

generate_header() → str

Generate table header with an optional divider row

generate_table(table_data: Sequence[Sequence[Any]], *, include_header: bool = True, row_spacing: int = 1) → str

Generate a table from a data set

Parameters:
  • table_data – Data with an entry for each data row of the table. Each entry should have data for each column in the row.
  • include_header – If True, then a header will be included at top of table. (Defaults to True)
  • row_spacing – A number 0 or greater specifying how many blank lines to place between each row (Defaults to 1)
Raises:

ValueError if row_spacing is less than 0

total_width() → int

Calculate the total display width of this table

class cmd2.table_creator.BorderedTable(cols: Sequence[cmd2.table_creator.Column], *, tab_width: int = 4, column_borders: bool = True, padding: int = 1, border_fg: Optional[cmd2.ansi.FgColor] = None, border_bg: Optional[cmd2.ansi.BgColor] = None, header_bg: Optional[cmd2.ansi.BgColor] = None, data_bg: Optional[cmd2.ansi.BgColor] = None)

Implementation of TableCreator which generates a table with borders around the table and between rows. Borders between columns can also be toggled. This class can be used to create the whole table at once or one row at a time.

__init__(cols: Sequence[cmd2.table_creator.Column], *, tab_width: int = 4, column_borders: bool = True, padding: int = 1, border_fg: Optional[cmd2.ansi.FgColor] = None, border_bg: Optional[cmd2.ansi.BgColor] = None, header_bg: Optional[cmd2.ansi.BgColor] = None, data_bg: Optional[cmd2.ansi.BgColor] = None) → None

BorderedTable initializer

Parameters:
  • cols – column definitions for this table
  • tab_width – all tabs will be replaced with this many spaces. If a row’s fill_char is a tab, then it will be converted to one space.
  • column_borders – if True, borders between columns will be included. This gives the table a grid-like appearance. Turning off column borders results in a unified appearance between a row’s cells. (Defaults to True)
  • padding – number of spaces between text and left/right borders of cell
  • border_fg – optional foreground color for borders (defaults to None)
  • border_bg – optional background color for borders (defaults to None)
  • header_bg – optional background color for header cells (defaults to None)
  • data_bg – optional background color for data cells (defaults to None)
Raises:

ValueError if tab_width is less than 1

Raises:

ValueError if padding is less than 0

apply_border_color(value: Any) → str

If defined, apply the border foreground and background colors :param value: object whose text is to be colored :return: formatted text

apply_data_bg(value: Any) → str

If defined, apply the data background color to data text :param value: object whose text is to be colored :return: formatted data string

apply_header_bg(value: Any) → str

If defined, apply the header background color to header text :param value: object whose text is to be colored :return: formatted text

classmethod base_width(num_cols: int, *, column_borders: bool = True, padding: int = 1) → int

Utility method to calculate the display width required for a table before data is added to it. This is useful when determining how wide to make your columns to have a table be a specific width.

Parameters:
  • num_cols – how many columns the table will have
  • column_borders – if True, borders between columns will be included in the calculation (Defaults to True)
  • padding – number of spaces between text and left/right borders of cell
Returns:

base width

Raises:

ValueError if num_cols is less than 1

generate_data_row(row_data: Sequence[Any]) → str

Generate a data row

Parameters:row_data – data with an entry for each column in the row
Returns:data row string
Raises:ValueError if row_data isn’t the same length as self.cols
generate_header() → str

Generate table header

generate_header_bottom_border() → str

Generate a border which appears at the bottom of the header

generate_row_bottom_border() → str

Generate a border which appears at the bottom of rows

generate_table(table_data: Sequence[Sequence[Any]], *, include_header: bool = True) → str

Generate a table from a data set

Parameters:
  • table_data – Data with an entry for each data row of the table. Each entry should have data for each column in the row.
  • include_header – If True, then a header will be included at top of table. (Defaults to True)
generate_table_bottom_border() → str

Generate a border which appears at the bottom of the table

generate_table_top_border() → str

Generate a border which appears at the top of the header and data section

total_width() → int

Calculate the total display width of this table

class cmd2.table_creator.AlternatingTable(cols: Sequence[cmd2.table_creator.Column], *, tab_width: int = 4, column_borders: bool = True, padding: int = 1, border_fg: Optional[cmd2.ansi.FgColor] = None, border_bg: Optional[cmd2.ansi.BgColor] = None, header_bg: Optional[cmd2.ansi.BgColor] = None, odd_bg: Optional[cmd2.ansi.BgColor] = None, even_bg: Optional[cmd2.ansi.BgColor] = <Bg.DARK_GRAY: 100>)

Implementation of BorderedTable which uses background colors to distinguish between rows instead of row border lines. This class can be used to create the whole table at once or one row at a time.

To nest an AlternatingTable within another AlternatingTable, set style_data_text to False on the Column which contains the nested table. That will prevent the current row’s background color from affecting the colors of the nested table.

__init__(cols: Sequence[cmd2.table_creator.Column], *, tab_width: int = 4, column_borders: bool = True, padding: int = 1, border_fg: Optional[cmd2.ansi.FgColor] = None, border_bg: Optional[cmd2.ansi.BgColor] = None, header_bg: Optional[cmd2.ansi.BgColor] = None, odd_bg: Optional[cmd2.ansi.BgColor] = None, even_bg: Optional[cmd2.ansi.BgColor] = <Bg.DARK_GRAY: 100>) → None

AlternatingTable initializer

Note: Specify background colors using subclasses of BgColor (e.g. Bg, EightBitBg, RgbBg)

Parameters:
  • cols – column definitions for this table
  • tab_width – all tabs will be replaced with this many spaces. If a row’s fill_char is a tab, then it will be converted to one space.
  • column_borders – if True, borders between columns will be included. This gives the table a grid-like appearance. Turning off column borders results in a unified appearance between a row’s cells. (Defaults to True)
  • padding – number of spaces between text and left/right borders of cell
  • border_fg – optional foreground color for borders (defaults to None)
  • border_bg – optional background color for borders (defaults to None)
  • header_bg – optional background color for header cells (defaults to None)
  • odd_bg – optional background color for odd numbered data rows (defaults to None)
  • even_bg – optional background color for even numbered data rows (defaults to StdBg.DARK_GRAY)
Raises:

ValueError if tab_width is less than 1

Raises:

ValueError if padding is less than 0

apply_data_bg(value: Any) → str

Apply background color to data text based on what row is being generated and whether a color has been defined :param value: object whose text is to be colored :return: formatted data string

generate_data_row(row_data: Sequence[Any]) → str

Generate a data row

Parameters:row_data – data with an entry for each column in the row
Returns:data row string
generate_table(table_data: Sequence[Sequence[Any]], *, include_header: bool = True) → str

Generate a table from a data set

Parameters:
  • table_data – Data with an entry for each data row of the table. Each entry should have data for each column in the row.
  • include_header – If True, then a header will be included at top of table. (Defaults to True)