1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
|
Tabletext
=========
``tabletext`` is a Python library to format (pretty-print) tabular data as text
tables. Its goal is to be as simple as possible, while allowing optional
customization of the output.
``tabletext`` also comes with a command line utility, ``table`` which formats
its input into a table and prints it on the standard output.
Installation
------------
``tabletext`` is available on Pypi_ and can be installed with:
.. _Pypi: https://pypi.python.org/pypi/tabletext
.. code-block:: bash
$ pip install tabletext
Overview
--------
Library
~~~~~~~
``tabletext`` exposes a single function, ``to_text`` which in its simplest form
takes a list of lists (or any sequence_ of sequences_) and format it as
a table. The data is assumed to be in `row-major order`_, meaning that the
outer sequence's elements are the rows of the table.
.. _row-major order: https://en.wikipedia.org/wiki/Row-major_order
.. _sequence:
.. _sequences: https://docs.python.org/2/glossary.html#term-sequence
.. code:: python
>>> from tabletext import to_text
>>> a = [["Code", "Name"],
["AD", "ANDORRA"],
["AE", "UNITED ARAB EMIRATES"],
["AF", "AFGHANISTAN"],
["AG", "ANTIGUA AND BARBUDA"]]
>>> print to_text(a)
will output the following:
.. code:: bash
┌──────┬──────────────────────┐
│ Code │ Name │
├──────┼──────────────────────┤
│ AD │ ANDORRA │
├──────┼──────────────────────┤
│ AE │ UNITED ARAB EMIRATES │
├──────┼──────────────────────┤
│ AF │ AFGHANISTAN │
├──────┼──────────────────────┤
│ AG │ ANTIGUA AND BARBUDA │
└──────┴──────────────────────┘
You can customize the output with optional arguments:
.. code:: python
>>> print to_text(a, header=True, corners="+", hor="-", ver="|",
header_corners="+", header_hor="=",
header_ver="!", formats=[">", "<"])
will output:
.. code:: bash
+======+======================+
! Code ! Name !
+======+======================+
| AD | ANDORRA |
+------+----------------------+
| AE | UNITED ARAB EMIRATES |
+------+----------------------+
| AF | AFGHANISTAN |
+------+----------------------+
| AG | ANTIGUA AND BARBUDA |
+------+----------------------+
| AI | ANGUILLA |
+------+----------------------+
See the Documentation_ section for more details about the optional arguments of
the ``to_text`` function.
Command line utility
~~~~~~~~~~~~~~~~~~~~
The command line utility reads the table from its input, each line representing
a row, the row's entries being separated by ``\t`` characters (configurable),
and outputs the formatted table to the standard output:
.. code:: bash
$ df -h | tr -s ' ' \\t | cut -f1-6 | table --header
╒════════════╤══════╤══════╤═══════╤══════╤════════════════╕
│ Filesystem │ Size │ Used │ Avail │ Use% │ Mounted │
╞════════════╪══════╪══════╪═══════╪══════╪════════════════╡
│ /dev/sda2 │ 25G │ 14G │ 9.5G │ 60% │ / │
├────────────┼──────┼──────┼───────┼──────┼────────────────┤
│ dev │ 3.8G │ 0 │ 3.8G │ 0% │ /dev │
├────────────┼──────┼──────┼───────┼──────┼────────────────┤
│ run │ 3.8G │ 756K │ 3.8G │ 1% │ /run │
├────────────┼──────┼──────┼───────┼──────┼────────────────┤
│ tmpfs │ 3.8G │ 1.3M │ 3.8G │ 1% │ /dev/shm │
├────────────┼──────┼──────┼───────┼──────┼────────────────┤
│ tmpfs │ 3.8G │ 0 │ 3.8G │ 0% │ /sys/fs/cgroup │
├────────────┼──────┼──────┼───────┼──────┼────────────────┤
│ /dev/sda1 │ 511M │ 24M │ 488M │ 5% │ /boot │
├────────────┼──────┼──────┼───────┼──────┼────────────────┤
│ tmpfs │ 3.8G │ 372M │ 3.5G │ 10% │ /tmp │
├────────────┼──────┼──────┼───────┼──────┼────────────────┤
│ /dev/sda3 │ 15G │ 9.8G │ 4.2G │ 71% │ /home │
├────────────┼──────┼──────┼───────┼──────┼────────────────┤
│ /dev/sda5 │ 77G │ 46G │ 27G │ 64% │ /media/data │
├────────────┼──────┼──────┼───────┼──────┼────────────────┤
│ tmpfs │ 774M │ 16K │ 774M │ 1% │ /run/user/1000 │
└────────────┴──────┴──────┴───────┴──────┴────────────────┘
The available options can be printed with ``table --help`` and closely follow
the optional arguments of the library's ``to_text`` function as documented
here_.
.. _here: documentation_
Documentation
-------------
The optional arguments of the ``to_text`` function are as follows:
================== ================ ================
Argument Default Description
================== ================ ================
``formats`` ``None`` Format strings for the entries (see
below)
``padding`` ``(1, 1)`` Left and right padding lengths
``corners`` ``"┌┬┐├┼┤└┴┘"`` Characters to use for the corners
``hor`` ``"─"`` Horizontal separation character
``ver`` ``"│"`` Vertical separation character
``header`` ``False`` Wether or not to display the first row
as a header row
``header_corners`` ``"╒╤╕╞╪╡"`` Characters to use for the header row
corners
``header_hor`` ``"═"`` Horizontal separation character for the
header row
``header_ver`` ``"│"`` Vertical separation character for the
header row
================== ================ ================
More about some options:
* ``formats`` can be either a single format string, in which case it will be
used for all entries, or a list of format strings, one per column of the
table. The format strings must follow Python's `format specification`_. Note
however that you don't have to specify the width since it is automatically
computed. Useful format strings are ``"<"``, ``">"`` and ``"^"`` for
left-aligned, right-aligned and centered columns respectively.
* ``corners`` and ``header_corners`` are strings containing the corner
characters to be used for rows and the header row respectively. Follow the
same order as in the default values. Alternatively, you can specify only one
character (that is, a string of length 1) which will be used for all corners.
.. _format specification: https://docs.python.org/2/library/string.html#format-specification-mini-language
|
