Skip to content

Latest commit

 

History

History
153 lines (117 loc) · 5.71 KB

quickstart.rst

File metadata and controls

153 lines (117 loc) · 5.71 KB

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("\n".join(tabular_output.format_output(iter(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 :mod:`~cli_helpers.tabular_output` module. This module gives us access to the :func:`~cli_helpers.tabular_output.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, :mod:`~cli_helpers.tabular_output` uses tabulate, terminaltables, :mod:`csv`, and its own vertical table layout.

The best way to see the various display formats is to use the :class:`~cli_helpers.tabular_output.TabularOutputFormatter` class. This is what the :func:`~cli_helpers.tabular_output.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("\n".join(formatter.format_output(iter(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("\n".join(formatter.format_output(iter(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 :class:`~cli_helpers.tabular_output.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("\n".join(formatter.format_output(iter(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 :data:`TabularOutputFormatter.format_name <cli_helpers.tabular_output.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("\n".join(format_output(iter(data), headers, format_name='simple', disable_numparse=True)))
id    rating
----  --------
1     1.5
2     19.605
3     100.0
>>> print("\n".join(format_output(iter(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!

:mod:`~cli_helpers.tabular_output` supports any :term:`iterable`, not just a :class:`list` or :class:`tuple`. You can use a :class:`range`, :func:`enumerate`, a :class:`str`, or even a :class:`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("\n".join(format_output(iter(data), headers, format_name='simple')))
  a    b    c
---  ---  ---
  0    1    2
  3    4    5
  6    7    8

Real life examples include a PyMySQL :class:`Cursor <pymysql:pymysql.cursors.Cursor>` with database results or NumPy :class:`ndarray <numpy:numpy.ndarray>` with data points.