Tabulate API Reference¶

Auto-generated API documentation for the tabulate module.

`tabulate` ¶

Tabulate — zero dependencies, stdlib only, Python 3.10+.

Pretty-print tabular data as formatted text tables. Supports multiple output formats (plain, simple, grid, pipe, github, orgtbl, pretty), flexible header modes, column alignment, number formatting, CJK-aware column widths, and various input data shapes.

Example::

from tabulate import tabulate

data = [["Alice", 24], ["Bob", 30]]
print(tabulate(data, headers=["Name", "Age"], tablefmt="grid"))
# +--------+-------+
# | Name   |   Age |
# +========+=======+
# | Alice  |    24 |
# | Bob    |    30 |
# +--------+-------+

`TableFormat` `dataclass` ¶

Defines the line/border/separator characters for one table style.

Source code in tabulate/tabulate.py

@dataclass(frozen=True, slots=True)
class TableFormat:
    """Defines the line/border/separator characters for one table style."""

    lineabove: _Line | None = None
    linebelowheader: _Line | None = None
    linebetweenrows: _Line | None = None
    linebelow: _Line | None = None
    headerrow: _DataRow | None = None
    datarow: _DataRow | None = None
    padding: int = 0
    with_header_hide: list[str] = field(default_factory=list)
    # When True, column width = max(data_max, header_width + MIN_PADDING)
    # When False (pretty), column width = max(data_max, header_width)
    header_pad_width: bool = True

`tabulate(tabular_data, headers=(), tablefmt='simple', floatfmt='g', numalign='decimal', stralign='left', missingval='', showindex=False, colalign=None)` ¶

Format tabular data as a pretty-printed text table.

Parameters:

Name	Type	Description	Default
`tabular_data`	`Any`	Input data. Accepted shapes: list of lists, list of dicts, dict of lists/values, or any iterable of iterables.	required
`headers`	`Any`	Column headers. Can be a list/tuple of strings, `"firstrow"` (use first data row), `"keys"` (use dict keys or column indices), or an empty tuple for no headers.	`()`
`tablefmt`	`str`	Output format name — one of `"plain"`, `"simple"`, `"grid"`, `"pipe"`, `"orgtbl"`, `"pretty"`, `"github"`.	`'simple'`
`floatfmt`	`str`	Format string for float values (passed to `format()`).	`'g'`
`numalign`	`str`	Default alignment for numeric columns (`"right"`, `"left"`, `"center"`, `"decimal"`).	`'decimal'`
`stralign`	`str`	Default alignment for text columns.	`'left'`
`missingval`	`str`	String to display in place of `None`.	`''`
`showindex`	`bool \| str \| Sequence`	If truthy, prepend row indices. Can be `True`, `"always"`, or a sequence of explicit index values.	`False`
`colalign`	`Sequence[str] \| None`	Per-column alignment overrides.	`None`

Returns:

Type	Description
`str`	The formatted table as a string.

Raises:

Type	Description
`ValueError`	If tablefmt is not recognised.

Example::

data = [["Alice", 24], ["Bob", 30]]
print(tabulate(data, headers=["Name", "Age"]))
# Name      Age
# ------  -----
# Alice      24
# Bob        30

Source code in tabulate/tabulate.py

def tabulate(
    tabular_data: Any,
    headers: Any = (),
    tablefmt: str = "simple",
    floatfmt: str = "g",
    numalign: str = "decimal",
    stralign: str = "left",
    missingval: str = "",
    showindex: bool | str | Sequence = False,
    colalign: Sequence[str] | None = None,
) -> str:
    """Format tabular data as a pretty-printed text table.

    Args:
        tabular_data: Input data.  Accepted shapes: list of lists, list of
            dicts, dict of lists/values, or any iterable of iterables.
        headers: Column headers.  Can be a list/tuple of strings,
            ``"firstrow"`` (use first data row), ``"keys"`` (use dict keys
            or column indices), or an empty tuple for no headers.
        tablefmt: Output format name — one of ``"plain"``, ``"simple"``,
            ``"grid"``, ``"pipe"``, ``"orgtbl"``, ``"pretty"``, ``"github"``.
        floatfmt: Format string for float values (passed to ``format()``).
        numalign: Default alignment for numeric columns (``"right"``,
            ``"left"``, ``"center"``, ``"decimal"``).
        stralign: Default alignment for text columns.
        missingval: String to display in place of ``None``.
        showindex: If truthy, prepend row indices.  Can be ``True``,
            ``"always"``, or a sequence of explicit index values.
        colalign: Per-column alignment overrides.

    Returns:
        The formatted table as a string.

    Raises:
        ValueError: If *tablefmt* is not recognised.

    Example::

        data = [["Alice", 24], ["Bob", 30]]
        print(tabulate(data, headers=["Name", "Age"]))
        # Name      Age
        # ------  -----
        # Alice      24
        # Bob        30
    """
    if tablefmt not in _table_formats:
        raise ValueError(
            f"Unknown table format {tablefmt!r}. "
            f"Supported: {', '.join(sorted(_table_formats))}"
        )

    fmt = _table_formats[tablefmt]

    # Effective alignment defaults for pretty format (center everything)
    if tablefmt == "pretty":
        eff_numalign, eff_stralign = "center", "center"
    else:
        eff_numalign = numalign if numalign else "decimal"
        eff_stralign = stralign if stralign else "left"

    # 1. Normalise data
    rows, hdrs = _normalise_tabular_data(tabular_data, headers, showindex)

    # 2. Format every cell as string
    str_rows = _format_cells(rows, floatfmt, missingval)
    str_hdrs = list(hdrs)

    # 3. Equalise column count
    str_hdrs, ncols = _equalise_columns(str_rows, str_hdrs, missingval)
    if ncols == 0:
        return ""

    # 4. Determine per-column alignment
    aligns = _determine_alignments(rows, ncols, colalign, eff_numalign, eff_stralign)

    # 5. Compute column widths
    colwidths = _compute_column_widths(str_rows, str_hdrs, aligns, ncols, fmt)

    # 6. Pre-align all cells and headers
    _align_all_cells(str_rows, str_hdrs, aligns, colwidths, ncols)

    # 7. Build and return the table
    lines = _build_table_lines(str_rows, str_hdrs, aligns, colwidths, fmt, tablefmt)
    return "\n".join(line.rstrip() for line in lines)

Tabulate API Reference¶

tabulate ¶

TableFormat dataclass ¶

tabulate(tabular_data, headers=(), tablefmt='simple', floatfmt='g', numalign='decimal', stralign='left', missingval='', showindex=False, colalign=None) ¶

`tabulate` ¶

`TableFormat` `dataclass` ¶

`tabulate(tabular_data, headers=(), tablefmt='simple', floatfmt='g', numalign='decimal', stralign='left', missingval='', showindex=False, colalign=None)` ¶