json-source-edit

A Python package for surgical, byte-preserving JSON editing. Change only what you intend to change — everything else in the file survives byte-for-byte, so your diff shows your edit, not a full-file rewrite.

The problem

The obvious way to edit a JSON file is parse → modify → serialize:

data = json.loads(text)
data["steps"][1]["line"] = 433
text = json.dumps(data, indent=2)

This is correct, and it destroys your diff. Real evidence, from the project this package was extracted out of: three simple changes to one file — two field updates and one deletion — were expected to produce a ~10-line diff. The parse-modify-serialize round-trip produced a 500+ line diff instead.

That's because json.dumps doesn't know or care what your original formatting was — indentation, key order, quote style, all of it gets re-decided from scratch, every time, whether or not you touched it. Multiply that by a codebase-sized JSON file and code review becomes impossible: every line looks changed, and the actual edit is buried.

json-source-edit fixes this at the source: it never re-serializes the document. It computes exact byte positions for each change against the original text and splices replacement bytes into the gaps — the same operation a film or tape splicer performs, cut and rejoin at an exact point, everything else on the reel undisturbed.

Install

pip install json-source-edit

(Or clone the repo and pip install -e . for local development.)

Usage

The package's whole reason to exist is editing files without disturbing their formatting, so that workflow comes first:

from json_source_edit import JSONEditor

editor = JSONEditor.from_file("config.json")
editor.replace("/items/0/id", 99)
editor.save()   # writes back to config.json; config.json.backup keeps the original

A no-argument save() writes to the path the editor was loaded from (as of 0.5.1 — earlier releases silently wrote nothing here; see docs/adr/0014-*.md) and raises NoSaveDestinationError if there is no destination at all (e.g. a from_string editor), so "saved" can never again be reported without bytes on disk.

Or purely in memory:

editor = JSONEditor.from_string("""{
  "title": "Rust Basics",
  "steps": [
    {"file": "src/main.rs", "line": 10},
    {"file": "src/lib.rs", "line": 20}
  ]
}""")
editor.replace("/steps/0/line", 433)
editor.remove("/steps/1")
result = editor.apply(validate=True)
print(editor.preview_diff())

--- original
+++ modified
@@ -1,7 +1,6 @@
 {
   "title": "Rust Basics",
   "steps": [
-    {"file": "src/main.rs", "line": 10},
-    {"file": "src/lib.rs", "line": 20}
+    {"file": "src/main.rs", "line": 433}
   ]
 }

validate=True catches mistakes before they reach you. It reconstructs the expected result independently — replaying your edits against a copy of the parsed document — and diffs that against what the surgical edit actually produced. If they disagree, it raises SemanticValidationError instead of silently returning something subtly wrong.

apply(), commit(), and save() all default to validate=True — pass validate=False to skip both checks and get the raw compiled result regardless, e.g. if you're doing your own validation or need the ~10-15% extra time this costs off the critical path (apply()'s default changed from False in 0.5.0, after a batch that emptied a container and added into it was found to silently return invalid JSON on every release from v0.1.0 through v0.4.0 — see docs/adr/0010-*.md).

Three more methods help you inspect a pending batch before committing to it: get_value, get_modifications, and preview_diff.

Scope

Every JSON Patch operation is implemented. Multiple replace/remove/ test/add/move/copy calls batch correctly against the same original document — every path resolves in original-document coordinates regardless of what else is in the batch, so edit order doesn't matter and one deletion or insertion can't corrupt another edit's position.

Benchmark (v0)

Reproduce with python benchmarks/throughput.py — a standalone script, no test framework required.

Methodology: replaces 5% of a flat array's elements at each size, median of 5 runs, reporting throughput against the original document size (the more relevant number for "can this handle my file" than edit count alone).

Single-machine numbers, not a controlled benchmark environment — expect real variance run to run and machine to machine; rerun locally before relying on any of this for capacity planning.

(Measured on macOS/arm64, Python 3.12.4, 2026-08-01 — see the script's own output for full per-run samples; the "large" row in particular showed bimodal timing on this machine, a real observation, not smoothed over.)

Provenance

This package was designed and hardened inside codetour-cli, across four independent review gates, before being extracted here with no known remaining incompleteness. See PROVENANCE.md for the commit-by-commit history and docs/adr/0001-extraction-from-codetour-cli.md for the extraction decisions themselves (import strategy, the dependency verdict, the supported-Python-versions floor).

Credits

The position-mapping this package edits against — turning a JSON document into exact byte offsets for every value and key — is done by json-source-map, a small, dependency-free library by David Andersson. It's the one piece of this package that isn't ours: everything in src/json_source_edit/source_map.py is a thin seam around it, and everything else in this package builds on top of what it computes. Elegant, narrowly-scoped libraries like this are what make a package like this one feasible to write at all.

The playground (interactive TUI)

An interactive semantics playground ships as an optional extra — experiment with every operation against a live document, with inline path autosuggest, input history, and a .jse-playground.log.jsonl session log written where you launch it:

pip install "json-source-edit[playground]"
jse-playground

Good first minutes: new [1, 2, 3], then move /0 /1, then undo. Sequential mode (the default) applies each operation immediately; mode batch switches to the library's pristine-coordinate batch contract for studying how large batches compose.

Status

Published: pypi.org/project/json-source-edit. pip install json-source-edit. A 300+-test suite with full JSON Patch operation coverage, including cold-artifact regression tests — added after line-coverage numbers were caught certifying a no-op (a covered branch is not a working feature; docs/adr/0014-*.md). See CHANGELOG.md for release history. Design decisions beyond the original extraction live in docs/adr/ (0002: add's insertion doctrine, including the move/copy compositions; 0003: test's pristine-batch semantics).

License

MIT.