jsonpatch 1.41__tar.gz → 1.42__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (28) hide show
  1. {jsonpatch-1.41/jsonpatch.egg-info → jsonpatch-1.42}/PKG-INFO +1 -1
  2. {jsonpatch-1.41 → jsonpatch-1.42}/doc/tutorial.rst +108 -2
  3. {jsonpatch-1.41 → jsonpatch-1.42}/jsonpatch-stubs/__init__.pyi +3 -1
  4. {jsonpatch-1.41 → jsonpatch-1.42/jsonpatch.egg-info}/PKG-INFO +1 -1
  5. {jsonpatch-1.41 → jsonpatch-1.42}/jsonpatch.py +300 -28
  6. {jsonpatch-1.41 → jsonpatch-1.42}/property_tests.py +100 -0
  7. {jsonpatch-1.41 → jsonpatch-1.42}/tests.py +569 -1
  8. {jsonpatch-1.41 → jsonpatch-1.42}/typetests/usage.py +9 -1
  9. {jsonpatch-1.41 → jsonpatch-1.42}/AUTHORS +0 -0
  10. {jsonpatch-1.41 → jsonpatch-1.42}/LICENSE +0 -0
  11. {jsonpatch-1.41 → jsonpatch-1.42}/MANIFEST.in +0 -0
  12. {jsonpatch-1.41 → jsonpatch-1.42}/README.md +0 -0
  13. {jsonpatch-1.41 → jsonpatch-1.42}/doc/commandline.rst +0 -0
  14. {jsonpatch-1.41 → jsonpatch-1.42}/doc/index.rst +0 -0
  15. {jsonpatch-1.41 → jsonpatch-1.42}/doc/mod-jsonpatch.rst +0 -0
  16. {jsonpatch-1.41 → jsonpatch-1.42}/ext_tests.py +0 -0
  17. {jsonpatch-1.41 → jsonpatch-1.42}/jsonpatch.egg-info/SOURCES.txt +0 -0
  18. {jsonpatch-1.41 → jsonpatch-1.42}/jsonpatch.egg-info/dependency_links.txt +0 -0
  19. {jsonpatch-1.41 → jsonpatch-1.42}/jsonpatch.egg-info/entry_points.txt +0 -0
  20. {jsonpatch-1.41 → jsonpatch-1.42}/jsonpatch.egg-info/requires.txt +0 -0
  21. {jsonpatch-1.41 → jsonpatch-1.42}/jsonpatch.egg-info/top_level.txt +0 -0
  22. {jsonpatch-1.41 → jsonpatch-1.42}/jsonpatch_cli.py +0 -0
  23. {jsonpatch-1.41 → jsonpatch-1.42}/pyproject.toml +0 -0
  24. {jsonpatch-1.41 → jsonpatch-1.42}/pytest.ini +0 -0
  25. {jsonpatch-1.41 → jsonpatch-1.42}/requirements.txt +0 -0
  26. {jsonpatch-1.41 → jsonpatch-1.42}/setup.cfg +0 -0
  27. {jsonpatch-1.41 → jsonpatch-1.42}/setup.py +0 -0
  28. {jsonpatch-1.41 → jsonpatch-1.42}/tests.js +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: jsonpatch
3
- Version: 1.41
3
+ Version: 1.42
4
4
  Summary: Apply JSON-Patches (RFC 6902)
5
5
  Home-page: https://github.com/stefankoegl/python-json-patch
6
6
  Author: Stefan Kögl
@@ -70,14 +70,16 @@ The operations of a patch refer to locations in the object it is applied to.
70
70
  A patch created with ``make_patch(src, dst)`` or ``JsonPatch.from_diff(src,
71
71
  dst)`` must therefore be applied to ``src`` (or to an object equal to it).
72
72
  Applying it to any other object, such as ``dst``, usually fails with a
73
- ``JsonPatchConflict``, because the locations it refers to don't exist there:
73
+ ``JsonPatchConflict``, because the locations it refers to don't exist there.
74
+ Here it is a ``JsonPatchPathNotFound``, the subclass of ``JsonPatchConflict``
75
+ that is raised when the location an operation acts on doesn't exist:
74
76
 
75
77
  .. code-block:: python
76
78
 
77
79
  >>> patch.apply(dst)
