API documentation

Public interface

All of TableD’s functionality can be accessed through these 5 methods.

tabled.new(headings: typing.Union[typing.List[typing.Any], NoneType] = None, data: typing.Union[typing.List[typing.List[typing.Any]], NoneType] = None, style: str = 'default', align: str = None, device: str = 'stdout', dataframe=None) → tabled.tabled.TableD

Creates a new TableD object. This should be used instead of calling TableD’s __init__() directly.

Parameters:

• headings – A list of column headings.
• data – Nested list of lists of cell contents.
• style – Style of pretty printer.
• align – Align cell content to either left, center or right. Default to setting specified in style.
• device – Where to output pretty printed table.
• dataframe – existing pandas dataframe object.

Returns:

A TableD object.

Example

>>> new()
<tabled.tabled.TableD object at 0x...>

TableD.add_row(row: typing.List[typing.Any]) → None

Append a single row to table body.

Parameters:row – A row of data to be appended to the table.

Example

>>> table = TableD()
>>> table.add_row(['x1', 'x2', 'x3'])
>>> table.data
[['x1', 'x2', 'x3']]

TableD.add_rows(rows: typing.List[typing.List[typing.Any]]) → None

Append multiple rows to table body.

Parameters:rows – Multiple rows of data to be appended to table.

Example

>>> table = TableD()
>>> table.add_rows([['x1', 'x2', 'x3'],
...                 ['y1', 'y2', 'y3']])
>>> table.data
[['x1', 'x2', 'x3'], ['y1', 'y2', 'y3']]

TableD.set_headings(headings: typing.List[typing.Any]) → None

Overwrite or set the table headings.

Parameters:headings – A list of column headings.

Example

>>> table = TableD()
>>> table.set_headings(['id', 2, 3])
>>> table.headings
['id', '2', '3']

TableD.show() → None

Generate, cache and display table to standard output. Use cached version if available.

Internals

tabled.tabled

synopsis:

Pretty print data in tabular format.

copyright:

3. 2017, Tommy Ip.

license:

MIT

class tabled.tabled.TableD(headings: typing.Union[typing.List[typing.Any], NoneType] = None, data: typing.Union[typing.List[typing.List[typing.Any]], NoneType] = None, style: str = 'default', align: str = None, device: str = 'stdout') → None

Public interface for the central table abstraction.

headings

A list of column headings.

data

Nested list of lists of cell contents.

style

Style of pretty printer.

align

Align cell content to either left, center or right. Default to setting specified in style.

device

Where to output pretty printed table.

_columns

The number of columns the table have.

_output

Cached table string.

_cache_valid

Validity of the cached table string.

Example

>>> table = TableD(
...     ['Repository', 'Author', 'Type'],
...     [['tableD', 'Tommy Ip', 'Python library'],
...      ['VueJS', 'Evan You', 'Frontend JS framework'],
...      ['flask', 'Armin Ronacher', 'Web framework']]
... )
>>> table.show()
+------------+----------------+-----------------------+
| Repository | Author         | Type                  |
+------------+----------------+-----------------------+
| tableD     | Tommy Ip       | Python library        |
| VueJS      | Evan You       | Frontend JS framework |
| flask      | Armin Ronacher | Web framework         |
+------------+----------------+-----------------------+

__init__(headings: typing.Union[typing.List[typing.Any], NoneType] = None, data: typing.Union[typing.List[typing.List[typing.Any]], NoneType] = None, style: str = 'default', align: str = None, device: str = 'stdout') → None

Initialize data storage engine for TableD. You should use tabled.new() to construct a TableD object.

add_row(row: typing.List[typing.Any]) → None

Append a single row to table body.

Parameters:row – A row of data to be appended to the table.

Example

>>> table = TableD()
>>> table.add_row(['x1', 'x2', 'x3'])
>>> table.data
[['x1', 'x2', 'x3']]

add_rows(rows: typing.List[typing.List[typing.Any]]) → None

Append multiple rows to table body.

Parameters:rows – Multiple rows of data to be appended to table.

Example

>>> table = TableD()
>>> table.add_rows([['x1', 'x2', 'x3'],
...                 ['y1', 'y2', 'y3']])
>>> table.data
[['x1', 'x2', 'x3'], ['y1', 'y2', 'y3']]

set_headings(headings: typing.List[typing.Any]) → None

Overwrite or set the table headings.

Parameters:headings – A list of column headings.

Example

>>> table = TableD()
>>> table.set_headings(['id', 2, 3])
>>> table.headings
['id', '2', '3']

show() → None

Generate, cache and display table to standard output. Use cached version if available.

__weakref__

list of weak references to the object (if defined)

tabled.pretty_print

synopsis:

Pretty printing engine for tableD.

copyright:

3. 2017, Tommy Ip.

license:

MIT

tabled.pretty_print.left_pad(string: str, width: int) → str

Insert spaces to the left of a string to fit into a container.

Parameters:

• string – A text value to be padded with spaces.
• width – The width of the string container.

Returns:

