evennia.utils.evtable

This is an advanced ASCII table creator. It was inspired by Prettytable (https://code.google.com/p/prettytable/) but shares no code and is considerably more advanced, supporting auto-balancing of incomplete tables and ANSI colors among other things.

Example usage:

from evennia.utils import evtable

table = evtable.EvTable("Heading1", "Heading2",
                table=[[1,2,3],[4,5,6],[7,8,9]], border="cells")
table.add_column("This is long data", "This is even longer data")
table.add_row("This is a single row")
print table

Result:

+----------------------+----------+---+--------------------------+
|       Heading1       | Heading2 |   |                          |
+~~~~~~~~~~~~~~~~~~~~~~+~~~~~~~~~~+~~~+~~~~~~~~~~~~~~~~~~~~~~~~~~+
|           1          |     4    | 7 |     This is long data    |
+----------------------+----------+---+--------------------------+
|           2          |     5    | 8 | This is even longer data |
+----------------------+----------+---+--------------------------+
|           3          |     6    | 9 |                          |
+----------------------+----------+---+--------------------------+
| This is a single row |          |   |                          |
+----------------------+----------+---+--------------------------+

As seen, the table will automatically expand with empty cells to make the table symmetric. Tables can be restricted to a given width:

table.reformat(width=50, align="l")

(We could just have added these keywords to the table creation call)

This yields the following result:

+-----------+------------+-----------+-----------+
| Heading1  | Heading2   |           |           |
+~~~~~~~~~~~+~~~~~~~~~~~~+~~~~~~~~~~~+~~~~~~~~~~~+
| 1         | 4          | 7         | This is   |
|           |            |           | long data |
+-----------+------------+-----------+-----------+
|           |            |           | This is   |
| 2         | 5          | 8         | even      |
|           |            |           | longer    |
|           |            |           | data      |
+-----------+------------+-----------+-----------+
| 3         | 6          | 9         |           |
+-----------+------------+-----------+-----------+
| This is a |            |           |           |
|  single   |            |           |           |
| row       |            |           |           |
+-----------+------------+-----------+-----------+

Table-columns can be individually formatted. Note that if an individual column is set with a specific width, table auto-balancing will not affect this column (this may lead to the full table being too wide, so be careful mixing fixed-width columns with auto- balancing). Here we change the width and alignment of the column at index 3 (Python starts from 0):

table.reformat_column(3, width=30, align="r")
print table

+-----------+-------+-----+-----------------------------+---------+
| Heading1  | Headi |     |                             |         |
|           | ng2   |     |                             |         |
+~~~~~~~~~~~+~~~~~~~+~~~~~+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~+~~~~~~~~~+
| 1         | 4     | 7   |           This is long data | Test1   |
+-----------+-------+-----+-----------------------------+---------+
| 2         | 5     | 8   |    This is even longer data | Test3   |
+-----------+-------+-----+-----------------------------+---------+
| 3         | 6     | 9   |                             | Test4   |
+-----------+-------+-----+-----------------------------+---------+
| This is a |       |     |                             |         |
|  single   |       |     |                             |         |
| row       |       |     |                             |         |
+-----------+-------+-----+-----------------------------+---------+

When adding new rows/columns their data can have its own alignments (left/center/right, top/center/bottom).

If the height is restricted, cells will be restricted from expanding vertically. This will lead to text contents being cropped. Each cell can only shrink to a minimum width and height of 1.

EvTable is intended to be used with ANSIString for supporting ANSI-coloured string types.

When a cell is auto-wrapped across multiple lines, ANSI-reset sequences will be put at the end of each wrapped line. This means that the colour of a wrapped cell will not “bleed”, but it also means that eventual colour outside the table will not transfer “across” a table, you need to re-set the color to have it appear on both sides of the table string.

class evennia.utils.evtable.ANSITextWrapper(width=70, initial_indent='', subsequent_indent='', expand_tabs=True, replace_whitespace=True, fix_sentence_endings=False, break_long_words=True, drop_whitespace=True, break_on_hyphens=True, tabsize=8, *, max_lines=None, placeholder=' [...]')[source]

Bases: textwrap.TextWrapper

This is a wrapper work class for handling strings with ANSI tags in it. It overloads the standard library TextWrapper class and is used internally in EvTable and has no public methods.

evennia.utils.evtable.wrap(text, width=78, **kwargs)[source]

Wrap a single paragraph of text, returning a list of wrapped lines.

Reformat the single paragraph in ‘text’ so it fits in lines of no more than ‘width’ columns, and return a list of wrapped lines. By default, tabs in ‘text’ are expanded with string.expandtabs(), and all other whitespace characters (including newline) are converted to

Parameters

  • text (str) – Text to wrap.

  • width (int, optional) – Width to wrap text to.

Keyword Arguments

  • TextWrapper class for available keyword args to customize (See) –

  • behaviour. (wrapping) –

evennia.utils.evtable.fill(text, width=78, **kwargs)[source]

Fill a single paragraph of text, returning a new string.

Reformat the single paragraph in ‘text’ to fit in lines of no more than ‘width’ columns, and return a new string containing the entire wrapped paragraph. As with wrap(), tabs are expanded and other whitespace characters converted to space.

Parameters

  • text (str) – Text to fill.

  • width (int, optional) – Width of fill area.

Keyword Arguments

  • TextWrapper class for available keyword args to customize (See) –

  • behaviour. (filling) –

class evennia.utils.evtable.EvCell(data, **kwargs)[source]

Bases: object

Holds a single data cell for the table. A cell has a certain width and height and contains one or more lines of data. It can shrink and resize as needed.

__init__(data, **kwargs)[source]
Parameters

data (str) – The un-padded data of the entry.

Keyword Arguments

  • width (int) – Desired width of cell. It will pad to this size.

  • height (int) – Desired height of cell. it will pad to this size.

  • pad_width (int) – General padding width. This can be overruled by individual settings below.

  • pad_left (int) – Number of extra pad characters on the left.

  • pad_right (int) – Number of extra pad characters on the right.

  • pad_top (int) – Number of extra pad lines top (will pad with vpad_char).

  • pad_bottom (int) – Number of extra pad lines bottom (will pad with vpad_char).

  • pad_char (str) – by individual settings below (default ” “).

  • hpad_char (str) – Pad character to use both for extra horizontal padding (default ” “).

  • vpad_char (str) – Pad character to use for extra vertical padding and for vertical fill (default ” “).

  • fill_char (str) – Character used to filling (expanding cells to desired size). This can be overruled by individual settings below.

  • hfill_char (str) – Character used for horizontal fill (default ” “).

  • vfill_char (str) – Character used for vertical fill (default ” “).

  • align (str) – Should be one of “l”, “r”, “c”, “f” or “a” for left-, right-, center-, full-justified (with space between words) or absolute (keep as much original whitespace as possible). Default is left-aligned.

  • valign (str) – Should be one of “t”, “b” or “c” for top-, bottom and center vertical alignment respectively. Default is centered.

  • border_width (int) – General border width. This is overruled by individual settings below.

  • border_left (int) – Left border width.

  • border_right (int) – Right border width.

  • border_top (int) – Top border width.

  • border_bottom (int) – Bottom border width.

  • border_char (str) – This will use a single border char for all borders. overruled by individual settings below.

  • border_left_char (str) – Char used for left border.

  • border_right_char (str) – Char used for right border.

  • border_top_char (str) – Char used for top border.

  • border_bottom_char (str) – Char user for bottom border.

  • corner_char (str) – Character used when two borders cross. (default is “”). This is overruled by individual settings below.

  • corner_top_left_char (str) – Char used for “nw” corner.

  • corner_top_right_char (str) – Char used for “ne” corner.

  • corner_bottom_left_char (str) – Char used for “sw” corner.

  • corner_bottom_right_char (str) – Char used for “se” corner.

  • crop_string (str) – String to use when cropping sideways, default is ‘[…]’.

  • crop (bool) – Crop contentof cell rather than expand vertically, default=**False**.

  • enforce_size (bool) – If true, the width/height of the cell is strictly enforced and extra text will be cropped rather than the cell growing vertically.

Raises

Exception – for impossible cell size requirements where the border width or height cannot fit, or the content is too small.

get_min_height()[source]

Get the minimum possible height of cell, including at least one line for data.

Returns

min_height (int) – The mininum height of cell.

get_min_width()[source]

Get the minimum possible width of cell, including at least one character-width for data.

Returns

min_width (int) – The minimum width of cell.

get_height()[source]

Get natural height of cell, including padding.

Returns

natural_height (int) – Height of cell.

get_width()[source]

Get natural width of cell, including padding.

Returns

natural_width (int) – Width of cell.

replace_data(data, **kwargs)[source]

Replace cell data. This causes a full reformat of the cell.

Parameters

data (str) – Cell data.

Notes

The available keyword arguments are the same as for EvCell.__init__.

reformat(**kwargs)[source]

Reformat the EvCell with new options

Keyword Arguments

available keyword arguments are the same as for EvCell.__init__. (The) –

Raises

Exception – If the cells cannot shrink enough to accomodate the options or the data given.

get()[source]

Get data, padded and aligned in the form of a list of lines.

class evennia.utils.evtable.EvColumn(*args, **kwargs)[source]

Bases: object

This class holds a list of Cells to represent a column of a table. It holds operations and settings that affect all cells in the column.

Columns are not intended to be used stand-alone; they should be incorporated into an EvTable (like EvCells)

__init__(*args, **kwargs)[source]
Parameters

for each row in the column (Text) –

Keyword Arguments

  • EvCell.__init_ keywords are available, these (All) –

  • will be persistently applied to every Cell in the (settings) –

  • column. –

add_rows(*args, **kwargs)[source]

Add new cells to column. They will be inserted as a series of rows. It will inherit the options of the rest of the column’s cells (use update to change options).

Parameters

  • for the new cells (Texts) –

  • ypos (int, optional) – Index position in table before which to insert the new column. Uses Python indexing, so to insert at the top, use ypos=0. If not given, data will be inserted at the end of the column.

Keyword Arguments

keywods as per EvCell.__init__. (Available) –

reformat(**kwargs)[source]

Change the options for the column.

Keyword Arguments

as per EvCell.__init__. (Keywords) –

reformat_cell(index, **kwargs)[source]

reformat cell at given index, keeping column options if necessary.

Parameters

index (int) – Index location of the cell in the column, starting from 0 for the first row to Nrows-1.

Keyword Arguments

as per EvCell.__init__. (Keywords) –

class evennia.utils.evtable.EvTable(*args, **kwargs)[source]

Bases: object

The table class holds a list of EvColumns, each consisting of EvCells so that the result is a 2D matrix.

__init__(*args, **kwargs)[source]
Parameters

texts for the table. (Header) –

Keyword Arguments

  • table (list of lists or list of EvColumns, optional) – This is used to build the table in a quick way. If not given, the table will start out empty and add_ methods need to be used to add rows/columns.

  • header (bool, optional) – True/False - turn off the header texts (*args) being treated as a header (such as not adding extra underlining)

  • pad_width (int, optional) – How much empty space to pad your cells with (default is 1)

  • border (str, optional)) – The border style to use. This is one of - None - No border drawing at all. - “table” - only a border around the whole table. - “tablecols” - table and column borders. (default) - “header” - only border under header. - “cols” - only vertical borders. - “incols” - vertical borders, no outer edges. - “rows” - only borders between rows. - “cells” - border around all cells.

  • border_width (int, optional) – Width of table borders, if border is active. Note that widths wider than 1 may give artifacts in the corners. Default is 1.

  • corner_char (str, optional) – Character to use in corners when border is active. Default is +.

  • corner_top_left_char (str, optional) – Character used for “nw” corner of table. Defaults to corner_char.

  • corner_top_right_char (str, optional) – Character used for “ne” corner of table. Defaults to corner_char.

  • corner_bottom_left_char (str, optional) – Character used for “sw” corner of table. Defaults to corner_char.

  • corner_bottom_right_char (str, optional) – Character used for “se” corner of table. Defaults to corner_char.

  • pretty_corners (bool, optional) – Use custom characters to make the table corners look “rounded”. Uses UTF-8 characters. Defaults to False for maximum compatibility with various displays that may occationally have issues with UTF-8 characters.

  • header_line_char (str, optional) – Character to use for underlining the header row (default is ‘~’). Requires border to not be None.

  • width (int, optional) – Fixed width of table. If not set, width is set by the total width of each column. This will resize individual columns in the vertical direction to fit.

  • height (int, optional) – Fixed height of table. Defaults to being unset. Width is still given precedence. If given, table cells will crop text rather than expand vertically.

  • evenwidth (bool, optional) – Used with the width keyword. Adjusts columns to have as even width as possible. This often looks best also for mixed-length tables. Default is False.

  • maxwidth (int, optional) – This will set a maximum width of the table while allowing it to be smaller. Only if it grows wider than this size will it be resized by expanding horizontally (or crop height is given). This keyword has no meaning if width is set.

