Jetxl describes itself as an experimental xlsx writer. Writing without optional parameters is well covered. Combining several formatting parameters may hit bugs, and existing parameter behavior is subject to change. Pin an exact version.
Write-only
There’s no reader. Jetxl can’t open a spreadsheet, inspect one, or modify an existing workbook. Every call produces a file from scratch. For reading, use openpyxl.
Inconsistent indexing
This is the most common source of off-by-one bugs.
Grid limits
Excel stops at 1,048,576 rows and 16,384 columns. Jetxl checks both before writing and raises rather than producing a truncated file. The row limit counts the header row.
Values that change silently
NaN and infinity are written as empty cells, because neither is representable in the spreadsheet format. Control characters other than tab, newline and carriage return are stripped from text for the same reason. Neither conversion raises, so the file writes successfully and the difference appears only when you open it. See Data types.
Unusable colors disappear silently
Jetxl accepts six or eight hex digits and strips a leading #. Anything else, including named colors such as "red" and three-digit shorthand such as "F00", is dropped. The file writes successfully with default coloring instead of raising an error, so check your output when a color doesn’t appear.
Jetxl catches the obvious mistakes. An empty format code, or one made entirely of letters such as "accounting", raises an OSError naming the bad code. Anything else passes through to Excel unchecked, so a malformed code still produces a file that Excel complains about when you open it.
Passing a raw code that matches a built-in, such as "$#,##0.00" instead of "currency", writes the file and prints a warning suggesting the built-in name.
Excel caps format codes at roughly 255 characters, and color names inside a code are limited to Excel’s built-in set.
The built-in percentage formats map to Excel’s own percent formats, which multiply by 100 for display. Store 0.15 for 15 percent, not 15.
Despite the source describing it as bold plus gray, styled_headers applies bold with no fill. Use cell_styles on the header row for a background color.
Some mistakes fail quietly
An unrecognized comparison operator in a conditional format becomes greater_than rather than raising, so a typo produces a working file with the wrong rule. An unrecognized rule_type is worse: the whole rule is dropped and nothing is written. A table missing a required key such as name is dropped the same way.
Errors that do raise arrive from the Rust core as OSError, not ValueError.
Charts
Six types: column, bar, line, pie, scatter, area. Anything else, including combo charts, waterfalls, treemaps and sparklines, isn’t available. Rendering an image and embedding it is the workaround, at the cost of a static picture.
Chart style numbers don’t all work with all chart types, and rendering varies between Excel versions.
Tables
Ranges must not overlap. Excel rejects a workbook whose tables collide, and it surfaces when someone opens the file rather than at write time.
Validation is advisory
Rules constrain typing. Pasted values can bypass them, and recipients can delete them. Validate again when the file comes back.
Memory on the bytes functions
Jetxl holds the whole workbook in memory before returning it. At a million rows that approaches a gigabyte. Write to a file for very large exports.
Type-stub inconsistency
write_sheet_arrow annotates cell_styles as List[CellStyleMap], while write_sheet_arrow_to_bytes annotates it as List[CellStyleDict], a name with no corresponding definition in the stub. The runtime behavior appears to be the same; the annotation differs.
Reporting problems
Issues and discussions live on GitHub. Reports that include the Jetxl version, the DataFrame library and version, and a minimal failing example are the ones that get fixed.
