Metadata-Version: 2.4
Name: compactxlsx
Version: 0.1.0
Summary: Write compact XLSX files from pandas DataFrames.
Author: CompactXLSX contributors
License-Expression: MIT
Project-URL: Homepage, https://github.com/wapecheng/compactxlsx
Project-URL: Repository, https://github.com/wapecheng/compactxlsx
Project-URL: Issues, https://github.com/wapecheng/compactxlsx/issues
Project-URL: Changelog, https://github.com/wapecheng/compactxlsx/blob/main/CHANGELOG.md
Keywords: xlsx,excel,pandas,compression,ooxml
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.23
Requires-Dist: pandas>=1.5
Provides-Extra: test
Requires-Dist: openpyxl>=3.1; extra == "test"
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: openpyxl>=3.1; extra == "dev"
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Requires-Dist: twine>=5; extra == "dev"
Dynamic: license-file

# CompactXLSX

Write smaller XLSX files from pandas.

CompactXLSX is a focused, pure-Python writer for exporting pandas DataFrames
to minimal XLSX workbooks. It writes OOXML directly, stores repeated text in a
shared-string table, and applies maximum ZIP compression by default.

## Why CompactXLSX?

- One-line DataFrame export.
- Multiple worksheets from an ordered mapping.
- Small OOXML payload with shared strings.
- Native Excel cells for numbers and booleans.
- Optional compact header style.
- Atomic output replacement and configurable ZIP compression.
- No spreadsheet engine, Java runtime, or Rust toolchain required.

CompactXLSX is intended for large, data-only exports. It is not a replacement
for a full spreadsheet authoring library such as XlsxWriter or openpyxl.

## Installation

```bash
pip install compactxlsx
```

For local development:

```bash
python -m pip install -e '.[test]'
```

## Quick start

```python
import pandas as pd

from compactxlsx import write_xlsx

df = pd.DataFrame(
    {
        "name": ["Alice", "Bob", "Alice"],
        "score": [91.5, 88.0, 95.0],
        "active": [True, False, True],
    }
)

write_xlsx(df, "report.xlsx")
```

Multiple worksheets:

```python
write_xlsx(
    {
        "Students": students_df,
        "Classes": classes_df,
    },
    "school-report.xlsx",
    index=False,
    header_style=True,
    compression=9,
)
```

Recompress an existing workbook without changing its OOXML parts:

```python
from compactxlsx import recompress_xlsx

before, after = recompress_xlsx("report.xlsx")
print(f"saved {before - after:,} bytes")
```

For migration from the original helper, `save_excel_compressed()` remains as
an alias of `write_xlsx()`.

## Supported data

CompactXLSX writes missing values as blank cells, booleans as Excel booleans,
and finite integers/floats as Excel numbers. Strings are stored in one shared
string table. Dates, timedeltas, categories, and other Python objects are
currently exported as their string representation. Integers outside Excel's
exact IEEE-754 range are stored as text to prevent silent precision loss.

## Scope and limitations

- XLSX output only.
- Data-only worksheets; no formulas, charts, images, merged cells, filters, or
  arbitrary cell formatting.
- Header styling is intentionally limited to one built-in style.
- The complete pandas DataFrame and all unique strings must fit in memory.
- File-size reduction depends on the input. Repeated text generally benefits
  more than high-cardinality text.
- `recompress_xlsx()` changes ZIP compression only; it does not remove styles,
  images, worksheets, or workbook features.

## Benchmark

Run the included reproducible benchmark instead of relying on a universal
compression claim:

```bash
PYTHONPATH=src python benchmarks/benchmark.py --rows 100000
```

The benchmark reports write time and output size. If openpyxl or XlsxWriter is
installed, it includes them as comparison writers.

## Development

```bash
python -m pip install -e '.[test]'
python -m unittest discover -s tests -v
```

See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines.

## License

MIT. See [LICENSE](LICENSE).
