7.0: slim binding APIs, compatibility policy, and installable wheels on every platform

[GabrielMarquezMatte]

What does this change?

Everything on develop since 7.0.0-rc.2. It does three things:

• Python wheels now install on the systems they support, and more platforms get one.
• 7.x has a written compatibility policy that CI enforces.
• The Python, C++ and Rust APIs are cut down to one way per operation before 7.0 freezes them.

docs/guide/migrating-to-v7.md has a v6 → v7 table per binding.

The C ABI is unchanged and XL_ABI_VERSION stays 6.

Wheels and native builds

• The wheel's platform tag now comes from the bundled library, not from the build runner. The runner's own tags were macosx_26_0 and manylinux_2_39, so pip refused 6.0.0 and the 7.0 release candidates on macOS 14/15, Debian 12, Ubuntu 22.04, RHEL 9 and Amazon Linux 2023. The library itself needs macOS 12.0 and GLIBC 2.34.
• New targets: Linux aarch64 (ubuntu-24.04-arm), macOS x86_64 (macos-15-intel), and musllinux x64/aarch64 built in Alpine containers (python/scripts/build_musl_wheel.sh).
• check_wheel_tag.py fails CI when a wheel does not install on the runner that built it.
• Arch detection now accepts aarch64. The old check would have published the Linux ARM assets and CLI as x64.
• Wheel tags produced by CI: manylinux_2_34_{x86_64,aarch64}, musllinux_1_2_{x86_64,aarch64}, macosx_12_0_{arm64,x86_64}, win_amd64.

CI

• CodeQL always creates both Analyze (csharp) and Analyze (python). Before, a PR without C# changes never created the required Analyze (csharp) check, so it stayed pending forever.
• ExcelReader.NET and ExcelReader.Arrow enable package validation against 7.0.0-rc.2, and Build & Test (ubuntu-latest) packs both. A removed or changed public member fails the build: a deliberate break was caught with CP0002.

Compatibility policy

• New guide page docs/guide/versioning.md says what a minor version may change:

  • new members on the interfaces only the library implements, with default implementations;
  • new enum values;
  • new options.

  Interfaces that users implement never gain a member they would have to implement.

• XML docs on those interfaces and on CellType and ExcelColumnType link to the policy. CONTRIBUTING lists the rules.

Python API

• open_workbook(source) is the only opener. It takes a path, bytes/bytearray/memoryview/io.BytesIO, a Source, or a readable stream. open_bytes, open_source and open_stream are removed.
• write_workbook(destination, data, types=None) takes a path or a binary object with write(), and a TypedTable or any Arrow-compatible table, including pandas and polars DataFrames. Removed: write_arrow, write_pandas, write_polars and every *_to_bytes.
• open_writer(destination) and encrypt_package(package, destination, password) follow the same pattern. open_writer_to_memory, SheetWriter.bytes() and encrypt_package_bytes are removed.
• A sheet reads as rows(), parse_typed()/iter_parse_typed(), to_arrow() (now a RecordBatch)/to_arrow_stream(), or to_pandas()/to_polars().
  • Removed: read_all, read_all_columnar, ColumnarSheet, decode_cell, to_record_batch, to_record_batch_reader, iter_pandas, iter_polars, sheet_count, sheet_names, sheet_name_at.
• SheetWriter writes whole rows only, with write_row. A typed blank is written as (None, ColumnType.X).

C++ API

• Workbook::open is one overload set: path, byte span, Source or InputStream.
• write_columns, write_sheet and WriterHandle::open take a path or a std::vector<std::uint8_t>&. WriterHandle::finish() reports errors.
• Options are const Opts& = {}, with the format inside them.
• One aggregate_csv; CsvParallelOptions is removed.
• C handles, from_raw, handle() and to_c() are no longer public. The dead payload path in RowView is removed.
• The README is current: it pins v7.0.0 and documents WriterHandle.

Rust API

• The raw FFI is private: the ~130 Xl*/xl_*/XL_* items.
• Every item lives at the crate root, with one path each.
• Integer codes are now enums: Format, ColumnType, ErrorKind.
• Opening is Workbook::open(path) plus OpenOptions::{open, open_bytes, open_source, open_reader}. OpenOptions and WriteOptions are builder-only.
• Writing has path and impl Write pairs (write_columns/write_columns_to, write_sheet/write_sheet_to). WriterHandle::new(writer) ends with finish().
• Reading has Sheet::{parse, parse_arrow, parse_arrow_stream, read_all} and one aggregate_csv.

Behavior change in all three bindings

max_cell_bytes and intern_strings now apply to CSV too. Before, a CSV read used only csv_max_cell_bytes/csv_intern_strings, so the general limit never reached it. The csv_* pair is removed from the bindings.

Checklist

• dotnet build ExcelReader.slnx --configuration Release builds clean (warnings are errors)
• dotnet test tests/ExcelReader.Tests/ExcelReader.Tests.csproj --configuration Release passes
• If this changes the public API: PublicAPI.Unshipped.txt updated (.NET public API unchanged; XML docs only)
• Tests added/updated for the behavior change
• One focused change: this is the 7.0 release-candidate batch, split into one commit per area

Test plan

• CI on develop is green on every job: .NET on three OSes, ISA fallbacks, AOT, CodeQL, docs, the native build on five runners, Python smoke on five runners, musl on x64 and arm64, Rust and C++ on three OSes.
• Locally:
  • Python: 195 passed.
  • C++: 8/8 ctest, benchmark smoke, and the find_package consumer.
  • Rust: clippy -D warnings and 133 tests plus 19 doctests.
  • Package validation passes against rc.2.

Known gaps

• The release.yml jobs added here (musl, macOS Intel CLI and wheel) first run on the next tag.
• After 7.0.0 ships, move PackageValidationBaselineVersion to 7.0.0.
• The read benchmark tables predate checksum verification, and the Python README keeps earlier timings under the new method names.

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 91.06%. Comparing base (114f5ae) to head (daad018).
❗ Your organization needs to install the Codecov GitHub app to enable full functionality.

Additional details and impacted files

@@           Coverage Diff           @@
##           master     #142   +/-   ##
=======================================
  Coverage   91.06%   91.06%           
=======================================
  Files         251      251           
  Lines       17472    17472           
  Branches     3153     3153           
=======================================
  Hits        15911    15911           
  Misses       1070     1070           
  Partials      491      491           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.