Skip to content

An intuitive and type-safe Python library for converting lists to fancy ASCII tables for displaying in the terminal or code-blocks

License

Notifications You must be signed in to change notification settings

DenverCoder1/table2ascii

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

table2ascii

build version downloads license discord

An intuitive and type-safe library for converting 2D Python lists to fancy ASCII/Unicode tables

Documentation and examples are available at table2ascii.rtfd.io

πŸ“₯ Installation

pip install -U table2ascii

Requirements: Python 3.7+

πŸ§‘β€πŸ’» Usage

πŸš€ Convert lists to ASCII tables

from table2ascii import table2ascii

output = table2ascii(
    header=["#", "G", "H", "R", "S"],
    body=[["1", "30", "40", "35", "30"], ["2", "30", "40", "35", "30"]],
    footer=["SUM", "130", "140", "135", "130"],
)

print(output)

"""
╔═════════════════════════════╗
β•‘  #     G     H     R     S  β•‘
β•Ÿβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β•’
β•‘  1    30    40    35    30  β•‘
β•‘  2    30    40    35    30  β•‘
β•Ÿβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β•’
β•‘ SUM   130   140   135   130 β•‘
β•šβ•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•
"""

πŸ† Set first or last column headings

from table2ascii import table2ascii

output = table2ascii(
    body=[["Assignment", "30", "40", "35", "30"], ["Bonus", "10", "20", "5", "10"]],
    first_col_heading=True,
)

print(output)

"""
╔════════════╦═══════════════════╗
β•‘ Assignment β•‘ 30   40   35   30 β•‘
β•‘    Bonus   β•‘ 10   20    5   10 β•‘
β•šβ•β•β•β•β•β•β•β•β•β•β•β•β•©β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•
"""

πŸ“° Set column widths and alignments

from table2ascii import table2ascii, Alignment

output = table2ascii(
    header=["Product", "Category", "Price", "Rating"],
    body=[
        ["Milk", "Dairy", "$2.99", "6.283"],
        ["Cheese", "Dairy", "$10.99", "8.2"],
        ["Apples", "Produce", "$0.99", "10.00"],
    ],
    column_widths=[12, 12, 12, 12],
    alignments=[Alignment.LEFT, Alignment.CENTER, Alignment.RIGHT, Alignment.DECIMAL],
)

print(output)

"""
╔═══════════════════════════════════════════════════╗
β•‘ Product       Category         Price     Rating   β•‘
β•Ÿβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β•’
β•‘ Milk           Dairy           $2.99      6.283   β•‘
β•‘ Cheese         Dairy          $10.99      8.2     β•‘
β•‘ Apples        Produce          $0.99     10.00    β•‘
β•šβ•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•
"""

🎨 Use a preset style

See a list of 30+ preset styles here.

from table2ascii import table2ascii, Alignment, PresetStyle

output = table2ascii(
    header=["First", "Second", "Third", "Fourth"],
    body=[["10", "30", "40", "35"], ["20", "10", "20", "5"]],
    column_widths=[10, 10, 10, 10],
    style=PresetStyle.ascii_box
)

print(output)

"""
+----------+----------+----------+----------+
|  First   |  Second  |  Third   |  Fourth  |
+----------+----------+----------+----------+
|    10    |    30    |    40    |    35    |
+----------+----------+----------+----------+
|    20    |    10    |    20    |    5     |
+----------+----------+----------+----------+
"""

output = table2ascii(
    header=["First", "Second", "Third", "Fourth"],
    body=[["10", "30", "40", "35"], ["20", "10", "20", "5"]],
    style=PresetStyle.plain,
    cell_padding=0,
    alignments=Alignment.LEFT,
)

print(output)

"""
First Second Third Fourth
10    30     40    35
20    10     20    5
"""

🎲 Define a custom style

Check TableStyle for more info and PresetStyle for examples.

from table2ascii import table2ascii, TableStyle

my_style = TableStyle.from_string("*-..*||:+-+:+     *''*")

