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