cmd2.table_creator
cmd2.table_creator
cmd2 table creation API This API is built upon two core classes: Column and TableCreator The general use case is to inherit from TableCreator to create a table class with custom formatting options. There are already implemented and ready-to-use examples of this below TableCreator's code.
HorizontalAlignment
VerticalAlignment
Column
Column(header, *, width=None, header_horiz_align=LEFT, header_vert_align=BOTTOM, style_header_text=True, data_horiz_align=LEFT, data_vert_align=TOP, style_data_text=True, max_data_lines=INFINITY)
Table column configuration
Column initializer
PARAMETER | DESCRIPTION |
---|---|
header
|
label for column header
TYPE:
|
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)
TYPE:
|
header_horiz_align
|
horizontal alignment of header cells (defaults to left)
TYPE:
|
header_vert_align
|
vertical alignment of header cells (defaults to bottom)
TYPE:
|
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)
TYPE:
|
data_horiz_align
|
horizontal alignment of data cells (defaults to left)
TYPE:
|
data_vert_align
|
vertical alignment of data cells (defaults to top)
TYPE:
|
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)
TYPE:
|
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)
TYPE:
|
RAISES | DESCRIPTION |
---|---|
ValueError
|
if width is less than 1 |
ValueError
|
if max_data_lines is less than 1 |
Source code in cmd2/table_creator.py
TableCreator
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.
TableCreator initializer
PARAMETER | DESCRIPTION |
---|---|
cols
|
column definitions for this table
TYPE:
|
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.
TYPE:
|
RAISES | DESCRIPTION |
---|---|
ValueError
|
if tab_width is less than 1 |
Source code in cmd2/table_creator.py
generate_row
generate_row(row_data, is_header, *, fill_char=SPACE, pre_line=EMPTY, inter_cell=2 * SPACE, post_line=EMPTY)
Generate a header or data table row
PARAMETER | DESCRIPTION |
---|---|
row_data
|
data with an entry for each column in the row
TYPE:
|
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.
TYPE:
|
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)
TYPE:
|
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)
TYPE:
|
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)
TYPE:
|
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)
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
str
|
row string |
RAISES | DESCRIPTION |
---|---|
ValueError
|
if row_data isn't the same length as self.cols |
TypeError
|
if fill_char is more than one character (not including ANSI style sequences) |
ValueError
|
if fill_char, pre_line, inter_cell, or post_line contains an unprintable character like a newline |
Source code in cmd2/table_creator.py
421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 |
|
SimpleTable
Bases: TableCreator
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.
SimpleTable initializer
PARAMETER | DESCRIPTION |
---|---|
cols
|
column definitions for this table
TYPE:
|
column_spacing
|
how many spaces to place between columns. Defaults to 2.
TYPE:
|
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.
TYPE:
|
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)
TYPE:
|
header_bg
|
optional background color for header cells (defaults to None)
TYPE:
|
data_bg
|
optional background color for data cells (defaults to None)
TYPE:
|
RAISES | DESCRIPTION |
---|---|
ValueError
|
if tab_width is less than 1 |
ValueError
|
if column_spacing is less than 0 |
TypeError
|
if divider_char is longer than one character |
ValueError
|
if divider_char is an unprintable character |
Source code in cmd2/table_creator.py
generate_row
generate_row(row_data, is_header, *, fill_char=SPACE, pre_line=EMPTY, inter_cell=2 * SPACE, post_line=EMPTY)
Generate a header or data table row
PARAMETER | DESCRIPTION |
---|---|
row_data
|
data with an entry for each column in the row
TYPE:
|
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.
TYPE:
|
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)
TYPE:
|
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)
TYPE:
|
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)
TYPE:
|
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)
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
str
|
row string |
RAISES | DESCRIPTION |
---|---|
ValueError
|
if row_data isn't the same length as self.cols |
TypeError
|
if fill_char is more than one character (not including ANSI style sequences) |
ValueError
|
if fill_char, pre_line, inter_cell, or post_line contains an unprintable character like a newline |
Source code in cmd2/table_creator.py
421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 |
|
apply_header_bg
If defined, apply the header background color to header text
PARAMETER | DESCRIPTION |
---|---|
value
|
object whose text is to be colored
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
str
|
formatted text |
Source code in cmd2/table_creator.py
apply_data_bg
If defined, apply the data background color to data text
PARAMETER | DESCRIPTION |
---|---|
value
|
object whose text is to be colored
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
str
|
formatted data string |
Source code in cmd2/table_creator.py
base_width
classmethod
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.
PARAMETER | DESCRIPTION |
---|---|
num_cols
|
how many columns the table will have
TYPE:
|
column_spacing
|
how many spaces to place between columns. Defaults to 2.
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
int
|
base width |
RAISES | DESCRIPTION |
---|---|
ValueError
|
if column_spacing is less than 0 |
ValueError
|
if num_cols is less than 1 |
Source code in cmd2/table_creator.py
total_width
Calculate the total display width of this table
Source code in cmd2/table_creator.py
generate_header
Generate table header with an optional divider row
Source code in cmd2/table_creator.py
generate_divider
generate_data_row
Generate a data row
PARAMETER | DESCRIPTION |
---|---|
row_data
|
data with an entry for each column in the row
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
str
|
data row string |
RAISES | DESCRIPTION |
---|---|
ValueError
|
if row_data isn't the same length as self.cols |
Source code in cmd2/table_creator.py
generate_table
Generate a table from a data set
PARAMETER | DESCRIPTION |
---|---|
table_data
|
Data with an entry for each data row of the table. Each entry should have data for each column in the row.
TYPE:
|
include_header
|
If True, then a header will be included at top of table. (Defaults to True)
TYPE:
|
row_spacing
|
A number 0 or greater specifying how many blank lines to place between each row (Defaults to 1)
TYPE:
|
RAISES | DESCRIPTION |
---|---|
ValueError
|
if row_spacing is less than 0 |
Source code in cmd2/table_creator.py
BorderedTable
BorderedTable(cols, *, tab_width=4, column_borders=True, padding=1, border_fg=None, border_bg=None, header_bg=None, data_bg=None)
Bases: TableCreator
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.
BorderedTable initializer
PARAMETER | DESCRIPTION |
---|---|
cols
|
column definitions for this table
TYPE:
|
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.
TYPE:
|
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)
TYPE:
|
padding
|
number of spaces between text and left/right borders of cell
TYPE:
|
border_fg
|
optional foreground color for borders (defaults to None)
TYPE:
|
border_bg
|
optional background color for borders (defaults to None)
TYPE:
|
header_bg
|
optional background color for header cells (defaults to None)
TYPE:
|
data_bg
|
optional background color for data cells (defaults to None)
TYPE:
|
RAISES | DESCRIPTION |
---|---|
ValueError
|
if tab_width is less than 1 |
ValueError
|
if padding is less than 0 |
Source code in cmd2/table_creator.py
generate_row
generate_row(row_data, is_header, *, fill_char=SPACE, pre_line=EMPTY, inter_cell=2 * SPACE, post_line=EMPTY)
Generate a header or data table row
PARAMETER | DESCRIPTION |
---|---|
row_data
|
data with an entry for each column in the row
TYPE:
|
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.
TYPE:
|
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)
TYPE:
|
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)
TYPE:
|
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)
TYPE:
|
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)
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
str
|
row string |
RAISES | DESCRIPTION |
---|---|
ValueError
|
if row_data isn't the same length as self.cols |
TypeError
|
if fill_char is more than one character (not including ANSI style sequences) |
ValueError
|
if fill_char, pre_line, inter_cell, or post_line contains an unprintable character like a newline |
Source code in cmd2/table_creator.py
421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 |
|
apply_border_color
If defined, apply the border foreground and background colors
PARAMETER | DESCRIPTION |
---|---|
value
|
object whose text is to be colored
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
str
|
formatted text |
Source code in cmd2/table_creator.py
apply_header_bg
If defined, apply the header background color to header text
PARAMETER | DESCRIPTION |
---|---|
value
|
object whose text is to be colored
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
str
|
formatted text |
Source code in cmd2/table_creator.py
apply_data_bg
If defined, apply the data background color to data text
PARAMETER | DESCRIPTION |
---|---|
value
|
object whose text is to be colored
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
str
|
formatted data string |
Source code in cmd2/table_creator.py
base_width
classmethod
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.
PARAMETER | DESCRIPTION |
---|---|
num_cols
|
how many columns the table will have
TYPE:
|
column_borders
|
if True, borders between columns will be included in the calculation (Defaults to True)
TYPE:
|
padding
|
number of spaces between text and left/right borders of cell
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
int
|
base width |
RAISES | DESCRIPTION |
---|---|
ValueError
|
if num_cols is less than 1 |
Source code in cmd2/table_creator.py
total_width
Calculate the total display width of this table
Source code in cmd2/table_creator.py
generate_table_top_border
Generate a border which appears at the top of the header and data section
Source code in cmd2/table_creator.py
generate_header_bottom_border
Generate a border which appears at the bottom of the header
Source code in cmd2/table_creator.py
generate_row_bottom_border
Generate a border which appears at the bottom of rows
Source code in cmd2/table_creator.py
generate_table_bottom_border
Generate a border which appears at the bottom of the table
Source code in cmd2/table_creator.py
generate_header
Generate table header
Source code in cmd2/table_creator.py
generate_data_row
Generate a data row
PARAMETER | DESCRIPTION |
---|---|
row_data
|
data with an entry for each column in the row
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
str
|
data row string |
RAISES | DESCRIPTION |
---|---|
ValueError
|
if row_data isn't the same length as self.cols |
Source code in cmd2/table_creator.py
generate_table
Generate a table from a data set
PARAMETER | DESCRIPTION |
---|---|
table_data
|
Data with an entry for each data row of the table. Each entry should have data for each column in the row.
TYPE:
|
include_header
|
If True, then a header will be included at top of table. (Defaults to True)
TYPE:
|
Source code in cmd2/table_creator.py
AlternatingTable
AlternatingTable(cols, *, tab_width=4, column_borders=True, padding=1, border_fg=None, border_bg=None, header_bg=None, odd_bg=None, even_bg=DARK_GRAY)
Bases: BorderedTable
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.
AlternatingTable initializer
Note: Specify background colors using subclasses of BgColor (e.g. Bg, EightBitBg, RgbBg)
PARAMETER | DESCRIPTION |
---|---|
cols
|
column definitions for this table
TYPE:
|
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.
TYPE:
|
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)
TYPE:
|
padding
|
number of spaces between text and left/right borders of cell
TYPE:
|
border_fg
|
optional foreground color for borders (defaults to None)
TYPE:
|
border_bg
|
optional background color for borders (defaults to None)
TYPE:
|
header_bg
|
optional background color for header cells (defaults to None)
TYPE:
|
odd_bg
|
optional background color for odd numbered data rows (defaults to None)
TYPE:
|
even_bg
|
optional background color for even numbered data rows (defaults to StdBg.DARK_GRAY) |
RAISES | DESCRIPTION |
---|---|
ValueError
|
if tab_width is less than 1 |
ValueError
|
if padding is less than 0 |
Source code in cmd2/table_creator.py
generate_row
generate_row(row_data, is_header, *, fill_char=SPACE, pre_line=EMPTY, inter_cell=2 * SPACE, post_line=EMPTY)
Generate a header or data table row
PARAMETER | DESCRIPTION |
---|---|
row_data
|
data with an entry for each column in the row
TYPE:
|
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.
TYPE:
|
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)
TYPE:
|
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)
TYPE:
|
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)
TYPE:
|
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)
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
str
|
row string |
RAISES | DESCRIPTION |
---|---|
ValueError
|
if row_data isn't the same length as self.cols |
TypeError
|
if fill_char is more than one character (not including ANSI style sequences) |
ValueError
|
if fill_char, pre_line, inter_cell, or post_line contains an unprintable character like a newline |
Source code in cmd2/table_creator.py
421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 |
|
apply_border_color
If defined, apply the border foreground and background colors
PARAMETER | DESCRIPTION |
---|---|
value
|
object whose text is to be colored
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
str
|
formatted text |
Source code in cmd2/table_creator.py
apply_header_bg
If defined, apply the header background color to header text
PARAMETER | DESCRIPTION |
---|---|
value
|
object whose text is to be colored
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
str
|
formatted text |
Source code in cmd2/table_creator.py
base_width
classmethod
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.
PARAMETER | DESCRIPTION |
---|---|
num_cols
|
how many columns the table will have
TYPE:
|
column_borders
|
if True, borders between columns will be included in the calculation (Defaults to True)
TYPE:
|
padding
|
number of spaces between text and left/right borders of cell
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
int
|
base width |
RAISES | DESCRIPTION |
---|---|
ValueError
|
if num_cols is less than 1 |
Source code in cmd2/table_creator.py
total_width
Calculate the total display width of this table
Source code in cmd2/table_creator.py
generate_table_top_border
Generate a border which appears at the top of the header and data section
Source code in cmd2/table_creator.py
generate_header_bottom_border
Generate a border which appears at the bottom of the header
Source code in cmd2/table_creator.py
generate_row_bottom_border
Generate a border which appears at the bottom of rows
Source code in cmd2/table_creator.py
generate_table_bottom_border
Generate a border which appears at the bottom of the table
Source code in cmd2/table_creator.py
generate_header
Generate table header
Source code in cmd2/table_creator.py
apply_data_bg
Apply background color to data text based on what row is being generated and whether a color has been defined
PARAMETER | DESCRIPTION |
---|---|
value
|
object whose text is to be colored
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
str
|
formatted data string |
Source code in cmd2/table_creator.py
generate_data_row
Generate a data row
PARAMETER | DESCRIPTION |
---|---|
row_data
|
data with an entry for each column in the row
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
str
|
data row string |
Source code in cmd2/table_creator.py
generate_table
Generate a table from a data set
PARAMETER | DESCRIPTION |
---|---|
table_data
|
Data with an entry for each data row of the table. Each entry should have data for each column in the row.
TYPE:
|
include_header
|
If True, then a header will be included at top of table. (Defaults to True)
TYPE:
|