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>, 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 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.
-
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], *, 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], *, tab_width: int = 4, divider_char: Optional[str] = '-') → None¶ SimpleTable 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.
- 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: TypeError if fill_char is more than one character (not including ANSI style sequences)
Raises: ValueError if text or fill_char contains an unprintable character
-
classmethod
base_width
(num_cols: int) → 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 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
-
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)¶ 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
-
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_header
() → str¶ Generate table header
-
generate_header_bottom_border
()¶ Generate a border which appears at the bottom of the header
-
generate_row_bottom_border
()¶ 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
()¶ Generate a border which appears at the bottom of the table
-
generate_table_top_border
()¶ 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, 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)
-