Quick and easy display of tabular data with optional ANSI color and borders.
Project description
- GitHub repository: https://github.com/petercorke/ansitable
- Dependencies:
colored
ANSI table
Painless creation of nice-looking tables of data for Python.
Starting simple
1 | from ansitable import ANSITable, Column
2 |
3 | table = ANSITable("col1", "column 2 has a big header", "column 3")
4 | table.row("aaaaaaaaa", 2.2, 3)
5 | table.row("bbbbbbbbbbbbb", 5.5, 6)
6 | table.row("ccccccc", 8.8, 9)
7 | table.print()
Line 3 construct an ANSITable
object and the arguments are a sequence of
column names followed by ANSITable
keyword arguments - there are none in this first example. Since there are three column objects this this will be a 3-column table.
Lines 4-6 add rows, 3 data values for each row.
Line 7 prints the table and yields a tabular display with column widths automatically chosen, and headings and column data all left-justified (default)
col1 column 2 has a big header column 3
aaaaaaaaa 2.2 3
bbbbbbbbbbbbb 5.5 6
ccccccc 8.8 9
we can provide a file
option to print()
to allow writing to an output stream, the
default is stdout
.
The more general solution is to provide a sequence of Column
objects which
allows many column specific options to be given, as we shall see later.
For now though, we could rewrite the example above as:
table = ANSITable(
Column("col1"),
Column("column 2 has a big header"),
Column("column 3")
)
or as
table = ANSITable()
table.addcolumn("col1")
table.addcolumn("column 2 has a big header")
table.addcolumn("column 3")
We can specify a Python format()
style format string for any column - by default it
is the general formatting option "{}"
table = ANSITable(
Column("col1"),
Column("column 2 has a big header", "{:.3g}"), # CHANGE
Column("column 3", "{:-10.4f}")
)
table.row("aaaaaaaaa", 2.2, 3)
table.row("bbbbbbbbbbbbb", 5.5, 6)
table.row("ccccccc", 8.8, 9)
table.print()
which yields
col1 column 2 has a big header column 3
aaaaaaaaa 2.2 3.0000
bbbbbbbbbbbbb 5.5 6.0000
ccccccc 8.8 9.0000
Alternatively we can specify a formatter
argument which is a function that converts
the value to a string.
The data in column 1 is quite long, we might wish to set a maximum column width which
we can do using the width
argument
table = ANSITable(
Column("col1", width=10), # CHANGE
Column("column 2 has a big header", "{:.3g}"),
Column("column 3", "{:-10.4f}")
)
table.row("aaaaaaaaa", 2.2, 3)
table.row("bbbbbbbbbbbbb", 5.5, 6)
table.row("ccccccc", 8.8, 9)
table.print()
which yields
col1 column 2 has a big header column 3
aaaaaaaaa 2.2 3.0000
bbbbbbb... 5.5 6.0000
ccccccc 8.8 9.0000
where we see that the data in column 1 has been truncated.
If you don't like the ellipsis you can turn it off, and get to see three more
charaters, with the ANSITable
option ellipsis=False
.
Borders
We can add a table border made up of regular ASCII characters
table = ANSITable(
Column("col1"),
Column("column 2 has a big header"),
Column("column 3"),
border="ascii" # CHANGE
)
table.row("aaaaaaaaa", 2.2, 3)
table.row("bbbbbbbbbbbbb", 5.5, 6)
table.row("ccccccc", 8.8, 9)
table.print()
which yields
+--------------+---------------------------+----------+
| col1 | column 2 has a big header | column 3 |
+--------------+---------------------------+----------+
| aaaaaaaaa | 2.2 | 3 |
|bbbbbbbbbbbbb | 5.5 | 6 |
| ccccccc | 8.8 | 9 |
+--------------+---------------------------+----------+
Or we can construct a border using the ANSI box-drawing characters which are supported by most terminal emulators
table = ANSITable(
Column("col1"),
Column("column 2 has a big header"),
Column("column 3"),
border="thick" # CHANGE
)
table.row("aaaaaaaaa", 2.2, 3)
table.row("bbbbbbbbbbbbb", 5.5, 6)
table.row("ccccccc", 8.8, 9)
table.print()
which yields
┏━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┓
┃ col1 ┃ column 2 has a big header ┃ column 3 ┃
┣━━━━━━━━━━━━━━╋━━━━━━━━━━━━━━━━━━━━━━━━━━━╋━━━━━━━━━━┫
┃ aaaaaaaaa ┃ 2.2 ┃ 3 ┃
┃bbbbbbbbbbbbb ┃ 5.5 ┃ 6 ┃
┃ ccccccc ┃ 8.8 ┃ 9 ┃
┗━━━━━━━━━━━━━━┻━━━━━━━━━━━━━━━━━━━━━━━━━━━┻━━━━━━━━━━┛
which actually looks better on the console than it does in GitHub markdown.
Other border options include "thin", "rounded" (thin with round corners) and "double".
Header and column alignment
We can change the alignment of data and heading for any column with the alignment flags "<" (left), ">" (right) and "^" (centered).
table = ANSITable(
Column("col1"),
Column("column 2 has a big header", colalign="^"), # CHANGE
Column("column 3"),
border="thick"
)
table.row("aaaaaaaaa", 2.2, 3)
table.row("bbbbbbbbbbbbb", 5.5, 6)
table.row("ccccccc", 8.8, 9)
table.print()
which yields
┏━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┓
┃ col1 ┃ column 2 has a big header ┃ column 3 ┃
┣━━━━━━━━━━━━━━╋━━━━━━━━━━━━━━━━━━━━━━━━━━━╋━━━━━━━━━━┫
┃ aaaaaaaaa ┃ 2.2 ┃ 3 ┃
┃bbbbbbbbbbbbb ┃ 5.5 ┃ 6 ┃
┃ ccccccc ┃ 8.8 ┃ 9 ┃
┗━━━━━━━━━━━━━━┻━━━━━━━━━━━━━━━━━━━━━━━━━━━┻━━━━━━━━━━┛
where the data for column 2 has been centered.
Heading and data alignment for any column can be set independently
table = ANSITable(
Column("col1", headalign="<"), # CHANGE
Column("column 2 has a big header", colalign="^"),
Column("column 3", colalign="<"), # CHANGE
border="thick"
)
table.row("aaaaaaaaa", 2.2, 3)
table.row("bbbbbbbbbbbbb", 5.5, 6)
table.row("ccccccc", 8.8, 9)
table.print()
yields
┏━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┓
┃col1 ┃ column 2 has a big header ┃ column 3 ┃
┣━━━━━━━━━━━━━━╋━━━━━━━━━━━━━━━━━━━━━━━━━━━╋━━━━━━━━━━┫
┃ aaaaaaaaa ┃ 2.2 ┃ 3 ┃
┃bbbbbbbbbbbbb ┃ 5.5 ┃ 6 ┃
┃ ccccccc ┃ 8.8 ┃ 9 ┃
┗━━━━━━━━━━━━━━┻━━━━━━━━━━━━━━━━━━━━━━━━━━━┻━━━━━━━━━━┛
where we have left-justified the heading for column 1 and the data for column 3.
Color
If you have the colored
package installed then you can set the foreground and
background color and style (bold, reverse, underlined, dim) of the header and column data, as well as the border color.
table = ANSITable(
Column("col1", headalign="<", colcolor="red", headstyle="underlined"), # CHANGE
Column("column 2 has a big header", colalign="^", colstyle="reverse"), # CHANGE
Column("column 3", colalign="<", colbgcolor="green"), # CHANGE
border="thick", bordercolor="blue" # CHANGE
)
table.row("aaaaaaaaa", 2.2, 3)
table.row("bbbbbbbbbbbbb", 5.5, 6)
table.row("ccccccc", 8.8, 9)
table.print()
which yields
All options
ANSITable
These keyword arguments control the styling of the entire table.
Keyword | Default | Purpose |
---|---|---|
colsep | 2 | Gap between columns (in spaces) |
offset | 0 | Gap at start of each row, shifts the table to the left |
border | no border | Border style |
bordercolor | Border color, see possible values | |
ellipsis | True | Add an ellipsis if a wide column is truncated |
Column
These keyword arguments control the styling of a single column.
Keyword | Default | Purpose |
---|---|---|
fmt | "{}" | format string for the column value, or a callable that maps the column value to a string |
width | maximum column width, excess will be truncated | |
colcolor | Text color, see possible values | |
colbgcolor | Text background color, see possible values | |
colstyle | Text style: "bold", "underlined", "reverse", "dim", "blink" | |
colalign | ">" | Text alignment: ">" (left), "<" (right), "^" (centered) |
headcolor | Heading text color, see possible values | |
headbgcolor | Heading text background color, see possible values | |
headstyle | Heading text style: "bold", "underlined", "reverse", "dim", "blink" | |
headalign | ">" | Heading text alignment: ">" (left), "<" (right), "^" (centered) |
Note that many terminal emulators do not support the "blink" style.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.