78
80
  Traceback (most recent call last):
79
81
  ...
80
- jsonpatch.JsonPatchConflict: can't remove a non-existent object 'foo'
82
+ jsonpatch.JsonPatchPathNotFound: can't remove a non-existent object 'foo'
81
83
 
82
84
  Applying it to an object with the same structure but different values may
83
85
  succeed, though, and overwrite those values. With ``generate_test_ops=True``
@@ -151,6 +153,110 @@ do not roll back changes already made in place:
151
153
  >>> original
152
154
  {'value': 2}
153
155
 
156
+ To get all-or-nothing behaviour without copying the document, pass
157
+ ``atomic=True`` together with ``in_place=True``. If an operation fails, the
158
+ changes of the preceding operations are undone before the exception is
159
+ raised, so the document is either fully patched or left unchanged:
160
+
161
+ .. code-block:: python
162
+
163
+ >>> original = {'value': 1}
164
+ >>> try:
165
+ ... jsonpatch.apply_patch(original, patch, in_place=True, atomic=True)
166
+ ... except jsonpatch.JsonPatchTestFailed:
167
+ ... print('Test failed')
168
+ Test failed
169
+ >>> original
170
+ {'value': 1}
171
+
172
+ This only keeps the values that the patch removes or replaces until it has
173
+ been applied, so it needs much less memory than ``in_place=False`` for large
174
+ documents. The original containers are restored, so references into the
175
+ document stay valid. If a patch contains custom operations (see
176
+ :class:`jsonpatch.JsonPatch`'s ``operations``), whose changes can't be undone,
177
+ the document is copied instead, and its contents are restored from the copy
178
+ if an operation fails; nested containers are then replaced by their copies.
179
+
180
+ Restoring the document exactly, with the same values, the same order of
181
+ object members and the same container objects, is guaranteed for documents
182
+ made of plain ``dict`` and ``list`` objects, which includes every document
183
+ parsed from JSON. Other containers are restored through their own item
184
+ operations, which is exact as long as these only change the item they are
185
+ given:
186
+
187
+ * Containers that change when they are merely read, such as a
188
+ ``collections.defaultdict``, which adds a missing key on lookup, are not
189
+ supported: looking up a location, testing a value or reading the ``from``
190
+ of a ``move`` or ``copy`` can add members to them that remain after a
191
+ rollback.
192
+ * The copy that patches with custom operations are restored from only
193
+ restores the items of mappings and sequences, not other state that a
194
+ custom operation can change, such as the attributes of objects in the
195
+ document or the ``maps`` of a ``collections.ChainMap``.
196
+
197
+
198
+ Ignoring Missing Locations
199
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~
200
+
201
+ `RFC 6902 <https://tools.ietf.org/html/rfc6902#section-4.2>`_ requires a
202
+ ``remove`` to fail if the location it removes doesn't exist, and this library
203
+ follows it: such an operation raises ``JsonPatchPathNotFound``. A ``replace``
204
+ of a missing location, and a ``move`` or ``copy`` from one, raise it as well.
205
+
206
+ .. code-block:: python
207
+
208
+ >>> patch = [{'op': 'remove', 'path': '/data/another'}]
209
+ >>> try:
210
+ ... jsonpatch.apply_patch({'data': {}}, patch)
211
+ ... except jsonpatch.JsonPatchPathNotFound as ex:
212
+ ... print(ex, ex.op.location)
213
+ can't remove a non-existent object 'another' /data/another
214
+
215
+ Catching the exception around ``apply`` does not skip just that operation,
216
+ though: application stops, and the operations after it are not applied.
217
+
218
+ If removing a member that is already absent should count as success (an
219
+ idempotent ``remove``), the recommended way is a ``JsonPatch`` subclass that
220
+ uses its own ``remove`` operation. The ``operations`` attribute of a
221
+ ``JsonPatch`` class maps each operation name to the class implementing it:
222
+
223
+ .. code-block:: python
224
+
225
+ >>> from types import MappingProxyType
226
+ >>> class IdempotentRemoveOperation(jsonpatch.RemoveOperation):
227
+ ... def apply(self, obj):
228
+ ... try:
229
+ ... return super().apply(obj)
230
+ ... except jsonpatch.JsonPatchPathNotFound:
231
+ ... return obj # nothing to remove
232
+ >>> class IdempotentJsonPatch(jsonpatch.JsonPatch):
233
+ ... operations = MappingProxyType(dict(
234
+ ... jsonpatch.JsonPatch.operations,
235
+ ... remove=IdempotentRemoveOperation,
236
+ ... ))
237
+
238
+ >>> patch = IdempotentJsonPatch([
239
+ ... {'op': 'remove', 'path': '/data/another'},
240
+ ... {'op': 'add', 'path': '/data/new', 'value': 1},
241
+ ... ])
242
+ >>> patch.apply({'data': {}})
243
+ {'data': {'new': 1}}
244
+
245
+ Only a missing member or element is ignored. Other errors still raise, such
246
+ as a ``JsonPatchConflict`` for removing the whole document, or a
247
+ ``JsonPointerException`` if a parent of the location doesn't exist:
248
+
249
+ .. code-block:: python
250
+
251
+ >>> patch = IdempotentJsonPatch([{'op': 'remove', 'path': '/missing/key'}])
252
+ >>> patch.apply({'data': {}})
253
+ Traceback (most recent call last):
254
+ ...
255
+ jsonpointer.JsonPointerException: member 'missing' not found in {'data': {}}
256
+
257
+ Patches applied this way don't conform to RFC 6902, so only use this where
258
+ both sides of an exchange agree on it.
259
+
154
260
 
155
261
  Replacing the Whole Document
156
262
  ----------------------------
@@ -35,6 +35,7 @@ class JsonPatchException(Exception):
35
35
 
36
36
  class InvalidJsonPatch(JsonPatchException): ...
37
37
  class JsonPatchConflict(JsonPatchException): ...
38
+ class JsonPatchPathNotFound(JsonPatchConflict): ...
38
39
  class JsonPatchTestFailed(JsonPatchException, AssertionError): ...
39
40
 
40
41
  def multidict(ordered_pairs: Iterable[tuple[str, Any]]) -> dict[str, Any]: ...
@@ -43,6 +44,7 @@ def apply_patch(
43
44
  patch: str | bytes | Iterable[_Operation],
44
45
  in_place: bool = False,
45
46
  pointer_cls: type[JsonPointer] = ...,
47
+ atomic: bool = False,
46
48
  ) -> Any: ...
47
49
  def make_patch(
48
50
  src: Any,
@@ -118,7 +120,7 @@ class JsonPatch:
118
120
  generate_test_ops: bool = False,
119
121
  ) -> Self: ...
120
122
  def to_string(self, dumps: Callable[[Any], str] | None = None) -> str: ...
121
- def apply(self, obj: Any, in_place: bool = False) -> Any: ...
123
+ def apply(self, obj: Any, in_place: bool = False, atomic: bool = False) -> Any: ...
122
124
 
123
125
  # Computes the operations for JsonPatch.from_diff; mostly an implementation
124
126
  # detail, so its internal methods are typed loosely.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: jsonpatch
3
- Version: 1.41
3
+ Version: 1.42
4
4
  Summary: Apply JSON-Patches (RFC 6902)
5
5
  Home-page: https://github.com/stefankoegl/python-json-patch
6
6
  Author: Stefan Kögl
@@ -55,7 +55,7 @@ _EXACT_MATCH_LIMIT = 500 ** 2
55
55
 
56
56
  # Will be parsed by setup.py to determine package metadata
57
57
  __author__ = 'Stefan Kögl <stefan@skoegl.net>'
58
- __version__ = '1.41'
58
+ __version__ = '1.42'
59
59
  __website__ = 'https://github.com/stefankoegl/python-json-patch'
60
60
  __license__ = 'BSD-3-Clause'
61
61
 
@@ -90,6 +90,24 @@ class JsonPatchConflict(JsonPatchException):
90
90
  """
91
91
 
92
92
 
93
+ class JsonPatchPathNotFound(JsonPatchConflict):
94
+ """Raised if the location an operation has to act on does not exist.
95
+
96
+ This is the case for
97
+
98
+ - a ``remove`` or ``replace`` whose ``path`` refers to a non-existent
99
+ object member or array element, and
100
+ - a ``move`` or ``copy`` whose ``from`` refers to a non-existent object
101
+ member or array element.
102
+
103
+ It is a subclass of :class:`JsonPatchConflict`, so existing code that
104
+ catches :class:`JsonPatchConflict` continues to work. It can be caught on
105
+ its own to tell a missing location apart from other conflicts, for
106
+ example to implement a ``remove`` that ignores members which are already
107
+ absent (see the tutorial).
108
+ """
109
+
110
+
93
111
  class JsonPatchTestFailed(JsonPatchException, AssertionError):
94
112
  """ A Test operation failed """
95
113
 
@@ -113,7 +131,8 @@ def multidict(ordered_pairs):
113
131
  _jsonloads = functools.partial(json.loads, object_pairs_hook=multidict)
114
132
 
115
133
 
116
- def apply_patch(doc, patch, in_place=False, pointer_cls=JsonPointer):
134
+ def apply_patch(doc, patch, in_place=False, pointer_cls=JsonPointer,
135
+ atomic=False):
117
136
  """Apply patch operations to the specified JSON document.
118
137
 
119
138
  :param doc: JSON document, including arrays and scalar values.
@@ -129,6 +148,12 @@ def apply_patch(doc, patch, in_place=False, pointer_cls=JsonPointer):
129
148
  :param pointer_cls: JSON pointer class to use.
130
149
  :type pointer_cls: Type[JsonPointer]
131
150
 
151
+ :param atomic: With ``in_place=True``, undo the changes of all preceding
152
+ operations if an operation fails, so that ``doc`` is
153
+ either fully patched or left unchanged. See
154
+ :meth:`JsonPatch.apply`.
155
+ :type atomic: bool
156
+
132
157
  :return: Resulting document, which may have a different type from ``doc``.
133
158
  :rtype: object
134
159
 
@@ -150,7 +175,7 @@ def apply_patch(doc, patch, in_place=False, pointer_cls=JsonPointer):
150
175
  patch = JsonPatch.from_string(patch, pointer_cls=pointer_cls)
151
176
  else:
152
177
  patch = JsonPatch(patch, pointer_cls=pointer_cls)
153
- return patch.apply(doc, in_place)
178
+ return patch.apply(doc, in_place, atomic=atomic)
154
179
 
155
180
 
156
181
  def make_patch(src, dst, pointer_cls=JsonPointer, generate_test_ops=False):
@@ -186,6 +211,149 @@ def make_patch(src, dst, pointer_cls=JsonPointer, generate_test_ops=False):
186
211
  generate_test_ops=generate_test_ops)
