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.
- {jsonpatch-1.41/jsonpatch.egg-info → jsonpatch-1.43}/PKG-INFO +1 -1
- {jsonpatch-1.41 → jsonpatch-1.43}/doc/tutorial.rst +108 -2
- {jsonpatch-1.41 → jsonpatch-1.43}/jsonpatch-stubs/__init__.pyi +3 -1
- {jsonpatch-1.41 → jsonpatch-1.43/jsonpatch.egg-info}/PKG-INFO +1 -1
- {jsonpatch-1.41 → jsonpatch-1.43}/jsonpatch.py +304 -29
- {jsonpatch-1.41 → jsonpatch-1.43}/jsonpatch_cli.py +7 -2
- {jsonpatch-1.41 → jsonpatch-1.43}/property_tests.py +100 -0
- {jsonpatch-1.41 → jsonpatch-1.43}/tests.py +663 -3
- {jsonpatch-1.41 → jsonpatch-1.43}/typetests/usage.py +9 -1
- {jsonpatch-1.41 → jsonpatch-1.43}/AUTHORS +0 -0
- {jsonpatch-1.41 → jsonpatch-1.43}/LICENSE +0 -0
- {jsonpatch-1.41 → jsonpatch-1.43}/MANIFEST.in +0 -0
- {jsonpatch-1.41 → jsonpatch-1.43}/README.md +0 -0
- {jsonpatch-1.41 → jsonpatch-1.43}/doc/commandline.rst +0 -0
- {jsonpatch-1.41 → jsonpatch-1.43}/doc/index.rst +0 -0
- {jsonpatch-1.41 → jsonpatch-1.43}/doc/mod-jsonpatch.rst +0 -0
- {jsonpatch-1.41 → jsonpatch-1.43}/ext_tests.py +0 -0
- {jsonpatch-1.41 → jsonpatch-1.43}/jsonpatch.egg-info/SOURCES.txt +0 -0
- {jsonpatch-1.41 → jsonpatch-1.43}/jsonpatch.egg-info/dependency_links.txt +0 -0
- {jsonpatch-1.41 → jsonpatch-1.43}/jsonpatch.egg-info/entry_points.txt +0 -0
- {jsonpatch-1.41 → jsonpatch-1.43}/jsonpatch.egg-info/requires.txt +0 -0
- {jsonpatch-1.41 → jsonpatch-1.43}/jsonpatch.egg-info/top_level.txt +0 -0
- {jsonpatch-1.41 → jsonpatch-1.43}/pyproject.toml +0 -0
- {jsonpatch-1.41 → jsonpatch-1.43}/pytest.ini +0 -0
- {jsonpatch-1.41 → jsonpatch-1.43}/requirements.txt +0 -0
- {jsonpatch-1.41 → jsonpatch-1.43}/setup.cfg +0 -0
- {jsonpatch-1.41 → jsonpatch-1.43}/setup.py +0 -0
- {jsonpatch-1.41 → jsonpatch-1.43}/tests.js +0 -0
|
@@ -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.
|
|
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.
|