tabulate: auxiliary module to tablature matrix

PyHdust auxiliary module: third-part pretty-print tabular data.

license:: MIT License

pyhdust.tabulate.simple_separated_format(separator)[source]

Construct a simple TableFormat with columns separated by a separator.

>>> tsv = simple_separated_format("\t") ;         tabulate([["foo", 1], ["spam", 23]], tablefmt=tsv) == 'foo \t 1' +         '\nspam\t23'
True

pyhdust.tabulate.tabulate(tabular_data, headers=(), tablefmt='simple', floatfmt='g', numalign='decimal', stralign='left', missingval='')[source]

Format a fixed width table for pretty printing.

>>> print(tabulate([[1, 2.34], [-56, "8.999"], ["2", "10001"]]))
---  ---------
  1      2.34
-56      8.999
  2  10001
---  ---------

The first required argument (tabular_data) can be a list-of-lists (or another iterable of iterables), a list of named tuples, a dictionary of iterables, an iterable of dictionaries, a two-dimensional NumPy array, NumPy record array, or a Pandas’ dataframe.

Table headers

To print nice column headers, supply the second argument (headers):

headers can be an explicit list of column headers

if headers=”firstrow”, then the first row of data is used

if headers=”keys”, then dictionary keys or column indices are used

Otherwise a headerless table is produced.

If the number of headers is less than the number of columns, they are supposed to be names of the last columns. This is consistent with the plain-text format of R and Pandas’ dataframes.

>>> print(tabulate([["sex","age"],["Alice","F",24],["Bob","M",19]],
...       headers="firstrow"))
       sex      age
-----  -----  -----
Alice  F         24
Bob    M         19

Column alignment

tabulate tries to detect column types automatically, and aligns the values properly. By default it aligns decimal points of the numbers (or flushes integer numbers to the right), and flushes everything else to the left. Possible column alignments (numalign, stralign) are: “right”, “center”, “left”, “decimal” (only for numalign), and None (to disable alignment).

Table formats

floatfmt is a format specification used for columns which contain numeric data with a decimal point.

None values are replaced with a missingval string:

>>> print(tabulate([["spam", 1, None],
...                 ["eggs", 42, 3.14],
...                 ["other", None, 2.7]], missingval="?"))
-----  --  ----
spam    1  ?
eggs   42  3.14
other   ?  2.7
-----  --  ----

Various plain-text table formats (tablefmt) are supported: ‘plain’, ‘simple’, ‘grid’, ‘pipe’, ‘orgtbl’, ‘rst’, ‘mediawiki’,

‘latex’, and ‘latex_booktabs’. Variable tabulate_formats contains the list of currently supported formats.

“plain” format doesn’t use any pseudographics to draw tables, it separates columns with a double space:

>>> print(tabulate([["spam", 41.9999], ["eggs", "451.0"]],
...                 ["strings", "numbers"], "plain"))
strings      numbers
spam         41.9999
eggs        451

>>> print(tabulate([["spam", 41.9999], ["eggs", "451.0"]],
  tablefmt="plain"))
spam   41.9999
eggs  451

“simple” format is like Pandoc simple_tables:

>>> print(tabulate([["spam", 41.9999], ["eggs", "451.0"]],
...                 ["strings", "numbers"], "simple"))
strings      numbers
---------  ---------
spam         41.9999
eggs        451

>>> print(tabulate([["spam", 41.9999], ["eggs", "451.0"]],
  tablefmt="simple"))
----  --------
spam   41.9999
eggs  451
----  --------

“grid” is similar to tables produced by Emacs table.el package or Pandoc grid_tables:

>>> print(tabulate([["spam", 41.9999], ["eggs", "451.0"]],
...                ["strings", "numbers"], "grid"))
+-----------+-----------+
| strings   |   numbers |
+===========+===========+
| spam      |   41.9999 |
+-----------+-----------+
| eggs      |  451      |
+-----------+-----------+

