tytable 1.0.0

Typst tables from Polars DataFrames, with a tinytable-inspired API.

tytable

A small Python library that turns Polars DataFrames into Typst tables, inspired by R's tinytable package. Most of tinytable's styling power, including image/sparkline support and a Jupyter HTML preview.

Install

Install the latest release from PyPI:

uv add tytable

Or with pip:

pip install tytable

For generated plots and sparklines, install the optional extra. Embedding existing image files with .images() needs no additional Python dependencies:

uv add "tytable[images]"

From a cloned checkout, run:

uv sync --all-extras
make test

Quickstart

import polars as pl
from tytable import tt

df = pl.DataFrame({
    "Product": ["A", "B", "C"],
    "Score": [85.43, 72.10, 91.87],
})

tab = (
    tt(df, caption="Product scores", label="product-scores")
    .fmt(j="Score", digits=2)
    .style(j="Score", align="c")
    .style(i=0, bold=True, background="#2c3e50", color="white")
)

# Save in a script, or let `tab` be the last line of a Jupyter cell for a preview.
tab.save("report_assets/products.typ")
tab

The .typ file can be #included in a Typst report and compiled as part of the whole document.

Conventions

• 0-based row indexing: i=0 is the first data row (the row after the column-name header). Use i="header" for the column-name row, negative ints for column-group header rows (-1 is the innermost row, immediately above the column-name header; increasingly negative values move upward).
• Column selection by name: j="Score" (preferred); j=0 selects the first column by position.
• Method chaining: .style(), .fmt(), .group(), and the .theme_*() methods all return self. .render() / .save() are terminal.
• Readable defaults: text columns are left-aligned and numeric columns are right-aligned, including their headers. Explicit .style(align=...) calls override these dtype-based defaults.
• Lazy evaluation: styling, formatting, grouping, and plotting are recorded as intent and replayed in a fixed order at render time. Row indices always refer to the final, visible table.
• Figure wrapping: Typst tables are figures by default, enabling captions, numbering, and labels such as label="product-scores". Use figure=False for an unnumbered table; captions and labels cannot be combined with it.

Documentation

A practical guide with rendered examples (source followed by result) from easy to complex, a task-oriented API reference, and an R-tinytable comparison table live in the PDF built from docs/main.typ:

• Always-current build (HEAD): https://einmaulwurf.github.io/tytable/
• Versioned (latest release): https://github.com/EinMaulwurf/tytable/releases/latest/download/tytable-docs.pdf

Build locally (requires the typst CLI, install from here):

make docs
# → docs/tytable-docs.pdf

Starting with version 1.0, documented public APIs remain backward compatible throughout the 1.x series; breaking changes are reserved for 2.0.

Coming from R tinytable

tt(df) ↔ tt(data), .style() ↔ style_tt(), .fmt() ↔ format_tt(), .group() ↔ group_tt(), and .theme_striped() / .theme_grid() correspond to theme_tt(). Indexing is 0-based (vs R's 1-based) and columns are selected by name (preferred). The full comparison table is in the PDF above.