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