python-json-patch

jsonpatch is a pure-Python implementation of RFC 6902 JSON Patch, giving developers a straightforward API for describing and applying incremental changes to JSON documents. It supports the full patch operation set (add, remove, replace, move, copy, and test) and can also generate a patch automatically by diffing two JSON-like objects with make_patch, which proxies to an internal DiffBuilder that computes a minimal, ordered operation list.

The library ships as a single dependency-light module (jsonpointer is its only runtime requirement) plus two command-line scripts, jsondiff and jsonpatch, for scripting patch generation and application from the shell. It’s widely used as a building block inside API clients, configuration-management tools, and Kubernetes-adjacent Python projects that need to express partial updates to JSON payloads without hand-rolling pointer-walking logic.

What You Get

• apply_patch() function to apply a JSON Patch (list of operations or JSON string) to any dict/list document, returning a modified copy or mutating in place
• make_patch() / JsonPatch.from_diff() to automatically generate a minimal patch by comparing two JSON documents
• Full RFC 6902 operation support: add, remove, replace, move, copy, and test operations, each implemented as its own PatchOperation subclass
• jsonpatch and jsondiff command-line scripts for applying and generating patches directly from files or stdin
• Typed exception hierarchy (JsonPatchException, InvalidJsonPatch, JsonPatchConflict, JsonPatchTestFailed) for precise error handling

Common Use Cases

• Applying PATCH-style partial updates to REST API resources represented as JSON
• Generating and shipping diffs between configuration versions for auditing or rollback
• Implementing JSON Patch semantics for Kubernetes-style reconciliation and CRD update logic
• Synchronizing client and server state by transmitting only the changed operations instead of full documents

Under The Hood

Architecture The library is a single ~930-line module built around a PatchOperation abstract base class with six concrete subclasses (RemoveOperation, AddOperation, ReplaceOperation, MoveOperation, TestOperation, CopyOperation), each implementing its own apply(). The JsonPatch class wraps a list of operations and dispatches to the correct subclass via an immutable MappingProxyType lookup table. Top-level apply_patch()/make_patch() functions are thin proxies onto JsonPatch, insulating simple callers from the class hierarchy. Diff generation is isolated in a separate DiffBuilder that uses a hand-rolled doubly linked list for O(1) operation insert/remove and per-type index dictionaries to match added and removed values so it can collapse remove+add pairs into move or replace operations. Because the six operation types and DiffBuilder share the same operation-dict construction pattern, a change to the core PatchOperation contract would require coordinated updates across all of them, though callers of apply_patch/make_patch would be unaffected.

Tech Stack Pure Python with a single runtime dependency, jsonpointer, used for RFC 6901 pointer resolution. The code carries Python 2.7/3.x compatibility shims (collections vs collections.abc imports, a MappingProxyType fallback to dict) and uses a custom object_pairs_hook via functools.partial to safely load JSON documents with duplicate keys. Packaging is classic setuptools/distutils, with setup.py extracting version and license metadata directly out of jsonpatch.py via regex rather than a separate metadata file, and two argparse-based console scripts (jsonpatch, jsondiff) installed via the scripts= argument. There is no build step, no compiled extension, and no async runtime involved.

Code Quality Tests combine a unittest.TestCase suite in tests.py, a data-driven replay of community JSON-Patch conformance vectors from tests.js, and doctest examples embedded directly in the apply_patch/make_patch/JsonPatch docstrings. GitHub Actions CI and a .coveragerc are present. Error handling runs through a dedicated exception hierarchy rather than bare excepts, though a few broad except clauses exist for cross-version compatibility. There are no type hints or static type checking, consistent with a codebase that still targets Python 2.7, and no dedicated linter configuration is present beyond inline pylint-disable comments.

API Design The public surface is deliberately small: two top-level functions cover most use cases, while the JsonPatch class exposes from_string/from_diff/to_string for callers who need round-tripping or per-operation iteration. Accepting a patch as either a raw JSON string or a parsed list removes a common boilerplate step, and in_place defaults to False so the safe copy-based behavior is the default. The diff algorithm’s move/replace collapsing produces patches that read naturally instead of literal add/remove pairs, a genuine ergonomic improvement over a naive diff. Usage examples live entirely in docstrings rather than a separate examples directory, which keeps them in sync with the code but requires reading source to find them.