>>> print(tabulate([["spam", 41.9999], ["eggs", "451.0"]],
  tablefmt="grid"))
+------+----------+
| spam |  41.9999 |
+------+----------+
| eggs | 451      |
+------+----------+

“fancy_grid” draws a grid using box-drawing characters:

>>> print(tabulate([["spam", 41.9999], ["eggs", "451.0"]],
...                ["strings", "numbers"], "fancy_grid"))
╒═══════════╤═══════════╕
│ strings   │   numbers │
╞═══════════╪═══════════╡
│ spam      │   41.9999 │
├───────────┼───────────┤
│ eggs      │  451      │
╘═══════════╧═══════════╛

“pipe” is like tables in PHP Markdown Extra extension or Pandoc pipe_tables:

>>> print(tabulate([["spam", 41.9999], ["eggs", "451.0"]],
...                ["strings", "numbers"], "pipe"))
| strings   |   numbers |
|:----------|----------:|
| spam      |   41.9999 |
| eggs      |  451      |

>>> print(tabulate([["spam", 41.9999], ["eggs", "451.0"]],
  tablefmt="pipe"))
|:-----|---------:|
| spam |  41.9999 |
| eggs | 451      |

“orgtbl” is like tables in Emacs org-mode and orgtbl-mode. They are slightly different from “pipe” format by not using colons to define column alignment, and using a “+” sign to indicate line intersections:

>>> print(tabulate([["spam", 41.9999], ["eggs", "451.0"]],
...                ["strings", "numbers"], "orgtbl"))
| strings   |   numbers |
|-----------+-----------|
| spam      |   41.9999 |
| eggs      |  451      |

>>> print(tabulate([["spam", 41.9999], ["eggs", "451.0"]],
  tablefmt="orgtbl"))
| spam |  41.9999 |
| eggs | 451      |

“rst” is like a simple table format from reStructuredText; please note that reStructuredText accepts also “grid” tables:

>>> print(tabulate([["spam", 41.9999], ["eggs", "451.0"]],
...                ["strings", "numbers"], "rst"))
=========  =========
strings      numbers
=========  =========
spam         41.9999
eggs        451
=========  =========

>>> print(tabulate([["spam", 41.9999], ["eggs", "451.0"]], tablefmt="rst"))
====  ========
spam   41.9999
eggs  451
====  ========

“mediawiki” produces a table markup used in Wikipedia and on other MediaWiki-based sites:

>>> print(tabulate([["strings", "numbers"], ["spam", 41.9999], ["eggs",
  "451.0"]], headers="firstrow", tablefmt="mediawiki"))
{| class="wikitable" style="text-align: left;"
|+ <!-- caption -->
|-
! strings   !! align="right"|   numbers
|-
| spam      || align="right"|   41.9999
|-
| eggs      || align="right"|  451
|}

“html” produces HTML markup:

>>> print(tabulate([["strings", "numbers"], ["spam", 41.9999],
  ["eggs", "451.0"]],
...                headers="firstrow", tablefmt="html"))
<table>
<tr><th>strings  </th><th style="text-align: right;">  numbers</th></tr>
<tr><td>spam     </td><td style="text-align: right;">  41.9999</td></tr>
<tr><td>eggs     </td><td style="text-align: right;"> 451     </td></tr>
</table>

“latex” produces a tabular environment of LaTeX document markup:

>>> print(tabulate([["spam", 41.9999], ["eggs", "451.0"]],
  tablefmt="latex"))
\begin{tabular}{lr}
\hline
 spam &  41.9999 \\
 eggs & 451      \\
\hline
\end{tabular}

“latex_booktabs” produces a tabular environment of LaTeX document markup using the booktabs.sty package:

>>> print(tabulate([["spam", 41.9999], ["eggs", "451.0"]],
  tablefmt="latex_booktabs"))
\begin{tabular}{lr}
\toprule
 spam &  41.9999 \\
 eggs & 451      \\
\bottomrule
\end{tabular}