jsonpatch 1.41__tar.gz → 1.43__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.43}/PKG-INFO +1 -1
  2. {jsonpatch-1.41 → jsonpatch-1.43}/doc/tutorial.rst +108 -2
  3. {jsonpatch-1.41 → jsonpatch-1.43}/jsonpatch-stubs/__init__.pyi +3 -1
  4. {jsonpatch-1.41 → jsonpatch-1.43/jsonpatch.egg-info}/PKG-INFO +1 -1
  5. {jsonpatch-1.41 → jsonpatch-1.43}/jsonpatch.py +304 -29
  6. {jsonpatch-1.41 → jsonpatch-1.43}/jsonpatch_cli.py +7 -2
  7. {jsonpatch-1.41 → jsonpatch-1.43}/property_tests.py +100 -0
  8. {jsonpatch-1.41 → jsonpatch-1.43}/tests.py +663 -3
  9. {jsonpatch-1.41 → jsonpatch-1.43}/typetests/usage.py +9 -1
  10. {jsonpatch-1.41 → jsonpatch-1.43}/AUTHORS +0 -0
  11. {jsonpatch-1.41 → jsonpatch-1.43}/LICENSE +0 -0
  12. {jsonpatch-1.41 → jsonpatch-1.43}/MANIFEST.in +0 -0
  13. {jsonpatch-1.41 → jsonpatch-1.43}/README.md +0 -0
  14. {jsonpatch-1.41 → jsonpatch-1.43}/doc/commandline.rst +0 -0
  15. {jsonpatch-1.41 → jsonpatch-1.43}/doc/index.rst +0 -0
  16. {jsonpatch-1.41 → jsonpatch-1.43}/doc/mod-jsonpatch.rst +0 -0
  17. {jsonpatch-1.41 → jsonpatch-1.43}/ext_tests.py +0 -0
  18. {jsonpatch-1.41 → jsonpatch-1.43}/jsonpatch.egg-info/SOURCES.txt +0 -0
  19. {jsonpatch-1.41 → jsonpatch-1.43}/jsonpatch.egg-info/dependency_links.txt +0 -0
  20. {jsonpatch-1.41 → jsonpatch-1.43}/jsonpatch.egg-info/entry_points.txt +0 -0
  21. {jsonpatch-1.41 → jsonpatch-1.43}/jsonpatch.egg-info/requires.txt +0 -0
  22. {jsonpatch-1.41 → jsonpatch-1.43}/jsonpatch.egg-info/top_level.txt +0 -0
  23. {jsonpatch-1.41 → jsonpatch-1.43}/pyproject.toml +0 -0
  24. {jsonpatch-1.41 → jsonpatch-1.43}/pytest.ini +0 -0
  25. {jsonpatch-1.41 → jsonpatch-1.43}/requirements.txt +0 -0
  26. {jsonpatch-1.41 → jsonpatch-1.43}/setup.cfg +0 -0
  27. {jsonpatch-1.41 → jsonpatch-1.43}/setup.py +0 -0
  28. {jsonpatch-1.41 → jsonpatch-1.43}/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.43
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.43
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