# Public workbook exceptions

Unreleased

This exception contract is in source and has not shipped in either edition. Community 2.0.36 and Commercial 2.3.0 can raise the underlying error instead, for example `zipfile.BadZipFile` from `load_workbook` on a file that is not a ZIP package. Until a release carries the contract, catch those errors alongside `InvalidFileException`.

Catch `wolfxl.utils.exceptions.InvalidFileException` for malformed XLSX source content discovered by `load_workbook`/`open`, worksheet reads, `calculate`, `recalculate`, or `save`. Source decoding is lazy: successful loading does not prove that every worksheet can be read or recalculated.

```
from wolfxl import load_workbook
from wolfxl.utils.exceptions import InvalidFileException

try:
    with load_workbook("input.xlsx") as workbook:
        rows = list(workbook.active.values)
        workbook.calculate()
        workbook.save("output.xlsx")
except InvalidFileException as error:
    original_error = error.__cause__
```

## Error families

| Public operation | Malformed-source failures | Other exceptions callers should handle |
| --- | --- | --- |
| `load_workbook`, `open` | `InvalidFileException` for unrecognized input and XLSX ZIP/XML decoding failures, including corrupt DEFLATE and unsupported ZIP compression | `TypeError` for invalid source types; `ValueError` for invalid options or passwords; `NotImplementedError` for unsupported format/mode combinations; `RequiresWolfXLProError` for features requiring the add-on; `NumbersImportError` for Numbers decoding refusals |
| Cell reads, row/column iteration, dimensions, value chunks | `InvalidFileException` for native source XML, reference and shared-string decoding failures | `ValueError` or `CellCoordinatesException` for invalid caller coordinates, ranges and chunk sizes; `KeyError` for an unknown requested sheet; `WorkbookClosedException` after closing |
| `calculate`, `recalculate` | `InvalidFileException` for source decoding during formula intake or cell hydration | `ValueError` for invalid calculation options or perturbations; `ReadOnlyWorkbookException` for committed recalculation on read-only workbooks; documented calculation errors such as `UnsupportedRustFormula`, `FormulaErrorResultError` and `RustCalcBindingError` for formula or backend refusals |
| `save` | `InvalidFileException` for source decoding during formula-cache collection, source promotion or worksheet flushing; invalid non-spreadsheet declarations for the workbook part are refused during promotion | `ValueError`, `NotImplementedError`, `ReadOnlyWorkbookException`, `WorkbookClosedException` and documented save-policy errors for invalid requests or unsupported operations; filesystem/output-stream errors for destination failures |

Filesystem failures with an OS error number retain their original exception type. `InvalidFileException` also inherits from `OSError` and remains compatible with openpyxl's exception of the same name. A non-ZIP OOXML input can additionally be caught as `zipfile.BadZipFile`.

When wrapping a decoder or source-validation error, WolfXL retains the original exception in `__cause__`. Already typed file errors retain their existing cause rather than receiving another wrapper. Format-identification refusals without an underlying decoder exception do not fabricate a cause. Python warning callbacks, custom formula callbacks, cancellation and feature-specific policy refusals retain their own documented contracts.

The contract normalizes source-decoder failures when they occur. It does not require eager validation by every operation. Native streaming can filter out-of-grid cells, and calculation can leave unrelated source scalars unread.

A macro-enabled spreadsheet workbook declaration is valid. A VBA-project or Word document declaration for the spreadsheet workbook part is a different case.

## Reader and package refusals

Catch `InvalidFileException` for an out-of-range shared-string index, for nonascending or repeated rows refused by a read-only reader, and for unsafe ZIP metadata or package-size admission failures. The native refusal message and recovery advice remain available; native admission refusals also retain their `INVALID_SOURCE` diagnostic code. Explicit `Limits` budget failures remain `LimitExceeded`, and invalid caller options remain `ValueError`.

## Reproducible coverage

`tests/test_public_exception_contract.py` contains a deterministic, standalone package generator and the 27 malformed cases: ten deeply nested unknown-element positions, an unclosed row, six invalid cell references, three shared-string-table failures, an empty sheet title, three damaged DEFLATE members, unsupported ZIP compression, and two non-spreadsheet workbook-part declarations. The same tests exercise deferred read/calculation/save failures, direct and streaming reads, valid path/bytes/stream inputs, and macro-enabled workbook saves. No external corpus is needed.