diff options
Diffstat (limited to 'docs/source/list_commands.rst')
| -rw-r--r-- | docs/source/list_commands.rst | 85 |
1 files changed, 8 insertions, 77 deletions
diff --git a/docs/source/list_commands.rst b/docs/source/list_commands.rst index f76188b..62fbebb 100644 --- a/docs/source/list_commands.rst +++ b/docs/source/list_commands.rst @@ -1,50 +1,11 @@ -=============== - List Commands -=============== +======================== + List Output Formatters +======================== -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 +cliff-tablib delivers several new output formatters for list commands. html ----- +==== The ``html`` formatter uses tablib_ to produce HTML output as a table. @@ -69,39 +30,19 @@ The ``html`` formatter uses tablib_ to produce HTML output as a table. </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. - -.. _PrettyTable: http://code.google.com/p/prettytable/ - -:: - - (.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. @@ -115,14 +56,4 @@ sequence of mappings. - {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 -:class:`cliff.formatters.base.ListFormatter` and registering the -plugin in the ``cliff.formatter.list`` namespace. - - .. _tablib: https://github.com/kennethreitz/tablib |