Skip to main content

pytablewriter is a Python library to write a table in various formats: CSV / Elasticsearch / HTML / JavaScript / JSON / LaTeX / LDJSON / LTSV / Markdown / MediaWiki / NumPy / Excel / Pandas / Python / reStructuredText / SQLite / TOML / TSV / YAML.

Project description

Summary

pytablewriter is a Python library to write a table in various formats: CSV / Elasticsearch / HTML / JavaScript / JSON / LaTeX / LDJSON / LTSV / Markdown / MediaWiki / NumPy / Excel / Pandas / Python / reStructuredText / SQLite / TOML / TSV / YAML.

PyPI package version Supported Python versions Supported Python implementations Linux/macOS CI status Windows CI status Test coverage GitHub stars

Features

  • Write a table in various formats:
  • Automatic tabular data formatting
    • Alignment
    • Padding
    • Decimal places of numbers
  • Configure cell styles:
    • Text/Background color
    • Text alignment
    • Font size/weight
    • Thousand separator for numbers: e.g. 1,000/1 000
  • Configure output:
    • Write table to a stream such as a file/standard-output/string-buffer/Jupyter-Notebook
    • Get rendered tabular text
  • Data source
  • Multibyte character support
  • ANSI color support

Examples

Write tables

Write a Markdown table

Sample Code:
from pytablewriter import MarkdownTableWriter

def main():
    writer = MarkdownTableWriter()
    writer.table_name = "example_table"
    writer.headers = ["int", "float", "str", "bool", "mix", "time"]
    writer.value_matrix = [
        [0,   0.1,      "hoge", True,   0,      "2017-01-01 03:04:05+0900"],
        [2,   "-2.23",  "foo",  False,  None,   "2017-12-23 45:01:23+0900"],
        [3,   0,        "bar",  "true",  "inf", "2017-03-03 33:44:55+0900"],
        [-10, -9.9,     "",     "FALSE", "nan", "2017-01-01 00:00:00+0900"],
    ]

    writer.write_table()

if __name__ == "__main__":
    main()
Output:
# example_table
|int|float|str |bool |  mix   |          time          |
|--:|----:|----|-----|-------:|------------------------|
|  0| 0.10|hoge|True |       0|2017-01-01 03:04:05+0900|
|  2|-2.23|foo |False|        |2017-12-23 12:34:51+0900|
|  3| 0.00|bar |True |Infinity|2017-03-03 22:44:55+0900|
|-10|-9.90|    |False|     NaN|2017-01-01 00:00:00+0900|
Rendering Result:
 
markdown_ss

Rendered markdown at GitHub

Write a Markdown table with a margin
Sample Code:
from pytablewriter import MarkdownTableWriter

def main():
    writer = MarkdownTableWriter()
    writer.table_name = "write example with a margin"
    writer.headers = ["int", "float", "str", "bool", "mix", "time"]
    writer.value_matrix = [
        [0,   0.1,      "hoge", True,   0,      "2017-01-01 03:04:05+0900"],
        [2,   "-2.23",  "foo",  False,  None,   "2017-12-23 45:01:23+0900"],
        [3,   0,        "bar",  "true",  "inf", "2017-03-03 33:44:55+0900"],
        [-10, -9.9,     "",     "FALSE", "nan", "2017-01-01 00:00:00+0900"],
    ]
    writer.margin = 1  # add a whitespace for both sides of each cell

    writer.write_table()

if __name__ == "__main__":
    main()
Output:
# write example with a margin
| int | float | str  | bool  |   mix    |           time           |
|----:|------:|------|-------|---------:|--------------------------|
|   0 |  0.10 | hoge | True  |        0 | 2017-01-01 03:04:05+0900 |
|   2 | -2.23 | foo  | False |          | 2017-12-23 12:34:51+0900 |
|   3 |  0.00 | bar  | True  | Infinity | 2017-03-03 22:44:55+0900 |
| -10 | -9.90 |      | False |      NaN | 2017-01-01 00:00:00+0900 |