187
212
 
188
213
 
214
+ class _NullJournal(object):
215
+ """Performs the changes of patch operations without recording them."""
216
+
217
+ @staticmethod
218
+ def setitem(container, key, value):
219
+ container[key] = value
220
+
221
+ @staticmethod
222
+ def delitem(container, key):
223
+ del container[key]
224
+
225
+ @staticmethod
226
+ def insert(container, index, value):
227
+ container.insert(index, value)
228
+
229
+ @staticmethod
230
+ def append(container, value):
231
+ container.append(value)
232
+
233
+
234
+ _NO_JOURNAL = _NullJournal()
235
+
236
+
237
+ class _Journal(object):
238
+ """Performs the changes of patch operations and records how to undo them.
239
+
240
+ Each undo step refers to the changed container itself rather than to a
241
+ path. As :meth:`rollback` undoes the steps in reverse order, every
242
+ container is in the same state as right after its change when the step is
243
+ undone, so list indices still refer to the same items. Removed and
244
+ replaced values are kept as they are; they are detached from the
245
+ document, so restoring them needs no copy.
246
+
247
+ Restoring a removed member adds it at the end of its mapping, so the
248
+ order of the members of each dict that loses one is recorded once, and
249
+ restored after all steps have been undone. This is limited to dicts
250
+ (including subclasses such as OrderedDict or Counter), whose order is the
251
+ order of insertion; moving a member of other mappings, such as a
252
+ ChainMap, to the end can add it to a different underlying mapping.
253
+ """
254
+
255
+ def __init__(self):
256
+ self._undo = []
257
+ # id of a mapping -> (mapping, its keys before the first removal)
258
+ self._orders = {}
259
+
260
+ def setitem(self, container, key, value):
261
+ if (isinstance(container, MutableMapping) and key not in container or
262
+ # a ChainMap adds the members of its other mappings that are
263
+ # set to its first one
264
+ isinstance(container, collections.ChainMap) and
265
+ key not in container.maps[0]):
266
+ container[key] = value
267
+ self._undo.append((_undo_delitem, container, key))
268
+ else:
269
+ old = container[key]
270
+ container[key] = value
271
+ self._undo.append((_undo_setitem, container, key, old))
272
+
273
+ def delitem(self, container, key):
274
+ # reading a missing member can create it, e.g. in a defaultdict
275
+ if isinstance(container, Mapping) and key not in container:
276
+ raise KeyError(key)
277
+ old = container[key]
278
+ if isinstance(container, MutableSequence):
279
+ del container[key]
280
+ self._undo.append((_undo_insert, container, key, old))
281
+ elif isinstance(container, MutableMapping):
282
+ if (isinstance(container, dict) and
283
+ id(container) not in self._orders):
284
+ self._orders[id(container)] = (container, list(container))
285
+ del container[key]
286
+ self._undo.append((_undo_setitem, container, key, old))
287
+ else:
288
+ del container[key]
289
+ self._undo.append((_undo_setitem, container, key, old))
290
+
291
+ def insert(self, container, index, value):
292
+ container.insert(index, value)
293
+ self._undo.append((_undo_delitem, container, index))
294
+
295
+ def append(self, container, value):
296
+ if (isinstance(container, collections.deque) and
297
+ container.maxlen is not None and
298
+ len(container) == container.maxlen):
299
+ # A full bounded deque drops its first item to make room
300
+ if container.maxlen:
301
+ dropped = container[0]
302
+ container.append(value)
303
+ self._undo.append((_undo_dropping_append, container, dropped))
304
+ else:
305
+ container.append(value) # it stays empty
306
+ return
307
+ container.append(value)
308
+ # the list may shrink again before this step is undone, but by then
309
+ # it has the same length as right after the append
310
+ self._undo.append((_undo_delitem, container, len(container) - 1))
311
+
312
+ def rollback(self):
313
+ """Undoes all recorded changes, the most recent one first."""
314
+ while self._undo:
315
+ step = self._undo.pop()
316
+ step[0](*step[1:])
317
+ for mapping, keys in self._orders.values():
318
+ _reorder(mapping, keys)
319
+ self._orders.clear()
320
+
321
+
322
+ def _undo_setitem(container, key, value):
323
+ container[key] = value
324
+
325
+
326
+ def _undo_delitem(container, key):
327
+ del container[key]
328
+
329
+
330
+ def _undo_insert(container, index, value):
331
+ container.insert(index, value)
332
+
333
+
334
+ def _undo_dropping_append(deque, dropped):
335
+ del deque[-1]
336
+ deque.appendleft(dropped)
337
+
338
+
339
+ def _reorder(mapping, keys):
340
+ """Restores the order of the members of a mapping after a rollback.
341
+
342
+ ``keys`` are its keys before its first removal. They can include
343
+ members that the patch added before, and that the rollback has removed
344
+ again; the original members appear in it in their original order.
345
+ """
346
+ keys = [key for key in keys if key in mapping]
347
+ start = next((index for index, (key, original)
348
+ in enumerate(zip(mapping, keys)) if key != original),
349
+ len(keys))
350
+ # Move the members from the first misplaced one on to the end. Unlike
351
+ # update(), which e.g. a Counter uses to add counts, this only uses the
352
+ # operations the rollback itself uses
353
+ for key in keys[start:]:
354
+ mapping[key] = mapping.pop(key)
355
+
356
+
189
357
  class PatchOperation(object):
