Show Commands¶

One of the most common patterns with command line programs is the need to print properties of objects. 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 data in their preferred format.

ShowOne¶

The cliff.show.ShowOne 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 contains the data values associated with those names. See the description of the file command in the demoapp for details.

ShowOneWithDetails¶

The cliff.show.ShowOneWithDetails base class displays a single object’s fields with additional columns, such as descriptions, types, or sources. Unlike ShowOne, it does not limit table output to Field and Value columns.

Subclasses implement take_action() to return a two-member tuple containing:

A sequence of output column names.
An iterable of rows, each containing values in output column order. The first value in each row must be a string containing the resource’s field name.

For example:

from cliff import show


class ShowResource(show.ShowOneWithDetails):
    def take_action(self, parsed_args):
        return (
            ('Field', 'Value', 'Description'),
            (
                ('name', 'demo', 'Resource name'),
                ('status', 'ACTIVE', 'Current resource status'),
            ),
        )

As with ShowOne, -c / --column selects resource fields (rows), not output columns. Selection is case-insensitive, ignores surrounding whitespace, and accepts underscores in place of spaces. Selected rows retain their original order and all their output columns. Unrecognized field names are ignored if at least one requested field is recognized; otherwise, selection raises an error.

For example, resource show -c status would produce:

+--------+--------+-------------------------+
| Field  | Value  | Description             |
+--------+--------+-------------------------+
| status | ACTIVE | Current resource status |
+--------+--------+-------------------------+

ShowOneWithDetails uses the cliff.formatter.list plugins described in List Commands, with table as the default. Consequently, JSON and YAML output contain a list of row mappings rather than the single field-to-value mapping produced by ShowOne. For example, resource show -f json -c status would produce:

[
  {
    "Field": "status",
    "Value": "ACTIVE",
    "Description": "Current resource status"
  }
]

CSV and value output also include every output column of each selected row. The show-only shell formatter and Lister sorting options are not available.

Show Output Formatters¶

cliff is delivered with output formatters for show commands. ShowOne 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.

table¶

The table formatter uses PrettyTable to produce output formatted for human consumption. This is the default formatter.

(.venv)$ cliffdemo file setup.py
+---------------+--------------+
|     Field     |    Value     |
+---------------+--------------+
| Name          | setup.py     |
| Size          | 5825         |
| UID           | 502          |
| GID           | 20           |
| Modified Time | 1335569964.0 |
+---------------+--------------+

shell¶

The shell formatter produces output that can be parsed directly by a typical UNIX shell as variable assignments. This avoids extra parsing overhead in shell scripts.

(.venv)$ cliffdemo file -f shell setup.py
name="setup.py"
size="5916"
uid="527"
gid="501"
modified_time="1335655655.0"

(.venv)$ eval "$(cliffdemo file -f shell --prefix example_ setup.py)"
(.venv)$ echo $example_size
5916

value¶

The value formatter produces output that only contains the value of the field or fields.

(.venv)$ cliffdemo file -f value -c Size setup.py
5916
(.venv)$ SIZE="$(cliffdemo file -f value -c Size setup.py)"
(.venv)$ echo $SIZE
5916

yaml¶

The yaml formatter uses PyYAML to produce a YAML mapping where the field name is the key.

(.venv)$ cliffdemo file -f yaml setup.py
Name: setup.py
Size: 1807
UID: 1000
GID: 1000
Modified Time: 1393531476.9587486

json¶

The json formatter produces a JSON object where the field name is the key.

(.venv)$ cliffdemo file -f json setup.py
{
  "Modified Time": 1438726433.8055942,
  "GID": 1000,
  "UID": 1000,
  "Name": "setup.py",
  "Size": 1028
}

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.ShowFormatter and registering the plugin in the cliff.formatter.show namespace.

Show Commands