margin attribute can be available for all of the text format writer classes.

Write a reStructuredText table (Grid Tables)

Sample Code:
import pytablewriter

def main():
    writer = pytablewriter.RstGridTableWriter()
    writer.table_name = "example_table"
    writer.headers = ["int", "float", "str", "bool", "mix", "time"]
    writer.value_matrix = [
        [0,   0.1,      "hoge", True,   0,      "2017-01-01 03:04:05+0900"],
        [2,   "-2.23",  "foo",  False,  None,   "2017-12-23 45:01:23+0900"],
        [3,   0,        "bar",  "true",  "inf", "2017-03-03 33:44:55+0900"],
        [-10, -9.9,     "",     "FALSE", "nan", "2017-01-01 00:00:00+0900"],
    ]

    writer.write_table()

if __name__ == "__main__":
    main()
Output:
.. table:: example_table

    +---+-----+----+-----+--------+------------------------+
    |int|float|str |bool |  mix   |          time          |
    +===+=====+====+=====+========+========================+
    |  0| 0.10|hoge|True |       0|2017-01-01 03:04:05+0900|
    +---+-----+----+-----+--------+------------------------+
    |  2|-2.23|foo |False|        |2017-12-23 12:34:51+0900|
    +---+-----+----+-----+--------+------------------------+
    |  3| 0.00|bar |True |Infinity|2017-03-03 22:44:55+0900|
    +---+-----+----+-----+--------+------------------------+
    |-10|-9.90|    |False|     NaN|2017-01-01 00:00:00+0900|
    +---+-----+----+-----+--------+------------------------+
Rendering Result:
 
example_table
int float str bool mix time
0 0.10 hoge True 0 2017-01-01 03:04:05+0900
2 -2.23 foo False   2017-12-23 12:34:51+0900
3 0.00 bar True Infinity 2017-03-03 22:44:55+0900
-10 -9.90   False NaN 2017-01-01 00:00:00+0900

Write a table with JavaScript format (as a nested list variable definition)

Sample Code:
import pytablewriter

def main():
    writer = pytablewriter.JavaScriptTableWriter()
    writer.table_name = "example_table"
    writer.headers = ["int", "float", "str", "bool", "mix", "time"]
    writer.value_matrix = [
        [0,   0.1,      "hoge", True,   0,      "2017-01-01 03:04:05+0900"],
        [2,   "-2.23",  "foo",  False,  None,   "2017-12-23 45:01:23+0900"],
        [3,   0,        "bar",  "true",  "inf", "2017-03-03 33:44:55+0900"],
        [-10, -9.9,     "",     "FALSE", "nan", "2017-01-01 00:00:00+0900"],
    ]

    writer.write_table()

if __name__ == "__main__":
    main()
Output:
const example_table = [
    ["int", "float", "str", "bool", "mix", "time"],
    [0, 0.10, "hoge", true, 0, "2017-01-01 03:04:05+0900"],
    [2, -2.23, "foo", false, null, "2017-12-23 12:34:51+0900"],
    [3, 0.00, "bar", true, Infinity, "2017-03-03 22:44:55+0900"],
    [-10, -9.90, "", false, NaN, "2017-01-01 00:00:00+0900"]
];

Write a table to an Excel sheet

Sample Code:
from pytablewriter import ExcelXlsxTableWriter

def main():
    writer = ExcelXlsxTableWriter()
    writer.table_name = "example"
    writer.headers = ["int", "float", "str", "bool", "mix", "time"]
    writer.value_matrix = [
        [0,   0.1,      "hoge", True,   0,      "2017-01-01 03:04:05+0900"],
        [2,   "-2.23",  "foo",  False,  None,   "2017-12-23 12:34:51+0900"],
        [3,   0,        "bar",  "true",  "inf", "2017-03-03 22:44:55+0900"],
        [-10, -9.9,     "",     "FALSE", "nan", "2017-01-01 00:00:00+0900"],
    ]
    writer.dump("sample.xlsx")