190
358
  """A single operation inside a JSON Patch."""
191
359
 
@@ -225,7 +393,15 @@ class PatchOperation(object):
225
393
  raise InvalidJsonPatch("Invalid 'from'", op=self)
226
394
 
227
395
  def apply(self, obj):
228
- """Abstract method that applies a patch operation to the specified object."""
396
+ """Applies the patch operation to the specified object."""
397
+ return self._apply(obj, _NO_JOURNAL)
398
+
399
+ def _apply(self, obj, journal):
400
+ """Applies the operation, making all changes through ``journal``, so
401
+ that :meth:`JsonPatch.apply` can undo them with ``atomic=True``.
402
+
403
+ Subclasses either implement this method or override :meth:`apply`.
404
+ """
229
405
  raise NotImplementedError('should implement the patch operation.')
230
406
 
231
407
  def __hash__(self):
@@ -269,7 +445,7 @@ class PatchOperation(object):
269
445
  class RemoveOperation(PatchOperation):
270
446
  """Removes an object property or an array element."""
271
447
 
272
- def apply(self, obj):
448
+ def _apply(self, obj, journal):
273
449
  subobj, part = self.pointer.to_last(obj)
274
450
 
275
451
  if part is None:
@@ -279,10 +455,10 @@ class RemoveOperation(PatchOperation):
279
455
  raise JsonPointerException("invalid array index '{0}'".format(part))
