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.
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,
Table(data=None, headers=_MISSING, metadata=None)¶
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
- TODO: DB API cursor?
- TODO: json
- Pretty text (also usable as GF Markdown)
- TODO: CSV
- 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.
from_data(data, headers=_MISSING, max_depth=1, **kwargs)¶
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.
from_dict(data, headers=_MISSING, max_depth=1, metadata=None)¶
from_list(data, headers=_MISSING, max_depth=1, metadata=None)¶
Create a Table from a
list. Operates the same as
from_data(), but forces the interpretation of the data as a Sequence.
from_object(data, headers=_MISSING, max_depth=1, metadata=None)¶
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)¶
Render this Table to HTML. Configure the structure of Table HTML by subclassing and overriding
- 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
Falseif appending multiple Table outputs or an otherwise customized HTML wrapping tag is needed.
- with_newlines (bool) – Set to
Trueif output should include added newlines to make the HTML more readable. Default
- with_metadata (bool/str) – Set to
Trueif 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.