List Commands — cliff 0.5.1 documentation

### Navigation

- index
- next |
- previous |
- cliff 0.5.1 documentation »

# 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 add a `get_data()` method. Subclasses should provide a `get_data()` 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

### html

The `html` formatter uses tablib to produce HTML output as a table.

    (.venv)$ cliffdemo files -f html
    <table>
    <thead>
    <tr><th>Name</th>
    <th>Size</th></tr>
    </thead>
    <tr><td>build</td>
    <td>136</td></tr>
    <tr><td>cliffdemo.log</td>
    <td>3252</td></tr>
    <tr><td>Makefile</td>
    <td>5569</td></tr>
    <tr><td>requirements.txt</td>
    <td>33</td></tr>
    <tr><td>source</td>
    <td>782</td></tr>
    </table>

### json

The `json` formatter uses tablib to produce JSON output.

    (.venv)$ cliffdemo files -f json
    [{"Name": "build", "Size": 136}, {"Name": "cliffdemo.log", "Size":
    3461}, {"Name": "Makefile", "Size": 5569}, {"Name":
    "requirements.txt", "Size": 33}, {"Name": "source", "Size": 782}]

### 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 |
    +---------------+------+

### yaml

The `yaml` formatter uses tablib to produce YAML output as a sequence of mappings.

    (.venv)$ cliffdemo files -f yaml
    - {Name: build, Size: 136}
    - {Name: cliffdemo.log, Size: 3043}
    - {Name: Makefile, Size: 5569}
    - {Name: requirements.txt, Size: 33}
    - {Name: source, Size: 816}

### 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.

### Navigation

- index
- next |
- previous |
- cliff 0.5.1 documentation »