tableutils - 2D data structure

If there is one recurring theme in boltons, it is that Python has excellent datastructures that constitute a good foundation for most quick manipulations, as well as building applications. However, Python usage has grown much faster than builtin data structure power. Python has a growing need for more advanced general-purpose data structures which behave intuitively.

The Table class is one example. When handed one- or two-dimensional data, it can provide useful, if basic, text and HTML renditions of small to medium sized data. It also heuristically handles recursive data of various formats (lists, dicts, namedtuples, objects).

For more advanced Table-style manipulation check out the pandas DataFrame.

class boltons.tableutils.Table(data=None, headers=_MISSING, metadata=None)[source]

This Table class is meant to be simple, low-overhead, and extensible. Its most common use would be for translation between in-memory data structures and serialization formats, such as HTML and console-ready text.

As such, it stores data in list-of-lists format, and does not copy lists passed in. It also reserves the right to modify those lists in a “filling” process, whereby short lists are extended to the width of the table (usually determined by number of headers). This greatly reduces overhead and processing/validation that would have to occur otherwise.

General description of headers behavior:

Headers describe the columns, but are not part of the data, however, if the headers argument is omitted, Table tries to infer header names from the data. It is possible to have a table with no headers, just pass in headers=None.

Supported inputs:

  • list of list objects
  • dict (list/single)
  • object (list/single)
  • collections.namedtuple (list/single)
  • TODO: DB API cursor?
  • TODO: json

Supported outputs:

  • HTML
  • Pretty text (also usable as GF Markdown)
  • TODO: json
  • TODO: json lines

To minimize resident size, the Table data is stored as a list of lists.


Append the given data to the end of the Table.

classmethod from_data(data, headers=_MISSING, max_depth=1, **kwargs)[source]

Create a Table from any supported data, heuristically selecting how to represent the data in Table format.

  • data (object) – Any object or iterable with data to be imported to the Table.
  • headers (iterable) – An iterable of headers to be matched to the data. If not explicitly passed, headers will be guessed for certain datatypes.
  • max_depth (int) – The level to which nested Tables should be created (default: 1).
  • _data_type (InputType subclass) – For advanced use cases, do not guess the type of the input data, use this data type instead.
classmethod from_dict(data, headers=_MISSING, max_depth=1, metadata=None)[source]

Create a Table from a dict. Operates the same as from_data(), but forces interpretation of the data as a Mapping.

classmethod from_list(data, headers=_MISSING, max_depth=1, metadata=None)[source]

Create a Table from a list. Operates the same as from_data(), but forces the interpretation of the data as a Sequence.

classmethod from_object(data, headers=_MISSING, max_depth=1, metadata=None)[source]

Create a Table from an object. Operates the same as from_data(), but forces the interpretation of the data as an object. May be useful for some dict and list subtypes.


Called on each value in an HTML table. By default it simply escapes the HTML. Override this method to add additional conditions and behaviors, but take care to ensure the final output is HTML escaped.

to_html(orientation=None, wrapped=True, with_headers=True, with_newlines=True, with_metadata=False, max_depth=1)[source]

Render this Table to HTML. Configure the structure of Table HTML by subclassing and overriding _html_* class attributes.

  • orientation (str) – one of ‘auto’, ‘horizontal’, or ‘vertical’ (or the first letter of any of those). Default ‘auto’.
  • wrapped (bool) – whether or not to include the wrapping ‘<table></table>’ tags. Default True, set to False if appending multiple Table outputs or an otherwise customized HTML wrapping tag is needed.
  • with_newlines (bool) – Set to True if output should include added newlines to make the HTML more readable. Default False.
  • with_metadata (bool/str) – Set to True if output should be preceded with a Table of preset metadata, if it exists. Set to special value 'bottom' if the metadata Table HTML should come after the main HTML output.
  • max_depth (int) – Indicate how deeply to nest HTML tables before simply reverting to repr()-ing the nested data.

A text string of the HTML of the rendered table.

to_text(with_headers=True, maxlen=None)[source]

Get the Table’s textual representation. Only works well for Tables with non-recursive data.

  • with_headers (bool) – Whether to include a header row at the top.
  • maxlen (int) – Max length of data in each cell.