jsonpatch 1.38__tar.gz → 1.40__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 (26) hide show
  1. {jsonpatch-1.38 → jsonpatch-1.40}/MANIFEST.in +1 -0
  2. {jsonpatch-1.38/jsonpatch.egg-info → jsonpatch-1.40}/PKG-INFO +1 -1
  3. jsonpatch-1.40/doc/commandline.rst +121 -0
  4. jsonpatch-1.40/doc/index.rst +37 -0
  5. jsonpatch-1.40/doc/mod-jsonpatch.rst +7 -0
  6. jsonpatch-1.40/doc/tutorial.rst +287 -0
  7. {jsonpatch-1.38 → jsonpatch-1.40/jsonpatch.egg-info}/PKG-INFO +1 -1
  8. {jsonpatch-1.38 → jsonpatch-1.40}/jsonpatch.egg-info/SOURCES.txt +4 -0
  9. {jsonpatch-1.38 → jsonpatch-1.40}/jsonpatch.py +112 -48
  10. {jsonpatch-1.38 → jsonpatch-1.40}/jsonpatch_cli.py +5 -3
  11. {jsonpatch-1.38 → jsonpatch-1.40}/property_tests.py +19 -0
  12. {jsonpatch-1.38 → jsonpatch-1.40}/tests.py +387 -20
  13. {jsonpatch-1.38 → jsonpatch-1.40}/AUTHORS +0 -0
  14. {jsonpatch-1.38 → jsonpatch-1.40}/LICENSE +0 -0
  15. {jsonpatch-1.38 → jsonpatch-1.40}/README.md +0 -0
  16. {jsonpatch-1.38 → jsonpatch-1.40}/ext_tests.py +0 -0
  17. {jsonpatch-1.38 → jsonpatch-1.40}/jsonpatch.egg-info/dependency_links.txt +0 -0
  18. {jsonpatch-1.38 → jsonpatch-1.40}/jsonpatch.egg-info/entry_points.txt +0 -0
  19. {jsonpatch-1.38 → jsonpatch-1.40}/jsonpatch.egg-info/requires.txt +0 -0
  20. {jsonpatch-1.38 → jsonpatch-1.40}/jsonpatch.egg-info/top_level.txt +0 -0
  21. {jsonpatch-1.38 → jsonpatch-1.40}/pyproject.toml +0 -0
  22. {jsonpatch-1.38 → jsonpatch-1.40}/pytest.ini +0 -0
  23. {jsonpatch-1.38 → jsonpatch-1.40}/requirements.txt +0 -0
  24. {jsonpatch-1.38 → jsonpatch-1.40}/setup.cfg +0 -0
  25. {jsonpatch-1.38 → jsonpatch-1.40}/setup.py +0 -0
  26. {jsonpatch-1.38 → jsonpatch-1.40}/tests.js +0 -0
@@ -2,6 +2,7 @@ include requirements.txt
2
2
  include LICENSE
3
3
  include README.md
4
4
  include tests.py