Raises

Exception – If given erroneous input or width settings for the data.

Notes

Beyond those table-specific keywords, the non-overlapping keywords of EvCell.__init__ are also available. These will be passed down to every cell in the table.

add_header(*args, **kwargs)[source]

Add header to table. This is a number of texts to be put at the top of the table. They will replace an existing header.

Parameters

args (str) – These strings will be used as the header texts.

Keyword Arguments

  • keywords as per EvTable.__init__. Will be applied (Same) –

  • the new header's cells. (to) –

add_column(*args, **kwargs)[source]

Add a column to table. If there are more rows in new column than there are rows in the current table, the table will expand with empty rows in the other columns. If too few, the new column with get new empty rows. All filling rows are added to the end.

Parameters

  • args (EvColumn or multiple strings) – Either a single EvColumn instance or a number of data string arguments to be used to create a new column.

  • header (str, optional) – The header text for the column

  • xpos (int, optional) – Index position in table before which to input new column. If not given, column will be added to the end of the table. Uses Python indexing (so first column is xpos=0)

Keyword Arguments

keywords as per Cell.__init__. (Other) –

add_row(*args, **kwargs)[source]

Add a row to table (not a header). If there are more cells in the given row than there are cells in the current table the table will be expanded with empty columns to match. These will be added to the end of the table. In the same way, adding a line with too few cells will lead to the last ones getting padded.

Parameters

  • args (str) – Any number of string argumnets to use as the data in the row (one cell per argument).

  • ypos (int, optional) – Index position in table before which to input new row. If not given, will be added to the end of the table. Uses Python indexing (so first row is ypos=0)

Keyword Arguments

keywords are as per EvCell.__init__. (Other) –

reformat(**kwargs)[source]

Force a re-shape of the entire table.

Keyword Arguments

options as per EvTable.__init__. (Table) –

reformat_column(index, **kwargs)[source]

Sends custom options to a specific column in the table.

Parameters

index (int) – Which column to reformat. The column index is given from 0 to Ncolumns-1.

Keyword Arguments

options as per EvCell.__init__. (Column) –

Raises

Exception – if an invalid index is found.

get()[source]

Return lines of table as a list.

Returns

table_lines (list) – The lines of the table, in order.