Metadata-Version: 2.5
Name: csvx-py
Version: 0.1.0a1
Summary: Reference Python parser and XLSX converter for CSVX
Project-URL: Homepage, https://github.com/ljcamargo/csvx
Project-URL: Repository, https://github.com/ljcamargo/csvx
Author-email: Luis J Camargo <cam.aedes@gmail.com>
Maintainer-email: Luis J Camargo <cam.aedes@gmail.com>
License: Apache-2.0
License-File: LICENSE
Keywords: converter,csv,csvx,spreadsheet,xlsx
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Requires-Python: >=3.10
Requires-Dist: openpyxl>=3.1
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: jsonschema>=4; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

# csvx-py

Pre-alpha Python reference parser, canonical renderer, and XLSX converter for
the [CSVX draft](https://github.com/ljcamargo/csvx/blob/main/SPEC.md). The distribution name is `csvx-py`; the Python
package and command are both `csvx`.

## Install from this repository

Install the published alpha package with:

```bash
python -m pip install "csvx-py"
```

For development from the repository:

```bash
cd tools/csvx-py
python -m pip install -e ".[dev]"
```

## CLI

```bash
# Validate or canonicalize CSVX
csvx check workbook.csvx
csvx format workbook.csvx -o canonical.csvx

# Convert by file extension and retain a machine-readable loss report
csvx convert workbook.xlsx -o workbook.csvx --report import-report.json
csvx convert workbook.csvx -o rebuilt.xlsx --report export-report.json
```

XLSX import defaults to `--dimension content`: it preserves A1-relative
positions and interior gaps but trims trailing rows or columns that contain
only styles. Use `--dimension worksheet` to preserve the worksheet's reported
extent. `--strict` rejects any conversion that would report a loss.

## Current fidelity boundary

The converter preserves sheet names, cell values, exposed formula text,
comments, hyperlinks (`{{link: ...}}`), positional blank gaps, and exposed
formula caches when importing. It never evaluates formulas. XLSX export asks
the spreadsheet application to recalculate formulas because cached results
cannot reliably be written with the current library.

Styles, merges, data validation, conditional formatting, charts, drawings,
macros, and annotations other than links are not converted yet. Recognized
unsupported features are aggregated in lenient-mode reports and rejected by
strict mode. This pre-alpha converter does not yet detect every possible OOXML
feature, so strict mode is not a complete fidelity guarantee.

Reviewed real-workbook conversion examples and their reports live in
[`tests/samples/`](https://github.com/ljcamargo/csvx/tree/main/tests/samples). Run the package checks with:

```bash
python -m ruff check src tests
python -m pytest
```

Code is Apache-2.0; see the repository [license](https://github.com/ljcamargo/csvx/blob/main/tools/csvx-py/LICENSE).
