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
|
===============
List Commands
===============
One of the most common patterns with command line programs is the need
to print lists of data. cliff provides a base class for commands of
this type so that they only need to prepare the data, and the user can
choose from one of several output formatter plugins to see the list of
data in their preferred format.
Lister
======
The :class:`cliff.lister.Lister` base class API extends
:class:`Command` to allow :func:`take_action` to return data to be
formatted using a user-selectable formatter. Subclasses should provide
a :func:`take_action` implementation that returns a two member tuple
containing a tuple with the names of the columns in the dataset and an
iterable that will yield the data to be output. See the description of
:ref:`the files command in the demoapp <demoapp-list>` for details.
List Output Formatters
======================
cliff is delivered with two output formatters for list
commands. :class:`Lister` adds a command line switch to let the user
specify the formatter they want, so you don't have to do any extra
work in your application.
csv
---
The ``csv`` formatter produces a comma-separated-values document as
output. CSV data can be imported into a database or spreadsheet for
further manipulation.
::
(.venv)$ cliffdemo files -f csv
"Name","Size"
"build",136
"cliffdemo.log",2690
"Makefile",5569
"source",408
table
-----
The ``table`` formatter uses PrettyTable_ to produce output formatted
for human consumption.
.. _PrettyTable: https://pypi.org/project/prettytable/
::
(.venv)$ cliffdemo files
+---------------+------+
| Name | Size |
+---------------+------+
| build | 136 |
| cliffdemo.log | 2546 |
| Makefile | 5569 |
| source | 408 |
+---------------+------+
value
-----
The ``value`` formatter produces a space separated output with no headers.
::
(.venv)$ cliffdemo files -f value
build 136
cliffdemo.log 2690
Makefile 5569
source 408
This format can be very convenient when you want to pipe the output to
a script.
::
(.venv)$ cliffdemo files -f value | while read NAME SIZE
do
echo $NAME is $SIZE bytes
done
build is 136 bytes
cliffdemo.log is 2690 bytes
Makefile is 5569 bytes
source is 408 bytes
yaml
----
The ``yaml`` formatter uses PyYAML_ to produce a YAML sequence of
mappings.
.. _PyYAML: http://pyyaml.org/
::
(.venv)$ cliffdemo files -f yaml
- Name: dist
Size: 4096
- Name: cliffdemo.egg-info
Size: 4096
- Name: README.rst
Size: 960
- Name: setup.py
Size: 1807
- Name: build
Size: 4096
- Name: cliffdemo
Size: 4096
json
----
The ``json`` formatter produces an array of objects in indented JSON
format.
::
(.venv)$ cliffdemo files -f json
[
{
"Name": "source",
"Size": 4096
},
{
"Name": "Makefile",
"Size": 5569
},
{
"Name": "build",
"Size": 4096
}
]
Other Formatters
----------------
A formatter using tablib_ to produce HTML is available as part of
`cliff-tablib`_.
.. _cliff-tablib: https://github.com/dreamhost/cliff-tablib
Creating Your Own Formatter
---------------------------
If the standard formatters do not meet your needs, you can bundle
another formatter with your program by subclassing from
:class:`cliff.formatters.base.ListFormatter` and registering the
plugin in the ``cliff.formatter.list`` namespace.
.. _tablib: https://github.com/kennethreitz/tablib
|
