Quickstart

Displaying Tabular Data

The Basics

CLI Helpers provides a simple way to display your tabular data (columns/rows) in a visually-appealing manner:

>>> from cli_helpers import tabular_output

>>> data = [[1, 'Asgard', True], [2, 'Camelot', False], [3, 'El Dorado', True]]
>>> headers = ['id', 'city', 'visited']

>>> print(tabular_output.format_output(data, headers, format_name='simple'))

  id  city       visited
----  ---------  ---------
   1  Asgard     True
   2  Camelot    False
   3  El Dorado  True

Let’s take a look at what we did there.

1. We imported the tabular_output module. This module gives us access to the format_output() function.
2. Next we generate some data. Plus, we need a list of headers to give our data some context.
3. We format the output using the display format simple. That’s a nice looking table!

Display Formats

To display your data, tabular_output uses tabulate, terminaltables, csv, and its own vertical table layout.

The best way to see the various display formats is to use the TabularOutputFormatter class. This is what the format_output() function in our first example uses behind the scenes.

Let’s get a list of all the supported format names:

>>> from cli_helpers.tabular_output import TabularOutputFormatter
>>> formatter = TabularOutputFormatter()
>>> formatter.supported_formats
('vertical', 'csv', 'tsv', 'mediawiki', 'html', 'latex', 'latex_booktabs', 'textile', 'moinmoin', 'jira', 'plain', 'minimal', 'simple', 'grid', 'fancy_grid', 'pipe', 'orgtbl', 'psql', 'psql_unicode', 'rst', 'ascii', 'double', 'github')

You can format your data in any of those supported formats. Let’s take the same data from our first example and put it in the fancy_grid format:

>>> data = [[1, 'Asgard', True], [2, 'Camelot', False], [3, 'El Dorado', True]]
>>> headers = ['id', 'city', 'visited']
>>> print(formatter.format_output(data, headers, format_name='fancy_grid'))
╒══════╤═══════════╤═══════════╕
│   id │ city      │ visited   │
╞══════╪═══════════╪═══════════╡
│    1 │ Asgard    │ True      │
├──────┼───────────┼───────────┤
│    2 │ Camelot   │ False     │
├──────┼───────────┼───────────┤
│    3 │ El Dorado │ True      │
╘══════╧═══════════╧═══════════╛

That was easy! How about CLI Helper’s vertical table layout?

>>> print(formatter.format_output(data, headers, format_name='vertical'))
***************************[ 1. row ]***************************
id      | 1
city    | Asgard
visited | True
***************************[ 2. row ]***************************
id      | 2
city    | Camelot
visited | False
***************************[ 3. row ]***************************
id      | 3
city    | El Dorado
visited | True

Default Format

When you create a TabularOutputFormatter object, you can specify a default formatter so you don’t have to pass the format name each time you want to format your data:

>>> formatter = TabularOutputFormatter(format_name='plain')
>>> print(formatter.format_output(data, headers))
  id  city       visited
   1  Asgard     True
   2  Camelot    False
   3  El Dorado  True

Tip

You can get or set the default format whenever you’d like through TabularOutputFormatter.format_name.

Passing Options to the Formatters

Many of the formatters have settings that can be tweaked by passing an optional argument when you format your data. For example, if we wanted to enable or disable number parsing on any of tabulate’s formats, we could:

>>> data = [[1, 1.5], [2, 19.605], [3, 100.0]]
>>> headers = ['id', 'rating']
>>> print(format_output(data, headers, format_name='simple', disable_numparse=True))
id    rating
----  --------
1     1.5
2     19.605
3     100.0
>>> print(format_output(data, headers, format_name='simple', disable_numparse=False))
  id    rating
----  --------
   1     1.5
   2    19.605
   3   100

Lists and tuples and bytearrays. Oh my!

tabular_output supports any iterable, not just a list or tuple. You can use a range, enumerate(), a str, or even a bytearray! Here is a far-fetched example to prove the point:

>>> step = 3
>>> data = [range(n, n + step) for n in range(0, 9, step)]
>>> headers = 'abc'
>>> print(format_output(data, headers, format_name='simple'))
  a    b    c
---  ---  ---
  0    1    2
  3    4    5
  6    7    8

Real life examples include a PyMySQL Cursor with database results or NumPy ndarray with data points.