output = table2ascii(
    header=["First", "Second", "Third"],
    body=[["10", "30", "40"], ["20", "10", "20"], ["30", "20", "30"]],
    style=my_style
)

print(output)

"""
*-------.--------.-------*
| First : Second : Third |
+-------:--------:-------+
|  10   :   30   :  40   |
|  20   :   10   :  20   |
|  30   :   20   :  30   |
*-------'--------'-------*
"""

πŸͺ„ Merge adjacent cells

from table2ascii import table2ascii, Merge, PresetStyle

output = table2ascii(
    header=["#", "G", "Merge", Merge.LEFT, "S"],
    body=[
        [1, 5, 6, 200, Merge.LEFT],
        [2, "E", "Long cell", Merge.LEFT, Merge.LEFT],
        ["Bonus", Merge.LEFT, Merge.LEFT, "F", "G"],
    ],
    footer=["SUM", "100", "200", Merge.LEFT, "300"],
    style=PresetStyle.double_thin_box,
    first_col_heading=True,
)

print(output)

"""
╔═════╦═════╀═══════╀═════╗
β•‘  #  β•‘  G  β”‚ Merge β”‚  S  β•‘
╠═════╬═════β•ͺ═══╀═══╧═════╣
β•‘  1  β•‘  5  β”‚ 6 β”‚   200   β•‘
β•Ÿβ”€β”€β”€β”€β”€β•«β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β•’
β•‘  2  β•‘  E  β”‚  Long cell  β•‘
β•Ÿβ”€β”€β”€β”€β”€β•¨β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”¬β”€β”€β”€β”¬β”€β”€β”€β”€β”€β•’
β•‘     Bonus     β”‚ F β”‚  G  β•‘
╠═════╦═════╀═══╧═══β•ͺ═════╣
β•‘ SUM β•‘ 100 β”‚  200  β”‚ 300 β•‘
β•šβ•β•β•β•β•β•©β•β•β•β•β•β•§β•β•β•β•β•β•β•β•§β•β•β•β•β•β•
"""

βš™οΈ Options

All parameters are optional. At least one of header, body, and footer must be provided.

Refer to the documentation for more information.

Option Supported Types Description
header Sequence[SupportsStr], None
(Default: None)
First table row seperated by header row separator. Values should support str()
body Sequence[Sequence[SupportsStr]], None
(Default: None)
2D List of rows for the main section of the table. Values should support str()
footer Sequence[SupportsStr], None
(Default: None)
Last table row seperated by header row separator. Values should support str()
column_widths Sequence[Optional[int]], None
(Default: None / automatic)
List of column widths in characters for each column
alignments Sequence[Alignment], Alignment, None
(Default: None / all centered)
Column alignments
(ex. [Alignment.LEFT, Alignment.CENTER, Alignment.RIGHT, Alignment.DECIMAL])
number_alignments Sequence[Alignment], Alignment, None
(Default: None)
Column alignments for numeric values. alignments will be used if not specified.
style TableStyle
(Default: double_thin_compact)
Table style to use for the table*
first_col_heading bool
(Default: False)
Whether to add a heading column separator after the first column
last_col_heading bool
(Default: False)
Whether to add a heading column separator before the last column
cell_padding int
(Default: 1)
The minimum number of spaces to add between the cell content and the cell border
use_wcwidth bool
(Default: True)
Whether to use wcwidth instead of len() to calculate cell width

*See a list of all preset styles here.

See the API Reference for more info.

πŸ‘¨β€πŸŽ¨ Use cases

πŸ—¨οΈ Discord messages and embeds

  • Display tables nicely inside markdown code blocks on Discord
  • Useful for making Discord bots with Discord.py

image

πŸ’» Terminal outputs

  • Tables display nicely whenever monospace fonts are fully supported
  • Tables make terminal outputs look more professional

image

πŸ€— Contributing

Contributions are welcome!

See CONTRIBUTING.md for more details on how to get involved.