python-tabulate

Tabulate is a small, focused Python library that turns lists of lists, dicts, NumPy arrays, and pandas DataFrames into readable, aligned plain-text tables. A single tabulate() call handles column alignment, numeric formatting, and header rendering, so developers can print clean tabular output in scripts, CLIs, and notebooks without hand-rolling padding logic.

Its standout feature is breadth of output formats: over 30 table styles ranging from plain and simple text to GitHub-flavored Markdown, reStructuredText, HTML, LaTeX, and Jira/Confluence markup, plus a suite of Unicode box-drawing grids (simple, rounded, heavy, mixed, double, fancy). This makes it equally useful for quick debugging output and for generating tables destined for documentation or reports.

Beyond the Python API, the package installs a tabulate command-line utility that reads CSV, TSV, or JSON-lines data from a file or stdin and renders it in any supported format, making it a handy piece of any shell pipeline for inspecting tabular data.

What You Get

• A single tabulate() function that accepts lists of lists, lists of dicts, dicts of iterables, dataclasses, NumPy arrays/record arrays, and pandas DataFrames as input
• Over 30 output formats including plain, simple, github, grid variants (simple/rounded/heavy/mixed/double/fancy), pipe, orgtbl, html, latex, rst, jira, tsv, and more
• Automatic column alignment and numeric formatting, including decimal-point alignment and configurable float/int format strings
• A bundled tabulate CLI that reads RSV, CSV, or JSONL data from files or stdin and prints a formatted table
• Optional row-index columns (showindex) and support for embedding separating lines between groups of rows
• Optional wide-character (CJK) width support via the wcwidth extra for correctly aligned multi-byte text

Common Use Cases

• Printing debug or diagnostic tables from within a script without writing custom padding/alignment code
• Rendering a pandas DataFrame or NumPy array as a Markdown table for a README, notebook, or generated report
• Piping CSV or JSON-lines data through the tabulate CLI to get a readable table straight from the shell
• Generating LaTeX or reStructuredText tables for academic papers and Sphinx documentation from tabular data
• Formatting CLI tool output (e.g. listing resources, configs, or query results) in a consistent, readable grid

Under The Hood

Architecture The entire library lives in a single module, tabulate/__init__.py, which declares each of the 30+ output styles as a TableFormat namedtuple (line-drawing characters, row templates, padding rules) held in a dispatch table keyed by format name, alongside DataRow/Line primitives that describe how a rendered row or separator line looks. Column width calculation, alignment inference, and numeric formatting run as internal helper passes before a rendering function walks the format table to assemble the final string. The bundled cli.py is a thin argument-parsing wrapper that reads RSV/CSV/JSONL input and calls straight into the same tabulate() core, so the CLI and the importable API share one formatting path with no duplicated logic.

Tech Stack Pure Python (3.10+) with no required runtime dependencies; an optional wcwidth extra adds wide-character (CJK) alignment support. The package is built with the flit_core/flit_scm backend and versioned via setuptools_scm from git tags. Tests run under pytest with --doctest-modules and --doctest-glob=README.md, so the README’s own examples double as executable tests; tox/tox-uv drives the multi-version matrix and ruff handles linting.

Code Quality The test/ directory holds a dedicated suite (output, input, API, CLI, regression, textwrapper, grapheme-cluster tests) using plain assert-based pytest tests, run across a 5-Python-version by 3-OS CI matrix with a separate lint job and Codecov coverage reporting. Naming is consistent and internals are docstring-documented, though there is no static type checker (mypy) enforced and type hints are used sparingly.

API Design The public surface is deliberately tiny — one function (tabulate()) plus two small helpers (tabulate_formats, simple_separated_format) — so getting started requires no boilerplate beyond a single import and call. Keyword arguments (headers, tablefmt, floatfmt, showindex) cover nearly every customization need without subclassing or configuration objects, and accepting lists, dicts, DataFrames, and NumPy arrays interchangeably means callers rarely need to reshape their data before formatting it.