cmd2.table_creator¶
- class cmd2.table_creator.HorizontalAlignment(value)¶
Horizontal alignment of text in a cell
- LEFT = 1¶
- CENTER = 2¶
- RIGHT = 3¶
- class cmd2.table_creator.VerticalAlignment(value)¶
Vertical alignment of text in a cell
- TOP = 1¶
- MIDDLE = 2¶
- BOTTOM = 3¶
- 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>, data_horiz_align: cmd2.table_creator.HorizontalAlignment = <HorizontalAlignment.LEFT: 1>, data_vert_align: cmd2.table_creator.VerticalAlignment = <VerticalAlignment.TOP: 1>, 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>, data_horiz_align: cmd2.table_creator.HorizontalAlignment = <HorizontalAlignment.LEFT: 1>, data_vert_align: cmd2.table_creator.VerticalAlignment = <VerticalAlignment.TOP: 1>, 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)
data_horiz_align – horizontal alignment of data cells (defaults to left)
data_vert_align – vertical alignment of data cells (defaults to top)
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: Optional[Sequence[Any]] = None, fill_char: str = ' ', pre_line: str = '', inter_cell: str = ' ', post_line: str = '') → str¶
Generate a header or data table row
- Parameters
row_data – If this is None then a header row is generated. Otherwise data should have an entry for each column in the row. (Defaults to None)
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 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] = '-')¶
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] = '-') → 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 None if you don’t want a divider row. Defaults to dash. (Cannot be a line breaking character)
- Raises
ValueError if column_spacing is less than 0
- Raises
ValueError if tab_width is less than 1
- Raises
TypeError if divider_char is longer than one character
- Raises
ValueError if divider_char is an unprintable character
- 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
- total_width() → int¶
Calculate the total display width of this table
- generate_header() → str¶
Generate table header with an optional divider row
- 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, 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
- class cmd2.table_creator.BorderedTable(cols: Sequence[cmd2.table_creator.Column], *, tab_width: int = 4, column_borders: bool = True, padding: int = 1)¶
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) → 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
- Raises
ValueError if padding is less than 0
- 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
- total_width() → int¶
Calculate the total display width of this table
- generate_table_top_border() → str¶
Generate a border which appears at the top of the header and data section
- 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_bottom_border() → str¶
Generate a border which appears at the bottom of the table
- generate_header() → str¶
Generate table header
- 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)
- class cmd2.table_creator.AlternatingTable(cols: Sequence[cmd2.table_creator.Column], *, tab_width: int = 4, column_borders: bool = True, padding: int = 1, bg_odd: Optional[cmd2.ansi.bg] = None, bg_even: Optional[cmd2.ansi.bg] = <bg.bright_black: '\x1b[100m'>)¶
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.
- __init__(cols: Sequence[cmd2.table_creator.Column], *, tab_width: int = 4, column_borders: bool = True, padding: int = 1, bg_odd: Optional[cmd2.ansi.bg] = None, bg_even: Optional[cmd2.ansi.bg] = <bg.bright_black: '\x1b[100m'>) → None¶
AlternatingTable 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
bg_odd – optional background color for odd numbered rows (defaults to None)
bg_even – optional background color for even numbered rows (defaults to gray)
- Raises
ValueError if padding is less than 0
- 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)