280
456
 
281
457
  try:
282
- del subobj[part]
458
+ journal.delitem(subobj, part)
283
459
  except (KeyError, IndexError):
284
460
  msg = "can't remove a non-existent object '{0}'".format(part)
285
- raise JsonPatchConflict(msg, op=self)
461
+ raise JsonPatchPathNotFound(msg, op=self)
286
462
  except TypeError as ex:
287
463
  raise JsonPatchConflict(str(ex), op=self)
288
464
 
@@ -292,7 +468,7 @@ class RemoveOperation(PatchOperation):
292
468
  class AddOperation(PatchOperation):
293
469
  """Adds an object property or an array element."""
294
470
 
295
- def apply(self, obj):
471
+ def _apply(self, obj, journal):
296
472
  try:
297
473
  value = self.operation["value"]
298
474
  except KeyError:
@@ -301,9 +477,13 @@ class AddOperation(PatchOperation):
301
477
 
302
478
  # Insert a copy so the document does not share mutable values with
303
479
  # the patch; otherwise later operations would modify the patch itself.
304
- return self._add(obj, copy.deepcopy(value))
480
+ value = copy.deepcopy(value)
481
+ if journal is _NO_JOURNAL:
482
+ # subclasses may override _add without the journal parameter
483
+ return self._add(obj, value)
484
+ return self._add(obj, value, journal)
305
485
 