A string aligned right in a container.

Example

>>> left_pad('tableD', 10)
'    tableD'

tabled.pretty_print.right_pad(string: str, width: int) → str

Insert spaces to the right of a string to fit into a container.

Parameters:

• string – A text value to be padded with spaces.
• width – The width of the string container.

Returns:

A string aligned left in a container.

Example

>>> right_pad('tableD', 10)
'tableD    '

tabled.pretty_print.left_right_pad(string: str, width: int) → str

Insert spaces to both sides of a string to fit into a container.

Note

The right side of the string would be allocated more spaces if the amount of blank spaces cannot be divided equally by 2.

Parameters:

• string – A text value to be padded with spaces.
• width – The width of the string container.

Returns:

A string aligned center in a container.

Example

>>> left_right_pad('tableD', 11)
'  tableD   '

tabled.pretty_print.pad(string: str, width: int, align: str, margin: int = 1) → str

Pad and align a string in a container.

Parameters:

• string – Input text to be padded and aligned.
• width – The width of the container.
• align – Left, center or right alignment.
• margin – Margin width between the string and the side wall.

Returns:

A string padded and aligned in a container.

Example

>>> pad('library', 13, 'left')
' library     '

tabled.pretty_print.render_row(row: typing.List[str], widths: typing.List[int], delimiters: typing.Dict[str, str], align: str = 'left', margin: int = 1) → str

Render a table row.

Parameters:

• row – A row of string, each is a cell of their columns.
• widths – A list of column widths.
• delimiter – A dictionary of column dividers.
• align – Left, center or right alignment of each cell.
• margin – Margin width between the string and the side wall.

Returns:

A string containing a print ready row.

Example

>>> render_row(['Some cell content', 'word', '1'], [22, 6, 7],
...               {'left': '|', 'right': '|', 'connector': '|'})
'| Some cell content    | word | 1     |'

tabled.pretty_print.render_table(headings: typing.List[str], table: typing.List[typing.List[str]], style: str = 'default', align: typing.Union[str, NoneType] = None) → str

This is where the magic happens!

Parameters:

• headings – A list of text containing the headings.
• table – Cells data in a nested list of lists structure.
• style – Style of formatting in the table.
• align – Override settings in style if specified.

Returns:

A string with formatting ready for output.

Example

>>> table = [['1', '1'],
...          ['2', '4'],
...          ['3', '9']]
>>> print(render_table(['x', 'f(x) = x^2'], table))
+---+------------+
| x | f(x) = x^2 |
+---+------------+
| 1 | 1          |
| 2 | 4          |
| 3 | 9          |
+---+------------+

tabled.utils

synopsis:

Utility functions.

copyright:

3. 2017, Tommy Ip.

license:

MIT

tabled.utils.max_width(column: typing.List[str]) → int

Finds the longest string in a column and returns its length.

Parameters:column – A list of strings represented as a column in a table. Returns:The length of the longest string.

Example

>>> max_width(['example text', 'Some long lines.', 'short'])
16

tabled.utils.rotate_table(table: typing.List[typing.List[str]]) → typing.List[typing.List[str]]

Transform rows to columns and columns to rows.

Parameters:table – Nested list of lists that is represented as a table structure. Returns:A rotated table with columns as rows.

Note

This operation is non directional, so applying this function twice would return the orginal input.

Example

>>> rotate_table([['x1', 'x2', 'x3'],
...               ['y1', 'y2', 'y3'],
...               ['z1', 'z2', 'z3']])
... 
[['x1', 'y1', 'z1'],
 ['x2', 'y2', 'z2'],
 ['x3', 'y3', 'z3']]

tabled.utils.columns_width(table: typing.List[typing.List[str]]) → typing.List[int]

Finds the width for each column in a table.

Parameters:table – Nested list of lists that is represented as a table structure. Returns:A list of integers showing the width for each columns. The width is the determined by the longest text in a column.

Example

>>> columns_width([['Example', 'This is very long'],
...                ['Short', 'word'],
...                ['Another long example', 'var']])
[20, 17]

tabled.utils.str_list(raw_list: typing.List[typing.Any]) → typing.List[str]

Cast all elements in a list to Text type.

tabled.utils.str_nested_list(nested_raw_list: typing.List[typing.List[typing.Any]]) → typing.List[typing.List[str]]

Cast all elements in a nested list to Text type.

tabled.utils.normalize_list(row: typing.List[str], size: int) → typing.List[str]

Make a row the same length as other rows by filling in blank spaces.

Parameters:

• row – A list of string to be normalized
• size – The length of the final list

Returns:

A list with of length size with blank element filled with “”. Trim any extra elements if the list is longer than size.

tabled.style_templates

synopsis:

Contains table styles.

copyright:

3. 2017, Tommy Ip.

license:

MIT

tabled.style_templates.get_style(style: str = 'default') → typing.Dict[str, typing.Dict[str, str]]

Construct and return a table style.

Parameters:style – Style name. Returns:A dictionary of style separated by categories.