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
|
Quickstart
==========
Displaying Tabular Data
-----------------------
The Basics
++++++++++
CLI Helpers provides a simple way to display your tabular data (columns/rows) in a visually-appealing manner::
>>> from cli_helpers import tabular_output
>>> data = [[1, 'Asgard', True], [2, 'Camelot', False], [3, 'El Dorado', True]]
>>> headers = ['id', 'city', 'visited']
>>> print("\n".join(tabular_output.format_output(iter(data), headers, format_name='simple')))
id city visited
---- --------- ---------
1 Asgard True
2 Camelot False
3 El Dorado True
Let's take a look at what we did there.
1. We imported the :mod:`~cli_helpers.tabular_output` module. This module gives us access to the :func:`~cli_helpers.tabular_output.format_output` function.
2. Next we generate some data. Plus, we need a list of headers to give our data some context.
3. We format the output using the display format ``simple``. That's a nice looking table!
Display Formats
+++++++++++++++
To display your data, :mod:`~cli_helpers.tabular_output` uses
`tabulate <https://bitbucket.org/astanin/python-tabulate>`_,
`terminaltables <https://robpol86.github.io/terminaltables/>`_, :mod:`csv`,
and its own vertical table layout.
The best way to see the various display formats is to use the
:class:`~cli_helpers.tabular_output.TabularOutputFormatter` class. This is
what the :func:`~cli_helpers.tabular_output.format_output` function in our
first example uses behind the scenes.
Let's get a list of all the supported format names::
>>> from cli_helpers.tabular_output import TabularOutputFormatter
>>> formatter = TabularOutputFormatter()
>>> formatter.supported_formats
('vertical', 'csv', 'tsv', 'mediawiki', 'html', 'latex', 'latex_booktabs', 'textile', 'moinmoin', 'jira', 'plain', 'minimal', 'simple', 'grid', 'fancy_grid', 'pipe', 'orgtbl', 'psql', 'psql_unicode', 'rst', 'ascii', 'double', 'github')
You can format your data in any of those supported formats. Let's take the
same data from our first example and put it in the ``fancy_grid`` format::
>>> data = [[1, 'Asgard', True], [2, 'Camelot', False], [3, 'El Dorado', True]]
>>> headers = ['id', 'city', 'visited']
>>> print("\n".join(formatter.format_output(iter(data), headers, format_name='fancy_grid')))
╒══════╤═══════════╤═══════════╕
│ id │ city │ visited │
╞══════╪═══════════╪═══════════╡
│ 1 │ Asgard │ True │
├──────┼───────────┼───────────┤
│ 2 │ Camelot │ False │
├──────┼───────────┼───────────┤
│ 3 │ El Dorado │ True │
╘══════╧═══════════╧═══════════╛
That was easy! How about CLI Helper's vertical table layout?
>>> print("\n".join(formatter.format_output(iter(data), headers, format_name='vertical')))
***************************[ 1. row ]***************************
id | 1
city | Asgard
visited | True
***************************[ 2. row ]***************************
id | 2
city | Camelot
visited | False
***************************[ 3. row ]***************************
id | 3
city | El Dorado
visited | True
Default Format
++++++++++++++
When you create a :class:`~cli_helpers.tabular_output.TabularOutputFormatter`
object, you can specify a default formatter so you don't have to pass the
format name each time you want to format your data::
>>> formatter = TabularOutputFormatter(format_name='plain')
>>> print("\n".join(formatter.format_output(iter(data), headers)))
id city visited
1 Asgard True
2 Camelot False
3 El Dorado True
.. TIP::
You can get or set the default format whenever you'd like through
:data:`TabularOutputFormatter.format_name <cli_helpers.tabular_output.TabularOutputFormatter.format_name>`.
Passing Options to the Formatters
+++++++++++++++++++++++++++++++++
Many of the formatters have settings that can be tweaked by passing
an optional argument when you format your data. For example,
if we wanted to enable or disable number parsing on any of
`tabulate's <https://bitbucket.org/astanin/python-tabulate>`_
formats, we could::
>>> data = [[1, 1.5], [2, 19.605], [3, 100.0]]
>>> headers = ['id', 'rating']
>>> print("\n".join(format_output(iter(data), headers, format_name='simple', disable_numparse=True)))
id rating
---- --------
1 1.5
2 19.605
3 100.0
>>> print("\n".join(format_output(iter(data), headers, format_name='simple', disable_numparse=False)))
id rating
---- --------
1 1.5
2 19.605
3 100
Lists and tuples and bytearrays. Oh my!
+++++++++++++++++++++++++++++++++++++++
:mod:`~cli_helpers.tabular_output` supports any :term:`iterable`, not just
a :class:`list` or :class:`tuple`. You can use a :class:`range`,
:func:`enumerate`, a :class:`str`, or even a :class:`bytearray`! Here is a
far-fetched example to prove the point::
>>> step = 3
>>> data = [range(n, n + step) for n in range(0, 9, step)]
>>> headers = 'abc'
>>> print("\n".join(format_output(iter(data), headers, format_name='simple')))
a b c
--- --- ---
0 1 2
3 4 5
6 7 8
Real life examples include a PyMySQL
:class:`Cursor <pymysql:pymysql.cursors.Cursor>` with
database results or
NumPy :class:`ndarray <numpy:numpy.ndarray>` with data points.
|