306
- def _add(self, obj, value):
486
+ def _add(self, obj, value, journal=_NO_JOURNAL):
307
487
  subobj, part = self.pointer.to_last(obj)
308
488
 
309
489
  if part is None:
@@ -311,16 +491,16 @@ class AddOperation(PatchOperation):
311
491
 
312
492
  if isinstance(subobj, MutableSequence):
313
493
  if part == '-':
314
- subobj.append(value) # pylint: disable=E1103
494
+ journal.append(subobj, value)
315
495
 
316
496
  elif part > len(subobj) or part < 0:
317
497
  raise JsonPatchConflict("can't insert outside of list", op=self)
318
498
 
319
499
  else:
320
- subobj.insert(part, value) # pylint: disable=E1103
500
+ journal.insert(subobj, part, value)
321
501
 
322
502
  elif isinstance(subobj, MutableMapping):
323
- subobj[part] = value
503
+ journal.setitem(subobj, part, value)
324
504
 
325
505
  else:
326
506
  raise JsonPatchConflict("unable to fully resolve json pointer {0}, part {1}".format(self.location, part), op=self)
@@ -330,7 +510,7 @@ class AddOperation(PatchOperation):
330
510
  class ReplaceOperation(PatchOperation):
331
511
  """Replaces an object property or an array element by a new value."""
332
512
 
333
- def apply(self, obj):
513
+ def _apply(self, obj, journal):
334
514
  try:
335
515
  value = self.operation["value"]
336
516
  except KeyError:
@@ -352,23 +532,23 @@ class ReplaceOperation(PatchOperation):
352
532
  raise InvalidJsonPatch("'path' with '-' can't be applied to 'replace' operation", op=self)
353
533
 
354
534
  if part >= len(subobj) or part < 0:
355
- raise JsonPatchConflict("can't replace outside of list", op=self)
535
+ raise JsonPatchPathNotFound("can't replace outside of list", op=self)
356
536
 
357
537
  elif isinstance(subobj, MutableMapping):
358
538
  if part not in subobj:
359
539
  msg = "can't replace a non-existent object '{0}'".format(part)
360
- raise JsonPatchConflict(msg, op=self)
540
+ raise JsonPatchPathNotFound(msg, op=self)
361
541
  else:
