Why it exists

openpyxl is excellent at creating workbooks. Its object model, file-format coverage, and years of absorbed edge cases are why this fork builds on it.

The harder problem is changing a real workbook without dropping charts or leaving formulas pointed at the wrong cells. That is silent corruption: a file that opens fine and is quietly wrong, often with numbers that still look plausible. An agent cannot eyeball the result, so it needs the workbook’s structure and every edit outcome as typed, machine-readable data. It also needs the library to refuse rather than guess.

Safety contract

Every added operation either does exactly what it claims or refuses atomically. load_workbook(path) keeps the original package bytes as the source of truth by default. Every editing session has one of three explicit outcomes:

• a correct save: edits are spliced into the original bytes, and unrelated package content survives byte-identical; formula-affecting edits may intentionally invalidate caches and update calculation metadata;

• a typed refusal: an unsafe edit changes nothing on disk or in memory and the exception identifies the remedy;

• a loud warning: a stock-mode path reports that an operation may be lossy.

Preserve mode is the default for editable OOXML workbooks, including files opened indirectly by pandas append mode. Pass preserve=False explicitly only when you intend to use openpyxl’s stock, potentially lossy round trip. Read-only and unsupported-format loads retain stock behavior.

A short example

Inspect a workbook, change a labeled input, and save with a machine-readable receipt:

from openpyxl import Workbook, load_workbook

wb = Workbook()
ws = wb.active
ws["A1"], ws["B1"] = "Growth rate", 0.05
ws["A2"], ws["B2"] = "Revenue", 1000
ws["B3"] = "=B2 * (1 + B1)"
wb.save("model.xlsx")

wb = load_workbook("model.xlsx")

wb.sheetnames                       # inspect workbook structure directly
wb.active.locate("Growth rate")     # find a value cell by its label

wb.set_input("Growth rate", 0.07)   # does not overwrite formulas
receipt = wb.save("model_v2.xlsx", receipt=True)
receipt.to_dict()["cells_changed"]  # {'xl/worksheets/sheet1.xml': {'B1': 'changed'}}

What it adds

Drop-in and name map

Only the distribution and repository are renamed. The importable package stays openpyxl. This is the same distribution/import split as Pillow (pip install pillow, import PIL), and it preserves existing code, snippets, and model priors. Every upstream feature remains available; preserve mode and the added APIs are additive.

• GitHub repository / PyPI distribution: ``paper-xlsx``

• Built wheel and sdist names: paper_xlsx-*

• Python import: ``openpyxl``

• Fork sentinel: openpyxl.__paper_version__ = "0.1.3"

• Upstream base: openpyxl 3.1.5 (marker tag paper-base)

Upstream releases are merged rather than rebased. The paper-base tag records the current openpyxl fork point.

Installation

Install from PyPI:

python -m pip uninstall -y openpyxl paper-xlsx
python -m pip install paper-xlsx

The clean uninstall is required when migrating from openpyxl. Both distributions own the frozen openpyxl import tree, and Python package metadata cannot make one satisfy a dependency on the other. If both are present, file ownership depends on installation order and the fork raises on import when it can detect that state.

Confirm the install:

paper-xlsx-doctor

Install the current branch from Git:

pip install "paper-xlsx @ git+https://github.com/paper-instruments/paper-xlsx.git@main"

Documentation

The Sphinx docs extend the upstream openpyxl documentation to cover the fork’s additions. Start with doc/paper.rst for preserve mode, the added API surface, and the refusal taxonomy. Everything inherited from openpyxl works as documented in the remaining upstream documentation.

How it’s tested

• Upstream openpyxl’s test suite runs on every change to check compatibility with existing behavior.

• A frozen, hash-pinned fixture corpus under tests/paper records exact provenance. Its current files come from openpyxl, LibreOffice, or documented package surgery; the still-missing real-Excel and Google Sheets fixture buckets are listed in the corpus README.

• The contract harness saves and reopens before asserting, enforces exact changed-part budgets, exercises refusal atomicity, and runs a headless LibreOffice load smoke.

License

MIT, inherited from openpyxl. Original work © the openpyxl authors; fork additions © Paper Instruments, Inc. The fork preserves the upstream license and attribution. See LICENCE.rst.