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
oflist
objectsdict
(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: CSV
- TODO: json
- TODO: json lines
To minimize resident size, the Table data is stored as a list of lists.
-
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.
Parameters: - 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 asfrom_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 asfrom_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 asfrom_data()
, but forces the interpretation of the data as an object. May be useful for somedict
andlist
subtypes.
-
get_cell_html
(value)[source]¶ 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.Parameters: - 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 toFalse
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. DefaultFalse
. - 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.
Returns: A text string of the HTML of the rendered table.