362
542
  raise JsonPatchConflict("unable to fully resolve json pointer {0}, part {1}".format(self.location, part), op=self)
363
543
 
364
- subobj[part] = value
544
+ journal.setitem(subobj, part, value)
365
545
  return obj
366
546
 
367
547
 
368
548
  class MoveOperation(PatchOperation):
369
549
  """Moves an object property or an array element to a new location."""
370
550
 
371
- def apply(self, obj):
551
+ def _apply(self, obj, journal):
372
552
  from_ptr = self._from_pointer()
373
553
 
374
554
  # Checked before anything is resolved, as removing an array element
@@ -386,7 +566,7 @@ class MoveOperation(PatchOperation):
386
566
  try:
387
567
  value = subobj[part]
388
568
  except (KeyError, IndexError) as ex:
389
- raise JsonPatchConflict(str(ex), op=self)
569
+ raise JsonPatchPathNotFound(str(ex), op=self)
390
570
 
391
571
  # If source and target are equal, this is a no-op
392
572
  if self.pointer == from_ptr:
@@ -396,14 +576,14 @@ class MoveOperation(PatchOperation):
396
576
  obj = RemoveOperation({
397
577
  'op': 'remove',
398
578
  'path': self.operation['from']
399
- }, pointer_cls=self.pointer_cls).apply(obj)
579
+ }, pointer_cls=self.pointer_cls)._apply(obj, journal)
400
580
 
401
581
  # the value has been detached from its old location, so no copy
402
582
  # needed
403
583
  obj = AddOperation({
404
584
  'op': 'add',
405
585
  'path': self.location,
406
- }, pointer_cls=self.pointer_cls)._add(obj, value)
586
+ }, pointer_cls=self.pointer_cls)._add(obj, value, journal)
407
587
  except JsonPatchException as ex:
408
588
  # report the failure against this operation rather than the
409
589
  # internal, synthetic remove / add operations
@@ -441,7 +621,7 @@ class MoveOperation(PatchOperation):
441
621
  class TestOperation(PatchOperation):
442
622
  """Test value by specified location."""
443
623
 
444
- def apply(self, obj):
624
+ def _apply(self, obj, journal):
445
625
  try:
446
626
  subobj, part = self.pointer.to_last(obj)
447
627
  if part is None:
@@ -468,21 +648,21 @@ class TestOperation(PatchOperation):
468
648
  class CopyOperation(PatchOperation):
469
649
  """ Copies an object property or an array element to a new location """
470
650
 
471
- def apply(self, obj):
651
+ def _apply(self, obj, journal):
472
652
  from_ptr = self._from_pointer()
473
653
 
474
654
  subobj, part = _to_existing_last(from_ptr, obj)
475
655
  try:
476
656
  value = copy.deepcopy(subobj if part is None else subobj[part])
477
657
  except (KeyError, IndexError) as ex:
478
- raise JsonPatchConflict(str(ex), op=self)
658
+ raise JsonPatchPathNotFound(str(ex), op=self)
479
659
 
480
660
  # value is already a deep copy, no need to copy it again
481
661
  try:
482
662
  obj = AddOperation({
483
663
  'op': 'add',
484
664
  'path': self.location,
485
- }, pointer_cls=self.pointer_cls)._add(obj, value)
665
+ }, pointer_cls=self.pointer_cls)._add(obj, value, journal)
486
666
  except JsonPatchException as ex:
487
667
  # report the failure against this operation rather than the
488
668
  # internal, synthetic add operation
@@ -492,6 +672,57 @@ class CopyOperation(PatchOperation):
492
672
  return obj
493
673
 
494
674
 