if __name__ == "__main__":
    main()
Output:
excel_single

Output excel file (sample_single.xlsx)

Write a Unicode table

Sample Code:
from pytablewriter import UnicodeTableWriter

def main():
    writer = UnicodeTableWriter()
    writer.table_name = "example_table"
    writer.headers = ["int", "float", "str", "bool", "mix", "time"]
    writer.value_matrix = [
        [0,   0.1,      "hoge", True,   0,      "2017-01-01 03:04:05+0900"],
        [2,   "-2.23",  "foo",  False,  None,   "2017-12-23 45:01:23+0900"],
        [3,   0,        "bar",  "true",  "inf", "2017-03-03 33:44:55+0900"],
        [-10, -9.9,     "",     "FALSE", "nan", "2017-01-01 00:00:00+0900"],
    ]

    writer.write_table()

if __name__ == "__main__":
    main()
Output:
┌───┬─────┬────┬─────┬────────┬────────────────────────┐
│int│float│str │bool │  mix   │          time          │
├───┼─────┼────┼─────┼────────┼────────────────────────┤
│  0│ 0.10│hoge│True │       0│2017-01-01 03:04:05+0900│
├───┼─────┼────┼─────┼────────┼────────────────────────┤
│  2│-2.23│foo │False│        │2017-12-23 12:34:51+0900│
├───┼─────┼────┼─────┼────────┼────────────────────────┤
│  3│ 0.00│bar │True │Infinity│2017-03-03 22:44:55+0900│
├───┼─────┼────┼─────┼────────┼────────────────────────┤
│-10│-9.90│    │False│     NaN│2017-01-01 00:00:00+0900│
└───┴─────┴────┴─────┴────────┴────────────────────────┘

Write a Markdown table from pandas.DataFrame instance

from_dataframe method of writer classes will set up tabular data from pandas.DataFrame:

Sample Code:
from textwrap import dedent
import pandas as pd
import io
from pytablewriter import MarkdownTableWriter

def main():
    csv_data = io.StringIO(dedent("""\
        "i","f","c","if","ifc","bool","inf","nan","mix_num","time"
        1,1.10,"aa",1.0,"1",True,Infinity,NaN,1,"2017-01-01 00:00:00+09:00"
        2,2.20,"bbb",2.2,"2.2",False,Infinity,NaN,Infinity,"2017-01-02 03:04:05+09:00"
        3,3.33,"cccc",-3.0,"ccc",True,Infinity,NaN,NaN,"2017-01-01 00:00:00+09:00"
        """))
    df = pd.read_csv(csv_data, sep=',')

    writer = MarkdownTableWriter()
    writer.from_dataframe(df)
    writer.write_table()

if __name__ == "__main__":
    main()
Output:
| i | f  | c  | if |ifc|bool |  inf   |nan|mix_num |          time           |
|--:|---:|----|---:|---|-----|--------|---|-------:|-------------------------|
|  1|1.10|aa  | 1.0|  1|True |Infinity|NaN|       1|2017-01-01 00:00:00+09:00|
|  2|2.20|bbb | 2.2|2.2|False|Infinity|NaN|Infinity|2017-01-02 03:04:05+09:00|
|  3|3.33|cccc|-3.0|ccc|True |Infinity|NaN|     NaN|2017-01-01 00:00:00+09:00|

Adding a column of the DataFrame index if you specify add_index_column=True:

Sample Code:
import pandas as pd
from pytablewriter import MarkdownTableWriter

def main():
    writer = MarkdownTableWriter()
    writer.table_name = "add_index_column"
    writer.from_dataframe(
        pd.DataFrame({"A": [1, 2], "B": [10, 11]}, index=["a", "b"]),
        add_index_column=True,
    )
    writer.write_table()

if __name__ == "__main__":
    main()
Output:
# add_index_column
|   | A | B |
|---|--:|--:|
|a  |  1| 10|
|b  |  2| 11|