5
+ include doc/*.rst
5
6
  include property_tests.py
6
7
  include pytest.ini
7
8
  include ext_tests.py
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: jsonpatch
3
- Version: 1.38
3
+ Version: 1.40
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
@@ -0,0 +1,121 @@
1
+ Commandline Utilities
2
+ =====================
3
+
4
+ The JSON patch package contains the commandline utilities ``jsondiff`` and
5
+ ``jsonpatch``.
6
+
7
+ Both utilities read JSON files as UTF-8. When ``jsonpatch`` modifies a file
8
+ in-place, it also writes UTF-8.
9
+
10
+ ``jsondiff``
11
+ ------------
12
+
13
+ The program ``jsondiff`` can be used to create a JSON patch by comparing two
14
+ JSON files ::
15
+
16
+ usage: jsondiff [-h] [--indent INDENT] [-u] [-t] [-v] FILE1 FILE2
17
+
18
+ Diff two JSON files
19
+
20
+ positional arguments:
21
+ FILE1
22
+ FILE2
23
+
24
+ options:
25
+ -h, --help show this help message and exit
26
+ --indent INDENT Indent output by n spaces
27
+ -u, --preserve-unicode
28
+ Output Unicode character as-is without using Code
29
+ Point
30
+ -t, --test-ops Precede each remove and replace operation by a test of
31
+ the value it changes
32
+ -v, --version show program's version number and exit
33
+
34
+ Example
35
+ ^^^^^^^
36
+
37
+ .. code-block:: bash
38
+
39
+ # inspect JSON files
40
+ $ cat a.json
41
+ { "a": [1, 2], "b": 0 }
42
+
43
+ $ cat b.json
44
+ { "a": [1, 2, 3], "c": 100 }
45
+
46
+ # show patch in "dense" representation
47
+ $ jsondiff a.json b.json
48
+ [{"op": "remove", "path": "/b"}, {"op": "add", "path": "/c", "value": 100}, {"op": "add", "path": "/a/2", "value": 3}]
49
+
50
+ # show patch with some indentation
51
+ $ jsondiff a.json b.json --indent=2
52
+ [
53
+ {
54
+ "op": "remove",
55
+ "path": "/b"
56
+ },
57
+ {
58
+ "op": "add",
59
+ "path": "/c",
60
+ "value": 100
61
+ },
62
+ {
63
+ "op": "add",
64
+ "path": "/a/2",
65
+ "value": 3
66
+ }
67
+ ]
68
+
69
+
70
+
71
+ ``jsonpatch``
72
+ -------------
73
+
74
+ The program ``jsonpatch`` is used to apply JSON patches on JSON files. ::
75
+
76
+ usage: jsonpatch [-h] [--indent INDENT] [-b] [-i] [-v] [-u] ORIGINAL [PATCH]
77
+
78
+ Apply a JSON patch on a JSON file
79
+
80
+ positional arguments:
81
+ ORIGINAL Original file
82
+ PATCH Patch file (read from stdin if omitted)
83
+
84
+ options:
85
+ -h, --help show this help message and exit
86
+ --indent INDENT Indent output by n spaces
87
+ -b, --backup Back up ORIGINAL if modifying in-place
88
+ -i, --in-place Modify ORIGINAL in-place instead of to stdout
89
+ -v, --version show program's version number and exit
90
+ -u, --preserve-unicode
91
+ Output Unicode character as-is without using Code
92
+ Point
93
+
94
+ Example
95
+ ^^^^^^^
96
+
97
+ .. code-block:: bash
98
+
99
+ # create a patch
100
+ $ jsondiff a.json b.json > patch.json
101
+
102
+ # show the result after applying a patch
103
+ $ jsonpatch a.json patch.json
104
+ {"a": [1, 2, 3], "c": 100}
105
+
106
+ $ jsonpatch a.json patch.json --indent=2
107
+ {
108
+ "a": [
109
+ 1,
110
+ 2,
111
+ 3
112
+ ],
113
+ "c": 100
114
+ }
115
+
116
+ # pipe result into new file
117
+ $ jsonpatch a.json patch.json --indent=2 > c.json
118
+
119
+ # c.json now equals b.json, so there is no difference to print
120
+ $ jsondiff b.json c.json
121
+
@@ -0,0 +1,37 @@
1
+ .. python-json-patch documentation master file, created by
2
+ sphinx-quickstart on Sat Apr 13 23:07:23 2013.
3
+ You can adapt this file completely to your liking, but it should at least
4
+ contain the root `toctree` directive.
5
+
6
+ python-json-patch
7
+ =================
8
+
9
+ `python-json-patch <https://github.com/stefankoegl/python-json-patch>`_
10
+ is a Python library for applying JSON patches (`RFC 6902
11
+ <https://datatracker.ietf.org/doc/html/rfc6902>`_). Python 3.10+ is
12
+ supported. Tests are run on both CPython and PyPy.
13
+
14
+ **Installation**
15
+
16
+ .. code-block:: bash
17
+
18
+ $ pip install jsonpatch
19
+
20
+ **Contents**
21
+
22
+ .. toctree::
23
+ :maxdepth: 2
24
+
25
+ tutorial
26
+ mod-jsonpatch
27
+ commandline
28
+ RFC 6902 <https://datatracker.ietf.org/doc/html/rfc6902>
29
+
30
+
31
+ Indices and tables
32
+ ==================
33
+
34
+ * :ref:`genindex`
35
+ * :ref:`modindex`
36
+ * :ref:`search`
37
+
@@ -0,0 +1,7 @@
1
+ .. mod-jsonpatch:
2
+
3
+ The ``jsonpatch`` module
4
+ ========================
5
+
6
+ .. automodule:: jsonpatch
7
+ :members:
@@ -0,0 +1,287 @@
1
+ Tutorial
2
+ ========
3
+
4
+ Please refer to `RFC 6902 <https://datatracker.ietf.org/doc/html/rfc6902>`_ for the exact
5
+ patch syntax.
6
+
7
+ Creating a Patch
8
+ ----------------
9
+
10
+ Patches can be created in two ways. One way is to explicitly create a
11
+ ``JsonPatch`` object from an iterable of operation dictionaries, such as a
12
+ list, tuple, iterator, or generator. Non-sequence iterables are materialized
13
+ before validation so that the patch can be applied repeatedly.
14
+ For convenience, the method
15
+ ``JsonPatch.from_string()`` accepts a string, parses it and constructs the
16
+ patch object from it.
17
+
18
+ .. code-block:: python
19
+
20
+ >>> import jsonpatch
21
+ >>> patch = jsonpatch.JsonPatch([
22
+ ... {'op': 'add', 'path': '/foo', 'value': 'bar'},
23
+ ... {'op': 'add', 'path': '/baz', 'value': [1, 2, 3]},
24
+ ... {'op': 'remove', 'path': '/baz/1'},
25
+ ... {'op': 'test', 'path': '/baz', 'value': [1, 3]},
26
+ ... {'op': 'replace', 'path': '/baz/0', 'value': 42},
27
+ ... {'op': 'remove', 'path': '/baz/1'},
28
+ ... ])
29
+
30
+ # or equivalently
31
+ >>> patch = jsonpatch.JsonPatch.from_string('''[
32
+ ... {"op": "add", "path": "/foo", "value": "bar"},
33
+ ... {"op": "add", "path": "/baz", "value": [1, 2, 3]},
34
+ ... {"op": "remove", "path": "/baz/1"},
35
+ ... {"op": "test", "path": "/baz", "value": [1, 3]},
36
+ ... {"op": "replace", "path": "/baz/0", "value": 42},
37
+ ... {"op": "remove", "path": "/baz/1"}
38
+ ... ]''')
39
+ >>> patch.apply({})
40
+ {'foo': 'bar', 'baz': [42]}
41
+
42
+ Another way is to *diff* two objects.
43
+
44
+ .. code-block:: python
45
+
46
+ >>> src = {'foo': 'bar', 'numbers': [1, 3, 4, 8]}
47
+ >>> dst = {'baz': 'qux', 'numbers': [1, 4, 7]}
48
+ >>> patch = jsonpatch.JsonPatch.from_diff(src, dst)
49
+
50
+ # or equivalently
51
+ >>> patch = jsonpatch.make_patch(src, dst)
52
+
53
+
54
+ Applying a Patch
55
+ ----------------
56
+
57
+ A patch is applied to a JSON document. The patch created by diffing ``src``
58
+ and ``dst`` above turns ``src`` into ``dst``:
59
+
60
+ .. code-block:: python
61
+
62
+ >>> result = patch.apply(src)
63
+ >>> result == dst
64
+ True
65
+
66
+ The ``apply`` method returns a new object as a result. If ``in_place=True`` the
67
+ object is modified in place.
68
+
69
+ The operations of a patch refer to locations in the object it is applied to.
70
+ A patch created with ``make_patch(src, dst)`` or ``JsonPatch.from_diff(src,
71
+ dst)`` must therefore be applied to ``src`` (or to an object equal to it).
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:
74
+
75
+ .. code-block:: python
76
+
77
+ >>> patch.apply(dst)
78
+ Traceback (most recent call last):
79
+ ...
80
+ jsonpatch.JsonPatchConflict: can't remove a non-existent object 'foo'
81
+
82
+ Applying it to an object with the same structure but different values may
83
+ succeed, though, and overwrite those values. With ``generate_test_ops=True``
84
+ each ``remove`` and ``replace`` operation is preceded by a ``test`` operation
85
+ that checks the value it removes or replaces. The patch then also records the
86
+ previous values, and fails with a ``JsonPatchTestFailed`` if they differ:
87
+
88
+ .. code-block:: python
89
+
90
+ >>> patch = jsonpatch.make_patch({'a': 1, 'b': 2}, {'a': 3},
91
+ ... generate_test_ops=True)
92
+ >>> patch.patch # doctest: +NORMALIZE_WHITESPACE
93
+ [{'op': 'test', 'path': '/b', 'value': 2}, {'op': 'remove', 'path': '/b'},
94
+ {'op': 'test', 'path': '/a', 'value': 1},
95
+ {'op': 'replace', 'path': '/a', 'value': 3}]
96
+ >>> patch.apply({'a': 5, 'b': 2})
97
+ Traceback (most recent call last):
98
+ ...
99
+ jsonpatch.JsonPatchTestFailed: 5 (<class 'int'>) is not equal to tested value 1 (<class 'int'>)
100
+
101
+ If a patch is only used once, it is not necessary to create a patch object
102
+ explicitly.
103
+
104
+ .. code-block:: python
105
+
106
+ >>> obj = {'foo': 'bar'}
107
+
108
+ # from a patch string
109
+ >>> patch = '[{"op": "add", "path": "/baz", "value": "qux"}]'
110
+ >>> res = jsonpatch.apply_patch(obj, patch)
111
+
112
+ # or from a list
113
+ >>> patch = [{'op': 'add', 'path': '/baz', 'value': 'qux'}]
114
+ >>> res = jsonpatch.apply_patch(obj, patch)
115
+
116
+
117
+ When an Operation Fails
118
+ ~~~~~~~~~~~~~~~~~~~~~~~
119
+
120
+ Operations are applied in order. If an operation raises an exception,
121
+ application stops. With the default ``in_place=False``, operations affect a
122
+ copy, so the original document is unchanged:
123
+
124
+ .. code-block:: python
125
+
126
+ >>> import jsonpatch
127
+ >>> original = {'value': 1}
128
+ >>> patch = [
129
+ ... {'op': 'replace', 'path': '/value', 'value': 2},
130
+ ... {'op': 'test', 'path': '/value', 'value': 3},
131
+ ... ]
132
+ >>> try:
133
+ ... jsonpatch.apply_patch(original, patch)
134
+ ... except jsonpatch.JsonPatchTestFailed:
135
+ ... print('Test failed')
136
+ Test failed
137
+ >>> original
138
+ {'value': 1}
139
+
140
+ With ``in_place=True``, the same patch raises ``JsonPatchTestFailed``, but
141
+ the earlier replacement remains in the original document. Failed patches
142
+ do not roll back changes already made in place:
143
+
144
+ .. code-block:: python
145
+
146
+ >>> try:
147
+ ... jsonpatch.apply_patch(original, patch, in_place=True)
148
+ ... except jsonpatch.JsonPatchTestFailed:
149
+ ... print('Test failed')
150
+ Test failed
151
+ >>> original
152
+ {'value': 2}
153
+
154
+
155
+ Replacing the Whole Document
156
+ ----------------------------
157
+
158
+ A document can be an object, array, string, number, boolean, or ``null``.
159
+ An empty ``path`` (``""``) selects the whole document, so a replacement can
160
+ also change its type:
161
+
162
+ .. code-block:: python
163
+
164
+ >>> import jsonpatch
165
+ >>> original = {'old': True}
166
+ >>> patch = jsonpatch.JsonPatch([
167
+ ... {'op': 'replace', 'path': '', 'value': [1, 2]}
168
+ ... ])
169
+ >>> result = patch.apply(original, in_place=True)
170
+ >>> result
171
+ [1, 2]
172
+ >>> original
173
+ {'old': True}
174
+
175
+ Always use the return value when an operation can replace the root, even
176
+ with ``in_place=True``. Replacing the root returns a new value; it cannot
177
+ rebind the caller's variable. Changes to members of the original container
178
+ can still happen in place.
179
+
180
+ The empty pointer differs from ``"/"``, which selects an object member
181
+ whose key is the empty string:
182
+
183
+ .. code-block:: python
184
+
185
+ >>> jsonpatch.apply_patch({'': 1}, [
186
+ ... {'op': 'replace', 'path': '/', 'value': 2}
187
+ ... ])
188
+ {'': 2}
189
+ >>> jsonpatch.apply_patch(None, [
190
+ ... {'op': 'add', 'path': '', 'value': False}
191
+ ... ])
192
+ False
193
+
194
+
195
+ Paths and Special Characters
196
+ ----------------------------
197
+
198
+ The ``path`` and ``from`` members of an operation are JSON Pointers
199
+ (`RFC 6901 <https://datatracker.ietf.org/doc/html/rfc6901>`_). A pointer is a sequence of
200
+ reference tokens, each starting with ``/``, and every token selects one object
201
+ key or array index. Because ``/`` separates the tokens, a key that contains
202
+ ``/`` or ``~`` has to be escaped: ``~`` is written as ``~0`` and ``/`` as
203
+ ``~1``.
204
+
205
+ Patches created by ``make_patch`` follow this rule, so a key containing ``/``
206
+ shows up escaped in the generated path.
207
+
208
+ .. code-block:: python
209
+
210
+ >>> patch = jsonpatch.make_patch({}, {'/fields/test': '123456'})
211
+ >>> patch.patch
212
+ [{'op': 'add', 'path': '/~1fields~1test', 'value': '123456'}]
213
+ >>> patch.apply({})
214
+ {'/fields/test': '123456'}
215
+
216
+ The unescaped path ``/fields/test`` would mean something different: the key
217
+ ``test`` inside the key ``fields``. Applying it to ``{}`` fails, because there
218
+ is no key ``fields``.
219
+
220
+ When writing a patch by hand, escape keys in the same way. The ``jsonpointer``
221
+ package, which ``jsonpatch`` depends on, can build a pointer from a list of
222
+ unescaped keys.
223
+
224
+ .. code-block:: python
225
+
226
+ >>> from jsonpointer import JsonPointer
227
+ >>> JsonPointer.from_parts(['/fields/test', 'a~b']).path
228
+ '/~1fields~1test/a~0b'
229
+
230
+
231
+ Dealing with Custom Types
232
+ -------------------------
233
+
234
+ Custom JSON dump and load functions can be used to support custom types such as
235
+ `decimal.Decimal`. The following examples shows how the
236
+ `simplejson <https://simplejson.readthedocs.io/>`_ package, which has native
237
+ support for Python's ``Decimal`` type, can be used to create a custom
238
+ ``JsonPatch`` subclass with ``Decimal`` support:
239
+
240
+ .. code-block:: python
241
+
242
+ >>> import decimal
243
+ >>> import simplejson
244
+
245
+ >>> class DecimalJsonPatch(jsonpatch.JsonPatch):
246
+ ... @staticmethod
247
+ ... def json_dumper(obj):
248
+ ... return simplejson.dumps(obj)
249
+ ...
250
+ ... @staticmethod
251
+ ... def json_loader(obj):
252
+ ... return simplejson.loads(obj, use_decimal=True,
253
+ ... object_pairs_hook=jsonpatch.multidict)
254
+
255
+ >>> src = {}
256
+ >>> dst = {'bar': decimal.Decimal('1.10')}
257
+ >>> patch = DecimalJsonPatch.from_diff(src, dst)
258
+ >>> doc = {'foo': 1}
259
+ >>> patch.apply(doc)
260
+ {'foo': 1, 'bar': Decimal('1.10')}
261
+
262
+ Instead of subclassing it is also possible to pass a dump function to
263
+ ``from_diff``:
264
+
265
+ .. code-block:: python
266
+
267
+ >>> patch = jsonpatch.JsonPatch.from_diff(src, dst, dumps=simplejson.dumps)
268
+
269
+ a dumps function to ``to_string``:
270
+
271
+ .. code-block:: python
272
+
273
+ >>> serialized_patch = patch.to_string(dumps=simplejson.dumps)
274
+ >>> serialized_patch
275
+ '[{"op": "add", "path": "/bar", "value": 1.10}]'
276
+
277
+ and load function to ``from_string``:
278
+
279
+ .. code-block:: python
280
+
281
+ >>> import functools
282
+ >>> loads = functools.partial(simplejson.loads, use_decimal=True,
283
+ ... object_pairs_hook=jsonpatch.multidict)
284
+ >>> patch = jsonpatch.JsonPatch.from_string(serialized_patch, loads=loads)
285
+ >>> doc = {'foo': 1}
286
+ >>> patch.apply(doc)
287
+ {'foo': 1, 'bar': Decimal('1.10')}
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: jsonpatch
3
- Version: 1.38
3
+ Version: 1.40
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
@@ -12,6 +12,10 @@ requirements.txt
12
12
  setup.py
13
13
  tests.js
14
14
  tests.py
15
+ doc/commandline.rst
16
+ doc/index.rst
17
+ doc/mod-jsonpatch.rst
18
+ doc/tutorial.rst
15
19
  jsonpatch.egg-info/PKG-INFO
16
20
  jsonpatch.egg-info/SOURCES.txt
17
21
  jsonpatch.egg-info/dependency_links.txt