675
+ def _restore(obj, saved):
676
+ """Restores the contents of a document from a copy of it.
677
+
678
+ Only the items of mappings and sequences are restored, not other state
679
+ that a custom operation can change, such as attributes or the list of
680
+ mappings of a ChainMap.
681
+ """
682
+ if isinstance(obj, collections.ChainMap):
683
+ # restore each mapping, so that none takes over another's members
684
+ for mapping, saved_mapping in zip(obj.maps, saved.maps):
685
+ _restore(mapping, saved_mapping)
686
+ elif isinstance(obj, MutableMapping):
687
+ obj.clear()
688
+ obj.update(saved)
689
+ elif isinstance(obj, MutableSequence):
690
+ # not obj[:] = saved, as e.g. deque doesn't support slices
691
+ obj.clear()
692
+ obj.extend(saved)
693
+ # Immutable containers can't have changed, but their children can
694
+ elif isinstance(obj, Mapping):
695
+ for key in saved:
696
+ _restore(obj[key], saved[key])
697
+ elif isinstance(obj, Sequence) and not isinstance(obj, (str, bytes)):
698
+ for item, saved_item in zip(obj, saved):
699
+ _restore(item, saved_item)
700
+
701
+
702
+ _JOURNALED_OPERATIONS = (
703
+ RemoveOperation, AddOperation, ReplaceOperation, MoveOperation,
704
+ TestOperation, CopyOperation,
705
+ )
706
+
707
+
708
+ def _supports_journal(operation):
709
+ """Whether all changes of ``operation`` go through its journal, which is
710
+ the case for the built-in operations unless a subclass, or the operation
711
+ object itself, changes how they are applied."""
712
+ overridden = getattr(operation, '__dict__', {})
713
+ if any(name in overridden for name in ('apply', '_apply', '_add')):
714
+ return False
715
+ cls = type(operation)
716
+ if getattr(cls, 'apply', None) is not PatchOperation.apply:
717
+ return False
718
+ if not any(getattr(cls, '_apply', None) is base._apply
719
+ for base in _JOURNALED_OPERATIONS):
720
+ return False
721
+ if isinstance(operation, AddOperation) and cls._add is not AddOperation._add:
722
+ return False
723
+ return True
724
+
725
+
495
726
  class JsonPatch(object):
496
727
  """A JSON Patch is an iterable of Patch Operations.
497
728
 
@@ -687,7 +918,7 @@ class JsonPatch(object):
687
918
  def _ops(self):
688
919
  return tuple(map(self._get_operation, self.patch))
689
920
 
690
- def apply(self, obj, in_place=False):
921
+ def apply(self, obj, in_place=False, atomic=False):
691
922
  """Applies the patch to a given object.
692
923
 
693
924
  :param obj: JSON document, including arrays and scalar values.
@@ -697,6 +928,21 @@ class JsonPatch(object):
697
928
  specified `obj` or to its copy.
698
929
  :type in_place: bool
699
930
 
931
+ :param atomic: With ``in_place=True``, undo the changes of all
932
+ preceding operations if an operation fails, so that
933
+ `obj` is either fully patched or left unchanged. This
934
+ does not copy the document; it only keeps the values
935
+ that the patch removes or replaces until it is
936
+ applied. Patches with custom operations, whose
937
+ changes can't be undone, copy the document instead.
938
+ Exact restoration is guaranteed for documents of
939
+ plain dicts and lists; members that containers such
940
+ as ``defaultdict`` add when they are only read are
941
+ not removed again (see the tutorial). Without
942
+ ``in_place=True``, `obj` is never changed, so this
943
+ has no effect.
944
+ :type atomic: bool
945
+
700
946
  :return: Resulting document. Use this return value even with
701
947
  ``in_place=True``, because a root replacement returns a new
702
948
  value rather than modifying the original container.
@@ -704,9 +950,35 @@ class JsonPatch(object):
704
950
 
705
951
  if not in_place:
706
952
  obj = copy.deepcopy(obj)
953
+ atomic = False
707
954
 
708
- for operation in self._ops:
709
- obj = operation.apply(obj)
955
+ ops = self._ops
956
+
957
+ if not atomic:
958
+ for operation in ops:
959
+ obj = operation.apply(obj)
960
+ return obj
961
+
962
+ if not all(map(_supports_journal, ops)):
963
+ # The changes of custom operations can't be undone, so restore
964
+ # the document from a copy instead
965
+ saved = copy.deepcopy(obj)
966
+ original = obj
967
+ try:
968
+ for operation in ops:
969
+ obj = operation.apply(obj)
970
+ except BaseException:
971
+ _restore(original, saved)
972
+ raise
973
+ return obj
974
+
975
+ journal = _Journal()
976
+ try:
977
+ for operation in ops:
978
+ obj = operation._apply(obj, journal)
979
+ except BaseException:
980
+ journal.rollback()
981
+ raise
710
982
 
711
983
  return obj
712
984