Great Tables Python

Great Tables Python

Build a display table as an output artifact. Transform and validate data before GT; then use the table pipeline to communicate structure, formatting, annotation, and emphasis without changing analytical values.

Boundary

Use this skill when a project imports great_tables or explicitly requests Great Tables. Do not use a GT object as a dataframe, compute business metrics inside presentation formatting, replace an interactive grid, or route a chart request here. Preserve the required render boundary: notebook/browser, HTML fragment/page, LaTeX, image, or PDF.

Know the objects

Read the display-table model before choosing stub, groups, column order, spanners, or annotations.

Ordered workflow

1. Recover the audience, output host, row grain, sort order, units, locale, significant digits, missing-value wording, and accessibility requirements.
2. Prepare a small typed dataframe containing only display rows and fields. Compute totals, ranks, percentages, and flags upstream and test them there.
3. Create GT(data, ...); define stub and row groups only from stable columns.
4. Establish structure before decoration: title/subtitle, column order and labels, spanners, stubhead, group labels, source notes, and footnotes.
5. Apply semantic formatting by column/row target. Do not convert numeric/date columns to strings upstream merely for commas or symbols.
6. Apply minimal targeted styling after formatting. Derive emphasis from an explicit data condition, not hard-coded row positions when rows can reorder.
7. Export through the method matching the artifact. Verify values and structure separately from the rendered appearance and environment prerequisites.

Intent to API family

Canonical anchor

from great_tables import GT, md


def revenue_table(data):
    # variance_pct contains proportions: 0.125 means 12.5%.
    return (
        GT(data, rowname_col="region", locale="en")
        .tab_header(
            title="Regional revenue",
            subtitle=md("Reported in **USD**"),
        )
        .tab_spanner(
            label="Revenue",
            columns=["actual", "budget"],
            id="revenue",
        )
        .fmt_currency(columns=["actual", "budget"], currency="USD")
        .fmt_percent(columns="variance_pct", decimals=1)
    )

Return the GT object from builders. Do not call show() or write a file in a pure table-construction function. fmt_percent scales proportional inputs by 100 by default. If the source already stores percentage points, declare that contract and set the installed API's no-scaling option explicitly.

Formatting and styling rules

• Formatting controls representation; styling controls appearance. Do not use CSS color to encode the only copy of a value or status.
• Prefer semantic formatter methods to upstream string formatting so sorting, filtering, summaries, and formatter targeting retain typed values.
• Use an explicit locale at the table or formatter boundary when separators, symbols, dates, or language are contractual.
• Choose decimals or significant figures from measurement precision; never imply precision absent from the source.
• Give later-referenced spanners explicit stable IDs. A label containing markup is not a reliable identifier.
• Treat html(...) as trusted raw markup. Do not pass untrusted data through it; use escaped/plain text or a sanitized policy.

Read formatting and styling.

Render boundary and verification

HTML fragments, full pages, email-inline CSS, LaTeX, and browser-captured images have different requirements. Image/PDF export can require a browser and optional renderer packages; successful GT construction does not prove export. Read render and testing.

Inspect the installed version of Great Tables before using drift-sensitive formatter, selector, spanner, or export signatures. The package was absent from this foundry during authoring, so examples are official-source-grounded but not locally rendered.

Completion requires: input values/grain/order tested upstream; visible labels, units, locale, rounding, and missing text correct; spanner/stub/group structure matches the contract; styles target intended cells after reordering; raw HTML is trusted or avoided; the requested artifact exists and renders in its real host; and missing browser/font/export evidence is reported rather than assumed.

References

• Display-table object model
• Formatting and styling
• Render boundaries and testing