Write a markdown table from a space-separated values

Sample Code:
from textwrap import dedent
import pytablewriter

def main():
    writer = pytablewriter.MarkdownTableWriter()
    writer.table_name = "ps"
    writer.from_csv(
        dedent("""\
            USER       PID %CPU %MEM    VSZ   RSS TTY      STAT START   TIME COMMAND
            root         1  0.0  0.4  77664  8784 ?        Ss   May11   0:02 /sbin/init
            root         2  0.0  0.0      0     0 ?        S    May11   0:00 [kthreadd]
            root         4  0.0  0.0      0     0 ?        I<   May11   0:00 [kworker/0:0H]
            root         6  0.0  0.0      0     0 ?        I<   May11   0:00 [mm_percpu_wq]
            root         7  0.0  0.0      0     0 ?        S    May11   0:01 [ksoftirqd/0]
        """),
        delimiter=" ")
    writer.write_table()

if __name__ == "__main__":
    main()
Output:
# ps
|USER|PID|%CPU|%MEM| VSZ |RSS |TTY|STAT|START|TIME|   COMMAND    |
|----|--:|---:|---:|----:|---:|---|----|-----|----|--------------|
|root|  1|   0| 0.4|77664|8784|?  |Ss  |May11|0:02|/sbin/init    |
|root|  2|   0| 0.0|    0|   0|?  |S   |May11|0:00|[kthreadd]    |
|root|  4|   0| 0.0|    0|   0|?  |I<  |May11|0:00|[kworker/0:0H]|
|root|  6|   0| 0.0|    0|   0|?  |I<  |May11|0:00|[mm_percpu_wq]|
|root|  7|   0| 0.0|    0|   0|?  |S   |May11|0:01|[ksoftirqd/0] |

Get rendered tabular text as str

dumps method returns rendered tabular text. dumps only available for text format writers.

Sample Code:
import pytablewriter

def main():
    writer = pytablewriter.MarkdownTableWriter()
    writer.headers = ["int", "float", "str", "bool", "mix", "time"]
    writer.value_matrix = [
        [0,   0.1,      "hoge", True,   0,      "2017-01-01 03:04:05+0900"],
        [2,   "-2.23",  "foo",  False,  None,   "2017-12-23 45:01:23+0900"],
        [3,   0,        "bar",  "true",  "inf", "2017-03-03 33:44:55+0900"],
        [-10, -9.9,     "",     "FALSE", "nan", "2017-01-01 00:00:00+0900"],
    ]

    print(writer.dumps())

if __name__ == "__main__":
    main()
Output:
|int|float|str |bool |  mix   |          time          |
|--:|----:|----|-----|-------:|------------------------|
|  0| 0.10|hoge|True |       0|2017-01-01 03:04:05+0900|
|  2|-2.23|foo |False|        |2017-12-23 45:01:23+0900|
|  3| 0.00|bar |True |Infinity|2017-03-03 33:44:55+0900|
|-10|-9.90|    |False|     NaN|2017-01-01 00:00:00+0900|

Configure table styles

Column styles

Writers can specify Style for each column by column_styles attribute of writer classes.

Sample Code:
from pytablewriter import MarkdownTableWriter
from pytablewriter.style import Style

def main():
    writer = MarkdownTableWriter()
    writer.table_name = "set style by column_styles"
    writer.headers = [
        "auto align",
        "left align",
        "center align",
        "bold",
        "italic",
        "bold italic ts",
    ]
    writer.value_matrix = [
        [11, 11, 11, 11, 11, 11],
        [1234, 1234, 1234, 1234, 1234, 1234],
    ]

    # specify styles for each column
    writer.column_styles = [
        Style(),
        Style(align="left"),
        Style(align="center"),
        Style(font_weight="bold"),
        Style(font_style="italic"),
        Style(font_weight="bold", font_style="italic", thousand_separator=","),
    ]

    writer.write_table()

if __name__ == "__main__":
    main()
