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 cliff.lister.Lister
base class API extends
Command
to allow take_action()
to return data to be
formatted using a user-selectable formatter. Subclasses should provide
a 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
the files command in the demoapp for details.
List Output Formatters¶
cliff is delivered with two output formatters for list
commands. 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.
(.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.
(.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.
Creating Your Own Formatter¶
If the standard formatters do not meet your needs, you can bundle
another formatter with your program by subclassing from
cliff.formatters.base.ListFormatter
and registering the
plugin in the cliff.formatter.list
namespace.