The jsonpatch module

Apply JSON-Patches (RFC 6902)

class jsonpatch.AddOperation(operation)

Adds an object property or an array element.

class jsonpatch.CopyOperation(operation)

Copies an object property or an array element to a new location

exception jsonpatch.InvalidJsonPatch

Raised if an invalid JSON Patch is created

class jsonpatch.JsonPatch(patch)

A JSON Patch is a list of Patch Operations.

>>> patch = JsonPatch([
...     {'op': 'add', 'path': '/foo', 'value': 'bar'},
...     {'op': 'add', 'path': '/baz', 'value': [1, 2, 3]},
...     {'op': 'remove', 'path': '/baz/1'},
...     {'op': 'test', 'path': '/baz', 'value': [1, 3]},
...     {'op': 'replace', 'path': '/baz/0', 'value': 42},
...     {'op': 'remove', 'path': '/baz/1'},
... ])
>>> doc = {}
>>> result = patch.apply(doc)
>>> expected = {'foo': 'bar', 'baz': [42]}
>>> result == expected

JsonPatch object is iterable, so you could easily access to each patch statement in loop:

>>> lpatch = list(patch)
>>> expected = {'op': 'add', 'path': '/foo', 'value': 'bar'}
>>> lpatch[0] == expected
>>> lpatch == patch.patch

Also JsonPatch could be converted directly to bool if it contains any operation statements:

>>> bool(patch)
>>> bool(JsonPatch([]))

This behavior is very handy with make_patch() to write more readable code:

>>> old = {'foo': 'bar', 'numbers': [1, 3, 4, 8]}
>>> new = {'baz': 'qux', 'numbers': [1, 4, 7]}
>>> patch = make_patch(old, new)
>>> if patch:
...     # document have changed, do something useful
...     patch.apply(old)    
apply(obj, in_place=False)

Applies the patch to given object.

  • obj (dict) – Document object.
  • in_place (bool) – Tweaks way how patch would be applied - directly to specified obj or to his copy.

Modified obj.

classmethod from_diff(src, dst, optimization=True)

Creates JsonPatch instance based on comparing of two document objects. Json patch would be created for src argument against dst one.

  • src (dict) – Data source document object.
  • dst (dict) – Data source document object.

JsonPatch instance.

>>> src = {'foo': 'bar', 'numbers': [1, 3, 4, 8]}
>>> dst = {'baz': 'qux', 'numbers': [1, 4, 7]}
>>> patch = JsonPatch.from_diff(src, dst)
>>> new = patch.apply(src)
>>> new == dst
classmethod from_string(patch_str)

Creates JsonPatch instance from string source.

Parameters:patch_str (str) – JSON patch as raw string.
Returns:JsonPatch instance.

Returns patch set as JSON string.

exception jsonpatch.JsonPatchConflict

Raised if patch could not be applied due to conflict situation such as: - attempt to add object key then it already exists; - attempt to operate with nonexistence object key; - attempt to insert value to array at position beyond of it size; - etc.

exception jsonpatch.JsonPatchException

Base Json Patch exception

exception jsonpatch.JsonPatchTestFailed

A Test operation failed

class jsonpatch.MoveOperation(operation)

Moves an object property or an array element to new location.

class jsonpatch.PatchOperation(operation)

A single operation inside a JSON Patch.


Abstract method that applies patch operation to specified object.

class jsonpatch.RemoveOperation(operation)

Removes an object property or an array element.

class jsonpatch.ReplaceOperation(operation)

Replaces an object property or an array element by new value.

class jsonpatch.TestOperation(operation)

Test value by specified location.

jsonpatch.apply_patch(doc, patch, in_place=False)

Apply list of patches to specified json document.

  • doc (dict) – Document object.
  • patch (list or str) – JSON patch as list of dicts or raw JSON-encoded string.
  • in_place (bool) – While True patch will modify target document. By default patch will be applied to document copy.

Patched document object.

Return type:


>>> doc = {'foo': 'bar'}
>>> patch = [{'op': 'add', 'path': '/baz', 'value': 'qux'}]
>>> other = apply_patch(doc, patch)
>>> doc is not other
>>> other == {'foo': 'bar', 'baz': 'qux'}
>>> patch = [{'op': 'add', 'path': '/baz', 'value': 'qux'}]
>>> apply_patch(doc, patch, in_place=True) == {'foo': 'bar', 'baz': 'qux'}
>>> doc == other

adds the object_pairs_hook parameter to json.load when possible

The “object_pairs_hook” parameter is used to handle duplicate keys when loading a JSON object. This parameter does not exist in Python 2.6. This methods returns an unmodified json.load for Python 2.6 and a partial function with object_pairs_hook set to multidict for Python versions that support the parameter.

jsonpatch.make_patch(src, dst)

Generates patch by comparing of two document objects. Actually is a proxy to JsonPatch.from_diff() method.

  • src (dict) – Data source document object.
  • dst (dict) – Data source document object.
>>> src = {'foo': 'bar', 'numbers': [1, 3, 4, 8]}
>>> dst = {'baz': 'qux', 'numbers': [1, 4, 7]}
>>> patch = make_patch(src, dst)
>>> new = patch.apply(src)
>>> new == dst

Convert duplicate keys values to lists.