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