xlinject

A surgical XML injector for .xlsx files.

xlinject is designed to read and write specific cell values directly inside the XLSX archive while preserving formatting, metadata, and modern Excel dynamic array semantics.

Status: Beta prerelease - API-first

Release note

0.2.0b2 fixes an Excel compatibility issue in the worksheet XML serializer. Workbooks produced by the previous xml.etree round-trip could still be read by ZIP tools and openpyxl, but some files were rejected by Excel itself after write operations. The serializer path now uses lxml, which preserves the required worksheet markup more safely.

Who this is for

xlinject is useful when you have Excel templates with modern formulas (LET, FILTER, dynamic arrays, custom metadata) and need to inject measured values without changing workbook structure or formatting.

Typical workflow:

1. Fetch data from an external API.
2. Build a mapping from A1 cell references to numeric values.
3. Inject values with xlinject.
4. Open workbook in Excel with formulas and layout preserved.

Why this project exists

Object-model-based libraries often deserialize and reserialize full workbook structures. During that process, unsupported XML tags/attributes can be dropped. xlinject will instead target specific XML nodes in-place to minimize collateral changes.

Direct write API

from pathlib import Path
from xlinject import inject_cells

report = inject_cells(
	"source.xlsx",
	"output.xlsx",
	sheet_name="Eingabemaske",
	cell_values={
		"B45": 45717.25,
		"C45": "12,34",
		"D45": 15.67,
	},
	guard_cells=["H2"],
)

print(report)

This writes only the listed cells and keeps formula XML intact unless allow_formula_overwrite=True is explicitly set.

Mixed write API

from xlinject import inject_cells_mixed

report = inject_cells_mixed(
	"source.xlsx",
	"output.xlsx",
	sheet_name="Template",
	cell_values={
		"B10": "BK4S1-0008738",
		"B16": 310,
		"B17": 129,
		"B20": "ja",
	},
	guard_cells=["B19", "B25"],
	validate_sheet_rules=True,
)

print(report)

inject_cells_mixed uses the same XML-first strategy as the numeric writer, but can also write string cells as inlineStr while preserving neighboring XML. When validate_sheet_rules=True, direct worksheet validations such as list, textLength, whole, and decimal are checked before the workbook is mutated.

Questions and support

If you want to use xlinject, are working on a Python-based .xlsx workflow, or run into a problem, please reach out.

Preferred channels:

• Email: kyle@kylehub.dev
• GitHub Issues: https://github.com/KyleDerZweite/xlinject/issues

Questions are welcome, especially when the intended usage is not clear. The goal is to keep improving both the library and its documentation, so usage questions, rough edges, and real-world workflow problems are useful feedback. I will do my best to help.

Development setup (uv)

Prerequisites

• Python 3.11+
• uv 0.11.16, pinned in pyproject.toml

Quick start

uv sync --locked --dev
uv run --locked pre-commit install

The default development interpreter is Python 3.11, selected by .python-version. CI runs the tests on Python 3.11, 3.12, 3.13, and 3.14 on Linux, plus Python 3.11 and 3.14 on Windows and Python 3.14 on macOS. Other interpreter/OS combinations are not covered by this matrix.

Quality checks

uv run --locked pre-commit run --all-files
uv run --locked ruff check .
uv run --locked mypy .
uv run --locked pytest

License

xlinject is open source under the GNU General Public License v3.0 or later (GPL-3.0-or-later). See LICENSE for the full license text.