Table

Click Extra provides a way to render tables in the terminal.

Here how to use the standalone table rendering option decorator:

from click_extra import command, echo, pass_context, table_format_option

@command
@table_format_option
@pass_context
def table_command(ctx):
    data = ((1, 87), (2, 80), (3, 79))
    headers = ("day", "temperature")
    ctx.print_table(data, headers)

As you can see above, this option adds a ready-to-use print_table() method to the context object.

The default help message for this option list all available table formats:

$ table-command --help
Usage: table-command [OPTIONS]

Options:
  -t, --table-format [asciidoc|csv|csv-excel|csv-excel-tab|csv-unix|double_grid|double_outline|fancy_grid|fancy_outline|github|grid|heavy_grid|heavy_outline|html|jira|latex|latex_booktabs|latex_longtable|latex_raw|mediawiki|mixed_grid|mixed_outline|moinmoin|orgtbl|outline|pipe|plain|presto|pretty|psql|rounded_grid|rounded_outline|rst|simple|simple_grid|simple_outline|textile|tsv|unsafehtml|vertical|youtrack]
          Rendering style of tables.
  --help  Show this message and exit.

So you can use the --table-format option to change the table format:

$ table-command --table-format fancy_outline
╒═════╤═════════════╕
│ day │ temperature │
╞═════╪═════════════╡
│ 1   │ 87          │
│ 2   │ 80          │
│ 3   │ 79          │
╘═════╧═════════════╛

$ table-command --table-format jira
|| day || temperature ||
| 1   | 87          |
| 2   | 80          |
| 3   | 79          |

Table formats

Available table formats are inherited from python-tabulate.

This list is augmented with extra formats:

  • csv

  • csv-excel

  • csv-excel-tab

  • csv-unix

  • vertical

Todo

Explicitly list all formats IDs and render an example of each format.

Todo

Explain extra parameters supported by print_table() for each category of formats.

Get table format

You can get the ID of the current table format from the context:

from click_extra import command, echo, pass_context, table_format_option

@command
@table_format_option
@pass_context
def vanilla_command(ctx):
    format_id = ctx.meta["click_extra.table_format"]
    echo(f"Table format: {format_id}")

    data = ((1, 87), (2, 80), (3, 79))
    headers = ("day", "temperature")
    ctx.print_table(data, headers)

$ vanilla-command --table-format fancy_outline
Table format: fancy_outline
╒═════╤═════════════╕
│ day │ temperature │
╞═════╪═════════════╡
│ 1   │ 87          │
│ 2   │ 80          │
│ 3   │ 79          │
╘═════╧═════════════╛

click_extra.tabulate API

        classDiagram
  ExtraOption <|-- TableFormatOption

Collection of table rendering utilities.

click_extra.tabulate.output_formats: list[str] = ['asciidoc', 'csv', 'csv-excel', 'csv-excel-tab', 'csv-unix', 'double_grid', 'double_outline', 'fancy_grid', 'fancy_outline', 'github', 'grid', 'heavy_grid', 'heavy_outline', 'html', 'jira', 'latex', 'latex_booktabs', 'latex_longtable', 'latex_raw', 'mediawiki', 'mixed_grid', 'mixed_outline', 'moinmoin', 'orgtbl', 'outline', 'pipe', 'plain', 'presto', 'pretty', 'psql', 'rounded_grid', 'rounded_outline', 'rst', 'simple', 'simple_grid', 'simple_outline', 'textile', 'tsv', 'unsafehtml', 'vertical', 'youtrack']

All output formats supported by click-extra.

click_extra.tabulate.get_csv_dialect(format_id)[source]

Extract, validate and normalize CSV dialect ID from format.

Return type:

str | None

click_extra.tabulate.render_csv(tabular_data, headers=(), **kwargs)[source]
Return type:

None

click_extra.tabulate.render_vertical(tabular_data, headers=(), **kwargs)[source]

Re-implements cli-helpers’s vertical table layout.

See cli-helpers source for reference.

Return type:

None

click_extra.tabulate.render_table(tabular_data, headers=(), **kwargs)[source]

Render a table with tabulate and output it via echo.

Return type:

None

class click_extra.tabulate.TableFormatOption(param_decls=None, type=Choice(['asciidoc', 'csv', 'csv-excel', 'csv-excel-tab', 'csv-unix', 'double_grid', 'double_outline', 'fancy_grid', 'fancy_outline', 'github', 'grid', 'heavy_grid', 'heavy_outline', 'html', 'jira', 'latex', 'latex_booktabs', 'latex_longtable', 'latex_raw', 'mediawiki', 'mixed_grid', 'mixed_outline', 'moinmoin', 'orgtbl', 'outline', 'pipe', 'plain', 'presto', 'pretty', 'psql', 'rounded_grid', 'rounded_outline', 'rst', 'simple', 'simple_grid', 'simple_outline', 'textile', 'tsv', 'unsafehtml', 'vertical', 'youtrack']), default='rounded_outline', expose_value=False, help='Rendering style of tables.', **kwargs)[source]

Bases: ExtraOption

A pre-configured option that is adding a -t/--table-format flag to select the rendering style of a table.

The selected table format ID is made available in the context in ctx.meta["click_extra.table_format"].

init_formatter(ctx, param, value)[source]

Save table format ID in the context, and adds print_table() to it.

The print_table(tabular_data, headers) method added to the context is a ready-to-use helper that takes for parameters: - tabular_data, a 2-dimensional iterable of iterables for cell values, - headers, a list of string to be used as headers.

Return type:

None