neatxlsx

neatxlsx is an opinionated XLSX report-table writer for Polars. It turns DataFrames and streaming LazyFrames into consistently formatted workbooks while keeping multi-row headers, freeze panes, large/wide-table splitting, and transactional delivery behind one small API.

Installation

pip install neatxlsx

Python 3.11 or newer and Polars 1.38.1 or newer are required.

Quick start

import neatxlsx as nx
import polars as pl

data = pl.DataFrame(
    {
        "Sample": ["A", "B"],
        "Count": [12, 18],
        "Score": [0.125, 0.375],
    }
)

with nx.Workbook("report.xlsx") as workbook:
    workbook.write_sheet(
        data,
        "Results",
        integer_columns="Count",
        decimal_columns="Score",
        freeze_columns=1,
    )

Workbook writes to a sibling temporary file. Normal context-manager exit atomically replaces the target where the filesystem supports atomic rename; exceptional exit discards the temporary workbook and leaves an existing target untouched.

Formats and policies

import neatxlsx as nx
import polars.selectors as cs

with nx.Workbook(
    "report.xlsx",
    header_format=nx.Format(bg_color="#D9EAF7"),
    decimal_format=nx.Format(num_format="0.000"),
) as workbook:
    workbook.write_sheet(
        data,
        "Results",
        header_column_formats={"Sample": nx.Format(font_name="Arial")},
        column_formats={"Score": nx.Format(font_color="#1F4E78")},
        integer_columns=cs.integer(),
        decimal_columns=cs.float(),
        autofit=nx.Autofit(mode="all", max_rows=10_000),
        scientific_notation=nx.ScientificNotation(scope="decimal"),
    )

Column arguments accept one name/index, an ordered sequence, or a Polars selector. Explicit integer and decimal selections override inferred roles for those columns; other columns remain inferred unless the matching infer_* option is disabled.

header_column_formats maps one logical data-column name or zero-based index to a header Format patch. It applies to the generated header and every custom header row, after the workbook header format and any header_row_formats row patch. column_formats remains body-only. Nonempty header-column patches cannot be combined with merge_header=True because a merged range has no unambiguous per-column style.

Large workbooks

ZIP64 is enabled by default because XLSX size depends on uncompressed worksheet XML and cannot be predicted reliably before streaming. Use nx.Workbook(..., use_zip64=False) only when a downstream reader lacks ZIP64 support. Every autofit mode consumes one LazyFrame batch stream. For "body" and "all", column widths are tracked while rows are written and applied only after that stream is exhausted.

See the documentation map for the complete API, lifecycle, testing, and release contracts.

For detailed pass-count, sampling, and temporary-file behavior, read the streaming and autofit architecture. Existing axiomkit callers can use the migration guide; contributors can use the benchmark protocol.