Table

#

When building a console application it may be useful to display tabular data:

.. code-block:: text

+---------------+--------------------------+------------------+
| ISBN | Title | Author |
+---------------+--------------------------+------------------+
| 99921-58-10-7 | Divine Comedy | Dante Alighieri |
| 9971-5-0210-0 | A Tale of Two Cities | Charles Dickens |
| 960-425-059-0 | The Lord of the Rings | J. R. R. Tolkien |
| 80-902734-1-6 | And Then There Were None | Agatha Christie |
+---------------+--------------------------+------------------+

To display a table, use the table() method, set the headers, set the rows and then render the table:

.. code-block:: python

def handle(self):
    table = self.table()

    table.set_headers(['ISBN', 'Title', 'Author'])
    table.set_rows([
        ['99921-58-10-7', 'Divine Comedy', 'Dante Alighieri'],
        ['9971-5-0210-0', 'A Tale of Two Cities', 'Charles Dickens'],
        ['960-425-059-0', 'The Lord of the Rings', 'J. R. R. Tolkien'],
        ['80-902734-1-6', 'And Then There Were None', 'Agatha Christie']
    ])

    table.render(self.io)

.. tip::

All these steps can be done in one go using the ``render_table`` method:

.. code-block:: python

    self.render_table(
        ['ISBN', 'Title', 'Author'],
        [
            ['99921-58-10-7', 'Divine Comedy', 'Dante Alighieri'],
            ['9971-5-0210-0', 'A Tale of Two Cities', 'Charles Dickens'],
            ['960-425-059-0', 'The Lord of the Rings', 'J. R. R. Tolkien'],
            ['80-902734-1-6', 'And Then There Were None', 'Agatha Christie']
        ]
    )

You can add a table separator anywhere in the output by using table_separator(),
which returns a TableSeparator, as a row:

.. code-block:: python

table.set_rows([
    ['99921-58-10-7', 'Divine Comedy', 'Dante Alighieri'],
    ['9971-5-0210-0', 'A Tale of Two Cities', 'Charles Dickens'],
    self.table_separator(),
    ['960-425-059-0', 'The Lord of the Rings', 'J. R. R. Tolkien'],
    ['80-902734-1-6', 'And Then There Were None', 'Agatha Christie']
])

.. code-block:: text

+---------------+--------------------------+------------------+
| ISBN | Title | Author |
+---------------+--------------------------+------------------+
| 99921-58-10-7 | Divine Comedy | Dante Alighieri |
| 9971-5-0210-0 | A Tale of Two Cities | Charles Dickens |
+---------------+--------------------------+------------------+
| 960-425-059-0 | The Lord of the Rings | J. R. R. Tolkien |
| 80-902734-1-6 | And Then There Were None | Agatha Christie |
+---------------+--------------------------+------------------+

The table style can be changed to any built-in styles via set_style():

.. code-block:: python

# same as calling nothing
table.set_style('default')

# changes the default style to compact
table.set_style('compact')

This code results in:

.. code-block:: text

ISBN Title Author
99921-58-10-7 Divine Comedy Dante Alighieri
9971-5-0210-0 A Tale of Two Cities Charles Dickens
960-425-059-0 The Lord of the Rings J. R. R. Tolkien
80-902734-1-6 And Then There Were None Agatha Christie

You can also set the style to borderless:

.. code-block:: python

table.set_style('borderless')

which outputs:

.. code-block:: text

=============== ========================== ==================
 ISBN Title Author
=============== ========================== ==================
 99921-58-10-7 Divine Comedy Dante Alighieri
 9971-5-0210-0 A Tale of Two Cities Charles Dickens
 960-425-059-0 The Lord of the Rings J. R. R. Tolkien
 80-902734-1-6 And Then There Were None Agatha Christie
=============== ========================== ==================

If the built-in styles do not fit your need, define your own:

.. code-block:: python

# by default, this is based on the default style
style = self.table_style()

# customize the style
style.set_horizontal_border_char('<fg=magenta>|</>')
style.set_vertical_border_char('<fg=magenta>-</>')
style.set_crossing_char(' ')

# use the style for this table
table.set_style(style)

Here is a full list of things you can customize:

set_adding_char()
set_horizontal_border_char()
set_vertical_border_char()
set_crossing_char()
set_cell_header_format()
set_cell_row_format()
set_border_format()
set_pad_type()

.. tip::

The style can also be passed as a keyword argument to ``render_table()``

.. code-block:: python

    self.render_table(
        ['ISBN', 'Title', 'Author'],
        [
            ['99921-58-10-7', 'Divine Comedy', 'Dante Alighieri'],
            ['9971-5-0210-0', 'A Tale of Two Cities', 'Charles Dickens'],
            ['960-425-059-0', 'The Lord of the Rings', 'J. R. R. Tolkien'],
            ['80-902734-1-6', 'And Then There Were None', 'Agatha Christie']
        ]
        style='borderless'
    )

Spanning Multiple Columns and Rows#

To make a table cell that spans multiple columns you can use table_cell(),
which returns a TableCell instance:

.. code-block:: python

table = self.table()

table.set_headers(['ISBN', 'Title', 'Author'])
table.set_rows([
    ['99921-58-10-7', 'Divine Comedy', 'Dante Alighieri'],
    self.table_separator(),
    [self.table_cell('This value spans 3 columns.', colspan=3)]
])

table.render()

This results in:

.. code-block:: text

+---------------+---------------+-----------------+
| ISBN | Title | Author |
+---------------+---------------+-----------------+
| 99921-58-10-7 | Divine Comedy | Dante Alighieri |
+---------------+---------------+-----------------+
| This value spans 3 columns. |
+---------------+---------------+-----------------+

.. tip::

You can create a multiple-line page title using a header cell that spans the entire table width:

.. code-block:: python

    table.set_headers([
        [self.table_cell('Main table title', colspan=3)],
        ['ISBN', 'Title', 'Author']
    ])

This generate:

.. code-block:: text

    +-------+-------+--------+
    | Main table title |
    +-------+-------+--------+
    | ISBN | Title | Author |
    +-------+-------+--------+
    | ... |
    +-------+-------+--------+

In a similar way you can span multiple rows:

.. code-block:: python

table = self.table()

table.set_headers(['ISBN', 'Title', 'Author'])
table.set_rows([
    [
        '978-0521567817',
        'De Monarchia',
        self.table_cell('Dante Alighieri\nspans multiple rows', rowspan=2)
    ]
])

table.render()

This outputs:

.. code-block:: text

+----------------+---------------+---------------------+
| ISBN | Title | Author |
+----------------+---------------+---------------------+
| 978-0521567817 | De Monarchia | Dante Alighieri |
| 978-0804169127 | Divine Comedy | spans multiple rows |
+----------------+---------------+---------------------+

You can use the colspan and rowspan options at the same time
which allows you to create any table layout you may wish.