Output:
# set style by styles
|auto align|left align|center align|  bold  |italic|bold italic ts|
|---------:|----------|:----------:|-------:|-----:|-------------:|
|        11|11        |     11     |  **11**|  _11_|      _**11**_|
|      1234|1234      |    1234    |**1234**|_1234_|   _**1,234**_|

Rendering result

You can also set Style to a specific column with index or header by using set_style method:

Sample Code:
from pytablewriter import MarkdownTableWriter
from pytablewriter.style import Style

def main():
    writer = MarkdownTableWriter()
    writer.headers = ["A", "B", "C",]
    writer.value_matrix = [[11, 11, 11], [1234, 1234, 1234]]

    writer.table_name = "set style by column index"
    writer.set_style(1, Style(align="center", font_weight="bold"))
    writer.set_style(2, Style(thousand_separator=" "))
    writer.write_table()
    writer.write_null_line()

    writer.table_name = "set style by header"
    writer.set_style("B", Style(font_style="italic"))
    writer.write_table()

if __name__ == "__main__":
    main()
Output:
# set style by column index
| A  |   B    |  C  |
|---:|:------:|----:|
|  11| **11** |   11|
|1234|**1234**|1 234|

# set style by header
| A  |  B   |  C  |
|---:|-----:|----:|
|  11|  _11_|   11|
|1234|_1234_|1 234|

Style filter

Example:

true_color_and_styles

Multibyte character support

Write a table using multibyte character

You can use multibyte characters as table data. Multibyte characters also properly padded and aligned.

Sample Code:
import pytablewriter

def main():
    writer = pytablewriter.RstSimpleTableWriter()
    writer.table_name = "生成に関するパターン"
    writer.headers = ["パターン名", "概要", "GoF", "Code Complete[1]"]
    writer.value_matrix = [
        ["Abstract Factory", "関連する一連のインスタンスを状況に応じて、適切に生成する方法を提供する。", "Yes", "Yes"],
        ["Builder", "複合化されたインスタンスの生成過程を隠蔽する。", "Yes", "No"],
        ["Factory Method", "実際に生成されるインスタンスに依存しない、インスタンスの生成方法を提供する。", "Yes", "Yes"],
        ["Prototype", "同様のインスタンスを生成するために、原型のインスタンスを複製する。", "Yes", "No"],
        ["Singleton", "あるクラスについて、インスタンスが単一であることを保証する。", "Yes", "Yes"],
    ]
    writer.write_table()

if __name__ == "__main__":
    main()
Output:
multi_byte_char_table

Output of multi-byte character table

Multi processing

You can increase the number of workers to process table data via max_workers attribute of a writer. The more max_workers the less processing time when tabular data is large and the execution environment has available cores.

if you increase max_workers larger than one, recommend to use main guarded as follows to avoid problemes caused by multi processing:

from multiprocessing import cpu_count
import pytablewriter as ptw

def main():
    writer = ptw.MarkdownTableWriter()
    writer.max_workers = cpu_count()
    ...

if __name__ == "__main__":
    main()

Installation

Installation: pip

pip install pytablewriter

Some of the formats require additional dependency packages, you can install these packages as follows:

  • Elasticsearch
    • pip install pytablewriter[es7] or pip install pytablewriter[es6]
  • Excel
    • pip install pytablewriter[excel]
  • HTML
    • pip install pytablewriter[html]
  • SQLite
    • pip install pytablewriter[sqlite]
  • TOML
    • pip install pytablewriter[toml]
  • Install all of the optioanal dependencies
    • pip install pytablewriter[all]

Installation: apt

sudo add-apt-repository ppa:thombashi/ppa
sudo apt update
sudo apt install python3-pytablewriter

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.

Files for pytablewriter, version 0.55.0
Filename, size File type Python version Upload date Hashes
Filename, size pytablewriter-0.55.0-py3-none-any.whl (93.4 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size pytablewriter-0.55.0.tar.gz (181.7 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page