jsonpatch 1.37__tar.gz → 1.39__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.37 → jsonpatch-1.39}/MANIFEST.in +1 -0
- {jsonpatch-1.37/jsonpatch.egg-info → jsonpatch-1.39}/PKG-INFO +1 -1
- jsonpatch-1.39/doc/commandline.rst +119 -0
- jsonpatch-1.39/doc/index.rst +37 -0
- jsonpatch-1.39/doc/mod-jsonpatch.rst +7 -0
- jsonpatch-1.39/doc/tutorial.rst +268 -0
- {jsonpatch-1.37 → jsonpatch-1.39/jsonpatch.egg-info}/PKG-INFO +1 -1
- {jsonpatch-1.37 → jsonpatch-1.39}/jsonpatch.egg-info/SOURCES.txt +4 -0
- {jsonpatch-1.37 → jsonpatch-1.39}/jsonpatch.py +32 -24
- {jsonpatch-1.37 → jsonpatch-1.39}/jsonpatch_cli.py +12 -0
- {jsonpatch-1.37 → jsonpatch-1.39}/tests.py +249 -20
- {jsonpatch-1.37 → jsonpatch-1.39}/AUTHORS +0 -0
- {jsonpatch-1.37 → jsonpatch-1.39}/LICENSE +0 -0
- {jsonpatch-1.37 → jsonpatch-1.39}/README.md +0 -0
- {jsonpatch-1.37 → jsonpatch-1.39}/ext_tests.py +0 -0
- {jsonpatch-1.37 → jsonpatch-1.39}/jsonpatch.egg-info/dependency_links.txt +0 -0
- {jsonpatch-1.37 → jsonpatch-1.39}/jsonpatch.egg-info/entry_points.txt +0 -0
- {jsonpatch-1.37 → jsonpatch-1.39}/jsonpatch.egg-info/requires.txt +0 -0
- {jsonpatch-1.37 → jsonpatch-1.39}/jsonpatch.egg-info/top_level.txt +0 -0
- {jsonpatch-1.37 → jsonpatch-1.39}/property_tests.py +0 -0
- {jsonpatch-1.37 → jsonpatch-1.39}/pyproject.toml +0 -0
- {jsonpatch-1.37 → jsonpatch-1.39}/pytest.ini +0 -0
- {jsonpatch-1.37 → jsonpatch-1.39}/requirements.txt +0 -0
- {jsonpatch-1.37 → jsonpatch-1.39}/setup.cfg +0 -0
- {jsonpatch-1.37 → jsonpatch-1.39}/setup.py +0 -0
- {jsonpatch-1.37 → jsonpatch-1.39}/tests.js +0 -0
|
@@ -0,0 +1,119 @@
|
|
|
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] [-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
|
+
-v, --version show program's version number and exit
|
|
31
|
+
|
|
32
|
+
Example
|
|
33
|
+
^^^^^^^
|
|
34
|
+
|
|
35
|
+
.. code-block:: bash
|
|
36
|
+
|
|
37
|
+
# inspect JSON files
|
|
38
|
+
$ cat a.json
|
|
39
|
+
{ "a": [1, 2], "b": 0 }
|
|
40
|
+
|
|
41
|
+
$ cat b.json
|
|
42
|
+
{ "a": [1, 2, 3], "c": 100 }
|
|
43
|
+
|
|
44
|
+
# show patch in "dense" representation
|
|
45
|
+
$ jsondiff a.json b.json
|
|
46
|
+
[{"op": "remove", "path": "/b"}, {"op": "add", "path": "/c", "value": 100}, {"op": "add", "path": "/a/2", "value": 3}]
|
|
47
|
+
|
|
48
|
+
# show patch with some indentation
|
|
49
|
+
$ jsondiff a.json b.json --indent=2
|
|
50
|
+
[
|
|
51
|
+
{
|
|
52
|
+
"op": "remove",
|
|
53
|
+
"path": "/b"
|
|
54
|
+
},
|
|
55
|
+
{
|
|
56
|
+
"op": "add",
|
|
57
|
+
"path": "/c",
|
|
58
|
+
"value": 100
|
|
59
|
+
},
|
|
60
|
+
{
|
|
61
|
+
"op": "add",
|
|
62
|
+
"path": "/a/2",
|
|
63
|
+
"value": 3
|
|
64
|
+
}
|
|
65
|
+
]
|
|
66
|
+
|
|
67
|
+
|
|
68
|
+
|
|
69
|
+
``jsonpatch``
|
|
70
|
+
-------------
|
|
71
|
+
|
|
72
|
+
The program ``jsonpatch`` is used to apply JSON patches on JSON files. ::
|
|
73
|
+
|
|
74
|
+
usage: jsonpatch [-h] [--indent INDENT] [-b] [-i] [-v] [-u] ORIGINAL [PATCH]
|
|
75
|
+
|
|
76
|
+
Apply a JSON patch on a JSON file
|
|
77
|
+
|
|
78
|
+
positional arguments:
|
|
79
|
+
ORIGINAL Original file
|
|
80
|
+
PATCH Patch file (read from stdin if omitted)
|
|
81
|
+
|
|
82
|
+
options:
|
|
83
|
+
-h, --help show this help message and exit
|
|
84
|
+
--indent INDENT Indent output by n spaces
|
|
85
|
+
-b, --backup Back up ORIGINAL if modifying in-place
|
|
86
|
+
-i, --in-place Modify ORIGINAL in-place instead of to stdout
|
|
87
|
+
-v, --version show program's version number and exit
|
|
88
|
+
-u, --preserve-unicode
|
|
89
|
+
Output Unicode character as-is without using Code
|
|
90
|
+
Point
|
|
91
|
+
|
|
92
|
+
Example
|
|
93
|
+
^^^^^^^
|
|
94
|
+
|
|
95
|
+
.. code-block:: bash
|
|
96
|
+
|
|
97
|
+
# create a patch
|
|
98
|
+
$ jsondiff a.json b.json > patch.json
|
|
99
|
+
|
|
100
|
+
# show the result after applying a patch
|
|
101
|
+
$ jsonpatch a.json patch.json
|
|
102
|
+
{"a": [1, 2, 3], "c": 100}
|
|
103
|
+
|
|
104
|
+
$ jsonpatch a.json patch.json --indent=2
|
|
105
|
+
{
|
|
106
|
+
"a": [
|
|
107
|
+
1,
|
|
108
|
+
2,
|
|
109
|
+
3
|
|
110
|
+
],
|
|
111
|
+
"c": 100
|
|
112
|
+
}
|
|
113
|
+
|
|
114
|
+
# pipe result into new file
|
|
115
|
+
$ jsonpatch a.json patch.json --indent=2 > c.json
|
|
116
|
+
|
|
117
|
+
# c.json now equals b.json, so there is no difference to print
|
|
118
|
+
$ jsondiff b.json c.json
|
|
119
|
+
|
|
@@ -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,268 @@
|
|
|
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
|
+
If a patch is only used once, it is not necessary to create a patch object
|
|
83
|
+
explicitly.
|
|
84
|
+
|
|
85
|
+
.. code-block:: python
|
|
86
|
+
|
|
87
|
+
>>> obj = {'foo': 'bar'}
|
|
88
|
+
|
|
89
|
+
# from a patch string
|
|
90
|
+
>>> patch = '[{"op": "add", "path": "/baz", "value": "qux"}]'
|
|
91
|
+
>>> res = jsonpatch.apply_patch(obj, patch)
|
|
92
|
+
|
|
93
|
+
# or from a list
|
|
94
|
+
>>> patch = [{'op': 'add', 'path': '/baz', 'value': 'qux'}]
|
|
95
|
+
>>> res = jsonpatch.apply_patch(obj, patch)
|
|
96
|
+
|
|
97
|
+
|
|
98
|
+
When an Operation Fails
|
|
99
|
+
~~~~~~~~~~~~~~~~~~~~~~~
|
|
100
|
+
|
|
101
|
+
Operations are applied in order. If an operation raises an exception,
|
|
102
|
+
application stops. With the default ``in_place=False``, operations affect a
|
|
103
|
+
copy, so the original document is unchanged:
|
|
104
|
+
|
|
105
|
+
.. code-block:: python
|
|
106
|
+
|
|
107
|
+
>>> import jsonpatch
|
|
108
|
+
>>> original = {'value': 1}
|
|
109
|
+
>>> patch = [
|
|
110
|
+
... {'op': 'replace', 'path': '/value', 'value': 2},
|
|
111
|
+
... {'op': 'test', 'path': '/value', 'value': 3},
|
|
112
|
+
... ]
|
|
113
|
+
>>> try:
|
|
114
|
+
... jsonpatch.apply_patch(original, patch)
|
|
115
|
+
... except jsonpatch.JsonPatchTestFailed:
|
|
116
|
+
... print('Test failed')
|
|
117
|
+
Test failed
|
|
118
|
+
>>> original
|
|
119
|
+
{'value': 1}
|
|
120
|
+
|
|
121
|
+
With ``in_place=True``, the same patch raises ``JsonPatchTestFailed``, but
|
|
122
|
+
the earlier replacement remains in the original document. Failed patches
|
|
123
|
+
do not roll back changes already made in place:
|
|
124
|
+
|
|
125
|
+
.. code-block:: python
|
|
126
|
+
|
|
127
|
+
>>> try:
|
|
128
|
+
... jsonpatch.apply_patch(original, patch, in_place=True)
|
|
129
|
+
... except jsonpatch.JsonPatchTestFailed:
|
|
130
|
+
... print('Test failed')
|
|
131
|
+
Test failed
|
|
132
|
+
>>> original
|
|
133
|
+
{'value': 2}
|
|
134
|
+
|
|
135
|
+
|
|
136
|
+
Replacing the Whole Document
|
|
137
|
+
----------------------------
|
|
138
|
+
|
|
139
|
+
A document can be an object, array, string, number, boolean, or ``null``.
|
|
140
|
+
An empty ``path`` (``""``) selects the whole document, so a replacement can
|
|
141
|
+
also change its type:
|
|
142
|
+
|
|
143
|
+
.. code-block:: python
|
|
144
|
+
|
|
145
|
+
>>> import jsonpatch
|
|
146
|
+
>>> original = {'old': True}
|
|
147
|
+
>>> patch = jsonpatch.JsonPatch([
|
|
148
|
+
... {'op': 'replace', 'path': '', 'value': [1, 2]}
|
|
149
|
+
... ])
|
|
150
|
+
>>> result = patch.apply(original, in_place=True)
|
|
151
|
+
>>> result
|
|
152
|
+
[1, 2]
|
|
153
|
+
>>> original
|
|
154
|
+
{'old': True}
|
|
155
|
+
|
|
156
|
+
Always use the return value when an operation can replace the root, even
|
|
157
|
+
with ``in_place=True``. Replacing the root returns a new value; it cannot
|
|
158
|
+
rebind the caller's variable. Changes to members of the original container
|
|
159
|
+
can still happen in place.
|
|
160
|
+
|
|
161
|
+
The empty pointer differs from ``"/"``, which selects an object member
|
|
162
|
+
whose key is the empty string:
|
|
163
|
+
|
|
164
|
+
.. code-block:: python
|
|
165
|
+
|
|
166
|
+
>>> jsonpatch.apply_patch({'': 1}, [
|
|
167
|
+
... {'op': 'replace', 'path': '/', 'value': 2}
|
|
168
|
+
... ])
|
|
169
|
+
{'': 2}
|
|
170
|
+
>>> jsonpatch.apply_patch(None, [
|
|
171
|
+
... {'op': 'add', 'path': '', 'value': False}
|
|
172
|
+
... ])
|
|
173
|
+
False
|
|
174
|
+
|
|
175
|
+
|
|
176
|
+
Paths and Special Characters
|
|
177
|
+
----------------------------
|
|
178
|
+
|
|
179
|
+
The ``path`` and ``from`` members of an operation are JSON Pointers
|
|
180
|
+
(`RFC 6901 <https://datatracker.ietf.org/doc/html/rfc6901>`_). A pointer is a sequence of
|
|
181
|
+
reference tokens, each starting with ``/``, and every token selects one object
|
|
182
|
+
key or array index. Because ``/`` separates the tokens, a key that contains
|
|
183
|
+
``/`` or ``~`` has to be escaped: ``~`` is written as ``~0`` and ``/`` as
|
|
184
|
+
``~1``.
|
|
185
|
+
|
|
186
|
+
Patches created by ``make_patch`` follow this rule, so a key containing ``/``
|
|
187
|
+
shows up escaped in the generated path.
|
|
188
|
+
|
|
189
|
+
.. code-block:: python
|
|
190
|
+
|
|
191
|
+
>>> patch = jsonpatch.make_patch({}, {'/fields/test': '123456'})
|
|
192
|
+
>>> patch.patch
|
|
193
|
+
[{'op': 'add', 'path': '/~1fields~1test', 'value': '123456'}]
|
|
194
|
+
>>> patch.apply({})
|
|
195
|
+
{'/fields/test': '123456'}
|
|
196
|
+
|
|
197
|
+
The unescaped path ``/fields/test`` would mean something different: the key
|
|
198
|
+
``test`` inside the key ``fields``. Applying it to ``{}`` fails, because there
|
|
199
|
+
is no key ``fields``.
|
|
200
|
+
|
|
201
|
+
When writing a patch by hand, escape keys in the same way. The ``jsonpointer``
|
|
202
|
+
package, which ``jsonpatch`` depends on, can build a pointer from a list of
|
|
203
|
+
unescaped keys.
|
|
204
|
+
|
|
205
|
+
.. code-block:: python
|
|
206
|
+
|
|
207
|
+
>>> from jsonpointer import JsonPointer
|
|
208
|
+
>>> JsonPointer.from_parts(['/fields/test', 'a~b']).path
|
|
209
|
+
'/~1fields~1test/a~0b'
|
|
210
|
+
|
|
211
|
+
|
|
212
|
+
Dealing with Custom Types
|
|
213
|
+
-------------------------
|
|
214
|
+
|
|
215
|
+
Custom JSON dump and load functions can be used to support custom types such as
|
|
216
|
+
`decimal.Decimal`. The following examples shows how the
|
|
217
|
+
`simplejson <https://simplejson.readthedocs.io/>`_ package, which has native
|
|
218
|
+
support for Python's ``Decimal`` type, can be used to create a custom
|
|
219
|
+
``JsonPatch`` subclass with ``Decimal`` support:
|
|
220
|
+
|
|
221
|
+
.. code-block:: python
|
|
222
|
+
|
|
223
|
+
>>> import decimal
|
|
224
|
+
>>> import simplejson
|
|
225
|
+
|
|
226
|
+
>>> class DecimalJsonPatch(jsonpatch.JsonPatch):
|
|
227
|
+
... @staticmethod
|
|
228
|
+
... def json_dumper(obj):
|
|
229
|
+
... return simplejson.dumps(obj)
|
|
230
|
+
...
|
|
231
|
+
... @staticmethod
|
|
232
|
+
... def json_loader(obj):
|
|
233
|
+
... return simplejson.loads(obj, use_decimal=True,
|
|
234
|
+
... object_pairs_hook=jsonpatch.multidict)
|
|
235
|
+
|
|
236
|
+
>>> src = {}
|
|
237
|
+
>>> dst = {'bar': decimal.Decimal('1.10')}
|
|
238
|
+
>>> patch = DecimalJsonPatch.from_diff(src, dst)
|
|
239
|
+
>>> doc = {'foo': 1}
|
|
240
|
+
>>> patch.apply(doc)
|
|
241
|
+
{'foo': 1, 'bar': Decimal('1.10')}
|
|
242
|
+
|
|
243
|
+
Instead of subclassing it is also possible to pass a dump function to
|
|
244
|
+
``from_diff``:
|
|
245
|
+
|
|
246
|
+
.. code-block:: python
|
|
247
|
+
|
|
248
|
+
>>> patch = jsonpatch.JsonPatch.from_diff(src, dst, dumps=simplejson.dumps)
|
|
249
|
+
|
|
250
|
+
a dumps function to ``to_string``:
|
|
251
|
+
|
|
252
|
+
.. code-block:: python
|
|
253
|
+
|
|
254
|
+
>>> serialized_patch = patch.to_string(dumps=simplejson.dumps)
|
|
255
|
+
>>> serialized_patch
|
|
256
|
+
'[{"op": "add", "path": "/bar", "value": 1.10}]'
|
|
257
|
+
|
|
258
|
+
and load function to ``from_string``:
|
|
259
|
+
|
|
260
|
+
.. code-block:: python
|
|
261
|
+
|
|
262
|
+
>>> import functools
|
|
263
|
+
>>> loads = functools.partial(simplejson.loads, use_decimal=True,
|
|
264
|
+
... object_pairs_hook=jsonpatch.multidict)
|
|
265
|
+
>>> patch = jsonpatch.JsonPatch.from_string(serialized_patch, loads=loads)
|
|
266
|
+
>>> doc = {'foo': 1}
|
|
267
|
+
>>> patch.apply(doc)
|
|
268
|
+
{'foo': 1, 'bar': Decimal('1.10')}
|
|
@@ -37,7 +37,8 @@ import collections
|
|
|
37
37
|
import copy
|
|
38
38
|
import functools
|
|
39
39
|
import json
|
|
40
|
-
from collections.abc import Mapping, MutableMapping, MutableSequence,
|
|
40
|
+
from collections.abc import (Mapping, MutableMapping, MutableSequence,
|
|
41
|
+
Sequence)
|
|
41
42
|
from difflib import SequenceMatcher
|
|
42
43
|
from types import MappingProxyType
|
|
43
44
|
|
|
@@ -54,7 +55,7 @@ _EXACT_MATCH_LIMIT = 500 ** 2
|
|
|
54
55
|
|
|
55
56
|
# Will be parsed by setup.py to determine package metadata
|
|
56
57
|
__author__ = 'Stefan Kögl <stefan@skoegl.net>'
|
|
57
|
-
__version__ = '1.
|
|
58
|
+
__version__ = '1.39'
|
|
58
59
|
__website__ = 'https://github.com/stefankoegl/python-json-patch'
|
|
59
60
|
__license__ = 'BSD-3-Clause'
|
|
60
61
|
|
|
@@ -100,13 +101,13 @@ _jsonloads = functools.partial(json.loads, object_pairs_hook=multidict)
|
|
|
100
101
|
|
|
101
102
|
|
|
102
103
|
def apply_patch(doc, patch, in_place=False, pointer_cls=JsonPointer):
|
|
103
|
-
"""Apply
|
|
104
|
+
"""Apply patch operations to the specified JSON document.
|
|
104
105
|
|
|
105
|
-
:param doc:
|
|
106
|
-
:type doc:
|
|
106
|
+
:param doc: JSON document, including arrays and scalar values.
|
|
107
|
+
:type doc: object
|
|
107
108
|
|
|
108
|
-
:param patch:
|
|
109
|
-
:type patch:
|
|
109
|
+
:param patch: Iterable of operation dicts or a raw JSON-encoded string.
|
|
110
|
+
:type patch: iterable or str
|
|
110
111
|
|
|
111
112
|
:param in_place: While ``True`` patch will modify target document.
|
|
112
113
|
By default patch will be applied to document copy.
|
|
@@ -115,8 +116,8 @@ def apply_patch(doc, patch, in_place=False, pointer_cls=JsonPointer):
|
|
|
115
116
|
:param pointer_cls: JSON pointer class to use.
|
|
116
117
|
:type pointer_cls: Type[JsonPointer]
|
|
117
118
|
|
|
118
|
-
:return:
|
|
119
|
-
:rtype:
|
|
119
|
+
:return: Resulting document, which may have a different type from ``doc``.
|
|
120
|
+
:rtype: object
|
|
120
121
|
|
|
121
122
|
>>> doc = {'foo': 'bar'}
|
|
122
123
|
>>> patch = [{'op': 'add', 'path': '/baz', 'value': 'qux'}]
|
|
@@ -145,11 +146,11 @@ def make_patch(src, dst, pointer_cls=JsonPointer):
|
|
|
145
146
|
transforms `src` into `dst`, so it has to be applied to `src` (or to a
|
|
146
147
|
document equal to it).
|
|
147
148
|
|
|
148
|
-
:param src:
|
|
149
|
-
:type src:
|
|
149
|
+
:param src: Source JSON document, including arrays and scalar values.
|
|
150
|
+
:type src: object
|
|
150
151
|
|
|
151
|
-
:param dst:
|
|
152
|
-
:type dst:
|
|
152
|
+
:param dst: Target JSON document, including arrays and scalar values.
|
|
153
|
+
:type dst: object
|
|
153
154
|
|
|
154
155
|
:param pointer_cls: JSON pointer class to use.
|
|
155
156
|
:type pointer_cls: Type[JsonPointer]
|
|
@@ -262,6 +263,8 @@ class RemoveOperation(PatchOperation):
|
|
|
262
263
|
except (KeyError, IndexError):
|
|
263
264
|
msg = "can't remove a non-existent object '{0}'".format(part)
|
|
264
265
|
raise JsonPatchConflict(msg)
|
|
266
|
+
except TypeError as ex:
|
|
267
|
+
raise JsonPatchConflict(str(ex))
|
|
265
268
|
|
|
266
269
|
return obj
|
|
267
270
|
|
|
@@ -457,7 +460,11 @@ class CopyOperation(PatchOperation):
|
|
|
457
460
|
|
|
458
461
|
|
|
459
462
|
class JsonPatch(object):
|
|
460
|
-
"""A JSON Patch is
|
|
463
|
+
"""A JSON Patch is an iterable of Patch Operations.
|
|
464
|
+
|
|
465
|
+
Accepts sequences, iterators, generators, and other iterables of operation
|
|
466
|
+
dictionaries. Non-sequence inputs are materialized before validation so
|
|
467
|
+
the resulting patch can be applied repeatedly.
|
|
461
468
|
|
|
462
469
|
>>> patch = JsonPatch([
|
|
463
470
|
... {'op': 'add', 'path': '/foo', 'value': 'bar'},
|
|
@@ -515,13 +522,12 @@ class JsonPatch(object):
|
|
|
515
522
|
})
|
|
516
523
|
|
|
517
524
|
def __init__(self, patch, pointer_cls=JsonPointer):
|
|
518
|
-
self.patch = patch
|
|
519
525
|
self.pointer_cls = pointer_cls
|
|
520
526
|
|
|
521
527
|
if isinstance(patch, (str, bytes, Mapping)):
|
|
522
528
|
raise InvalidJsonPatch("Document is expected to be sequence of operations")
|
|
523
529
|
try:
|
|
524
|
-
|
|
530
|
+
self.patch = patch if isinstance(patch, Sequence) else list(patch)
|
|
525
531
|
except TypeError:
|
|
526
532
|
raise InvalidJsonPatch("Document is expected to be sequence of operations")
|
|
527
533
|
|
|
@@ -529,7 +535,7 @@ class JsonPatch(object):
|
|
|
529
535
|
# is correct by retrieving each patch element.
|
|
530
536
|
# Much of the validation is done in the initializer
|
|
531
537
|
# though some is delayed until the patch is applied.
|
|
532
|
-
for op in
|
|
538
|
+
for op in self.patch:
|
|
533
539
|
# We're only checking for strings in the following check
|
|
534
540
|
# for two reasons:
|
|
535
541
|
#
|
|
@@ -598,11 +604,11 @@ class JsonPatch(object):
|
|
|
598
604
|
one. The resulting patch transforms `src` into `dst`, so it has to be
|
|
599
605
|
applied to `src` (or to a document equal to it).
|
|
600
606
|
|
|
601
|
-
:param src:
|
|
602
|
-
:type src:
|
|
607
|
+
:param src: Source JSON document, including arrays and scalar values.
|
|
608
|
+
:type src: object
|
|
603
609
|
|
|
604
|
-
:param dst:
|
|
605
|
-
:type dst:
|
|
610
|
+
:param dst: Target JSON document, including arrays and scalar values.
|
|
611
|
+
:type dst: object
|
|
606
612
|
|
|
607
613
|
:param optimization: Generate move operations for matching values.
|
|
608
614
|
Set to False to use only add, remove and replace.
|
|
@@ -643,14 +649,16 @@ class JsonPatch(object):
|
|
|
643
649
|
def apply(self, obj, in_place=False):
|
|
644
650
|
"""Applies the patch to a given object.
|
|
645
651
|
|
|
646
|
-
:param obj:
|
|
647
|
-
:type obj:
|
|
652
|
+
:param obj: JSON document, including arrays and scalar values.
|
|
653
|
+
:type obj: object
|
|
648
654
|
|
|
649
655
|
:param in_place: Tweaks the way how patch would be applied - directly to
|
|
650
656
|
specified `obj` or to its copy.
|
|
651
657
|
:type in_place: bool
|
|
652
658
|
|
|
653
|
-
:return:
|
|
659
|
+
:return: Resulting document. Use this return value even with
|
|
660
|
+
``in_place=True``, because a root replacement returns a new
|
|
661
|
+
value rather than modifying the original container.
|
|
654
662
|
"""
|
|
655
663
|
|
|
656
664
|
if not in_place:
|
|
@@ -78,6 +78,7 @@ def patch_files():
|
|
|
78
78
|
args.ORIGINAL.close()
|
|
79
79
|
dirname = os.path.abspath(os.path.dirname(args.ORIGINAL.name))
|
|
80
80
|
|
|
81
|
+
fd = None
|
|
81
82
|
try:
|
|
82
83
|
# Attempt to replace the file atomically. We do this by
|
|
83
84
|
# creating a temporary file in the same directory as the
|
|
@@ -90,6 +91,17 @@ def patch_files():
|
|
|
90
91
|
atomic = True
|
|
91
92
|
|
|
92
93
|
except OSError:
|
|
94
|
+
# mkstemp may have succeeded before fdopen failed. Neither the
|
|
95
|
+
# descriptor nor the temporary file belongs to the fallback.
|
|
96
|
+
if fd is not None:
|
|
97
|
+
try:
|
|
98
|
+
os.close(fd)
|
|
99
|
+
except OSError:
|
|
100
|
+
pass
|
|
101
|
+
try:
|
|
102
|
+
os.unlink(pathname)
|
|
103
|
+
except OSError:
|
|
104
|
+
pass
|
|
93
105
|
# We failed to create the temporary file for an atomic
|
|
94
106
|
# replace, so fall back to non-atomic mode by backing up
|
|
95
107
|
# the original (if desired) and writing a new file.
|
|
@@ -1,7 +1,9 @@
|
|
|
1
1
|
#!/usr/bin/env python
|
|
2
2
|
# -*- coding: utf-8 -*-
|
|
3
3
|
|
|
4
|
+
import contextlib
|
|
4
5
|
import copy
|
|
6
|
+
import io
|
|
5
7
|
import json
|
|
6
8
|
import decimal
|
|
7
9
|
import doctest
|
|
@@ -10,6 +12,7 @@ import jsonpatch
|
|
|
10
12
|
import jsonpatch_cli
|
|
11
13
|
import jsonpointer
|
|
12
14
|
import random
|
|
15
|
+
import shlex
|
|
13
16
|
import sys
|
|
14
17
|
import os
|
|
15
18
|
import stat
|
|
@@ -21,6 +24,51 @@ from unittest import mock
|
|
|
21
24
|
|
|
22
25
|
class ApplyPatchTestCase(unittest.TestCase):
|
|
23
26
|
|
|
27
|
+
def test_operation_iterators_remain_reusable_after_validation(self):
|
|
28
|
+
operations = [
|
|
29
|
+
{'op': 'add', 'path': '/a', 'value': 1},
|
|
30
|
+
{'op': 'replace', 'path': '/a', 'value': 2},
|
|
31
|
+
]
|
|
32
|
+
class OneShotIterable:
|
|
33
|
+
def __init__(self, ops):
|
|
34
|
+
self.iterator = iter(ops)
|
|
35
|
+
|
|
36
|
+
def __iter__(self):
|
|
37
|
+
return self.iterator
|
|
38
|
+
|
|
39
|
+
for name, factory in (
|
|
40
|
+
('iterator', iter),
|
|
41
|
+
('generator', lambda ops: (op for op in ops)),
|
|
42
|
+
('one-shot iterable', OneShotIterable),
|
|
43
|
+
):
|
|
44
|
+
with self.subTest(name=name):
|
|
45
|
+
patch = jsonpatch.JsonPatch(factory(operations))
|
|
46
|
+
self.assertEqual(list(patch), operations)
|
|
47
|
+
self.assertEqual(json.loads(patch.to_string()), operations)
|
|
48
|
+
self.assertEqual(patch.apply({}), {'a': 2})
|
|
49
|
+
self.assertEqual(patch.apply({}), {'a': 2})
|
|
50
|
+
|
|
51
|
+
def test_empty_operation_iterator_is_false(self):
|
|
52
|
+
patch = jsonpatch.JsonPatch(iter([]))
|
|
53
|
+
self.assertFalse(patch)
|
|
54
|
+
self.assertEqual(patch.to_string(), '[]')
|
|
55
|
+
|
|
56
|
+
def test_invalid_operation_iterator_is_rejected(self):
|
|
57
|
+
operations = iter([
|
|
58
|
+
{'op': 'add', 'path': '/a', 'value': 1},
|
|
59
|
+
{'op': 'not-an-operation', 'path': '/a'},
|
|
60
|
+
])
|
|
61
|
+
with self.assertRaises(jsonpatch.InvalidJsonPatch):
|
|
62
|
+
jsonpatch.JsonPatch(operations)
|
|
63
|
+
|
|
64
|
+
def test_sequence_operations_preserve_contents(self):
|
|
65
|
+
operations = [{'op': 'add', 'path': '/a', 'value': 1}]
|
|
66
|
+
for sequence in (operations, tuple(operations)):
|
|
67
|
+
with self.subTest(sequence=type(sequence).__name__):
|
|
68
|
+
patch = jsonpatch.JsonPatch(sequence)
|
|
69
|
+
self.assertEqual(list(patch), operations)
|
|
70
|
+
self.assertEqual(patch.apply({}), {'a': 1})
|
|
71
|
+
|
|
24
72
|
def test_diff_without_optimization_uses_basic_operations(self):
|
|
25
73
|
documents = [
|
|
26
74
|
({'old': {'value': 1}}, {'new': {'value': 1}}),
|
|
@@ -1401,6 +1449,56 @@ class ConflictTests(unittest.TestCase):
|
|
|
1401
1449
|
patch_obj = [ { "op": "remove", "path": "/foo/non-existent"} ]
|
|
1402
1450
|
self.assertRaises(jsonpatch.JsonPatchConflict, jsonpatch.apply_patch, src, patch_obj)
|
|
1403
1451
|
|
|
1452
|
+
def test_remove_from_immutable_sequence(self):
|
|
1453
|
+
for src, path in [((1, 2), '/0'), ({'foo': (1, 2)}, '/foo/0')]:
|
|
1454
|
+
for in_place in (False, True):
|
|
1455
|
+
with self.subTest(src=src, in_place=in_place):
|
|
1456
|
+
original = copy.deepcopy(src)
|
|
1457
|
+
patch_obj = [{'op': 'remove', 'path': path}]
|
|
1458
|
+
with self.assertRaises(jsonpatch.JsonPatchConflict):
|
|
1459
|
+
jsonpatch.apply_patch(src, patch_obj, in_place=in_place)
|
|
1460
|
+
self.assertEqual(src, original)
|
|
1461
|
+
|
|
1462
|
+
def test_remove_from_read_only_mapping(self):
|
|
1463
|
+
for nested in (False, True):
|
|
1464
|
+
with self.subTest(nested=nested):
|
|
1465
|
+
data = {'foo': 1}
|
|
1466
|
+
src = MappingProxyType(data)
|
|
1467
|
+
path = '/foo'
|
|
1468
|
+
if nested:
|
|
1469
|
+
src = {'bar': src}
|
|
1470
|
+
path = '/bar/foo'
|
|
1471
|
+
patch_obj = [{'op': 'remove', 'path': path}]
|
|
1472
|
+
with self.assertRaises(jsonpatch.JsonPatchConflict):
|
|
1473
|
+
jsonpatch.apply_patch(src, patch_obj, in_place=True)
|
|
1474
|
+
self.assertEqual(data, {'foo': 1})
|
|
1475
|
+
|
|
1476
|
+
def test_move_from_immutable_sequence(self):
|
|
1477
|
+
for in_place in (False, True):
|
|
1478
|
+
with self.subTest(in_place=in_place):
|
|
1479
|
+
src = {'foo': (1, 2), 'bar': []}
|
|
1480
|
+
patch_obj = [{'op': 'move', 'from': '/foo/0', 'path': '/bar/-'}]
|
|
1481
|
+
with self.assertRaises(jsonpatch.JsonPatchConflict):
|
|
1482
|
+
jsonpatch.apply_patch(src, patch_obj, in_place=in_place)
|
|
1483
|
+
self.assertEqual(src, {'foo': (1, 2), 'bar': []})
|
|
1484
|
+
|
|
1485
|
+
def test_remove_from_duck_typed_mapping(self):
|
|
1486
|
+
class IndexedObject:
|
|
1487
|
+
def __init__(self):
|
|
1488
|
+
self.data = {'foo': 1, 'bar': 2}
|
|
1489
|
+
|
|
1490
|
+
def __getitem__(self, key):
|
|
1491
|
+
return self.data[key]
|
|
1492
|
+
|
|
1493
|
+
def __delitem__(self, key):
|
|
1494
|
+
del self.data[key]
|
|
1495
|
+
|
|
1496
|
+
src = IndexedObject()
|
|
1497
|
+
patch_obj = [{'op': 'remove', 'path': '/foo'}]
|
|
1498
|
+
result = jsonpatch.apply_patch(src, patch_obj, in_place=True)
|
|
1499
|
+
self.assertIs(result, src)
|
|
1500
|
+
self.assertEqual(src.data, {'bar': 2})
|
|
1501
|
+
|
|
1404
1502
|
def test_insert_oob(self):
|
|
1405
1503
|
src = {"foo": [1, 2]}
|
|
1406
1504
|
patch_obj = [ { "op": "add", "path": "/foo/10", "value": 1} ]
|
|
@@ -1885,7 +1983,31 @@ class CustomOperationTests(unittest.TestCase):
|
|
|
1885
1983
|
self.assertEqual(res, {})
|
|
1886
1984
|
|
|
1887
1985
|
|
|
1888
|
-
class
|
|
1986
|
+
class ScriptRunner:
|
|
1987
|
+
""" Runs the command line programs of this checkout """
|
|
1988
|
+
|
|
1989
|
+
def run_python(self, code, *args, stdin='', utf8=True, cwd=None):
|
|
1990
|
+
here = os.path.dirname(os.path.abspath(__file__))
|
|
1991
|
+
# the scripts have to import this jsonpatch, not an installed one
|
|
1992
|
+
pythonpath = [here] + [p for p in [os.environ.get('PYTHONPATH')] if p]
|
|
1993
|
+
env = dict(os.environ, PYTHONPATH=os.pathsep.join(pythonpath),
|
|
1994
|
+
PYTHONUTF8='1')
|
|
1995
|
+
if not utf8:
|
|
1996
|
+
# Exercise locale-dependent file I/O while keeping pipes in UTF-8.
|
|
1997
|
+
env.update(PYTHONUTF8='0', PYTHONIOENCODING='utf-8',
|
|
1998
|
+
LC_ALL='C', PYTHONCOERCECLOCALE='0')
|
|
1999
|
+
return subprocess.run(
|
|
2000
|
+
[sys.executable, '-c', code] + list(args),
|
|
2001
|
+
input=stdin, capture_output=True, encoding='utf-8', env=env,
|
|
2002
|
+
cwd=cwd)
|
|
2003
|
+
|
|
2004
|
+
def run_script(self, script, *args, stdin='', utf8=True, cwd=None):
|
|
2005
|
+
return self.run_python(
|
|
2006
|
+
'import jsonpatch_cli; jsonpatch_cli.{0}_main()'.format(script),
|
|
2007
|
+
*args, stdin=stdin, utf8=utf8, cwd=cwd)
|
|
2008
|
+
|
|
2009
|
+
|
|
2010
|
+
class CommandLineTests(ScriptRunner, unittest.TestCase):
|
|
1889
2011
|
""" The jsondiff and jsonpatch command line programs """
|
|
1890
2012
|
|
|
1891
2013
|
def setUp(self):
|
|
@@ -1903,25 +2025,6 @@ class CommandLineTests(unittest.TestCase):
|
|
|
1903
2025
|
with open(path, encoding='utf-8') as f:
|
|
1904
2026
|
return json.load(f)
|
|
1905
2027
|
|
|
1906
|
-
def run_python(self, code, *args, stdin='', utf8=True):
|
|
1907
|
-
here = os.path.dirname(os.path.abspath(__file__))
|
|
1908
|
-
# the scripts have to import this jsonpatch, not an installed one
|
|
1909
|
-
pythonpath = [here] + [p for p in [os.environ.get('PYTHONPATH')] if p]
|
|
1910
|
-
env = dict(os.environ, PYTHONPATH=os.pathsep.join(pythonpath),
|
|
1911
|
-
PYTHONUTF8='1')
|
|
1912
|
-
if not utf8:
|
|
1913
|
-
# Exercise locale-dependent file I/O while keeping pipes in UTF-8.
|
|
1914
|
-
env.update(PYTHONUTF8='0', PYTHONIOENCODING='utf-8',
|
|
1915
|
-
LC_ALL='C', PYTHONCOERCECLOCALE='0')
|
|
1916
|
-
return subprocess.run(
|
|
1917
|
-
[sys.executable, '-c', code] + list(args),
|
|
1918
|
-
input=stdin, capture_output=True, encoding='utf-8', env=env)
|
|
1919
|
-
|
|
1920
|
-
def run_script(self, script, *args, stdin='', utf8=True):
|
|
1921
|
-
return self.run_python(
|
|
1922
|
-
'import jsonpatch_cli; jsonpatch_cli.{0}_main()'.format(script),
|
|
1923
|
-
*args, stdin=stdin, utf8=utf8)
|
|
1924
|
-
|
|
1925
2028
|
def test_jsondiff(self):
|
|
1926
2029
|
src = self.write('a.json', {'a': [1, 2], 'b': 0})
|
|
1927
2030
|
dst = self.write('b.json', {'a': [1, 2, 3], 'c': 100})
|
|
@@ -2114,6 +2217,45 @@ class CommandLineTests(unittest.TestCase):
|
|
|
2114
2217
|
self.assertEqual(self.read(doc), {'a': 1})
|
|
2115
2218
|
self.assertEqual(sorted(os.listdir(self.dir)), ['doc.json', 'patch.json'])
|
|
2116
2219
|
|
|
2220
|
+
def test_jsonpatch_in_place_cleans_temp_on_fdopen_error(self):
|
|
2221
|
+
for backup in (False, True):
|
|
2222
|
+
with self.subTest(backup=backup):
|
|
2223
|
+
tmp = tempfile.TemporaryDirectory()
|
|
2224
|
+
self.addCleanup(tmp.cleanup)
|
|
2225
|
+
self.dir = tmp.name
|
|
2226
|
+
doc = self.write('doc.json', {'a': 1})
|
|
2227
|
+
patch = self.write('patch.json', [{'op': 'replace', 'path': '/a', 'value': 2}])
|
|
2228
|
+
parser = jsonpatch_cli.jsonpatch_parser
|
|
2229
|
+
args = parser.parse_args(['-i', doc, patch] + (['-b'] if backup else []))
|
|
2230
|
+
self.addCleanup(args.ORIGINAL.close)
|
|
2231
|
+
self.addCleanup(args.PATCH.close)
|
|
2232
|
+
descriptors = []
|
|
2233
|
+
|
|
2234
|
+
def close_if_open(fd):
|
|
2235
|
+
try:
|
|
2236
|
+
os.close(fd)
|
|
2237
|
+
except OSError:
|
|
2238
|
+
pass
|
|
2239
|
+
|
|
2240
|
+
def fail_fdopen(fd, *args, **kwargs):
|
|
2241
|
+
descriptors.append(fd)
|
|
2242
|
+
self.addCleanup(close_if_open, fd)
|
|
2243
|
+
raise OSError('cannot wrap temporary descriptor')
|
|
2244
|
+
|
|
2245
|
+
with mock.patch.object(parser, 'parse_args', return_value=args), \
|
|
2246
|
+
mock.patch('os.fdopen', side_effect=fail_fdopen):
|
|
2247
|
+
jsonpatch_cli.patch_files()
|
|
2248
|
+
|
|
2249
|
+
self.assertEqual(self.read(doc), {'a': 2})
|
|
2250
|
+
if backup:
|
|
2251
|
+
self.assertEqual(self.read(doc + '.orig'), {'a': 1})
|
|
2252
|
+
with self.assertRaises(OSError):
|
|
2253
|
+
os.fstat(descriptors[0])
|
|
2254
|
+
expected = ['doc.json', 'patch.json']
|
|
2255
|
+
if backup:
|
|
2256
|
+
expected.append('doc.json.orig')
|
|
2257
|
+
self.assertEqual(sorted(os.listdir(self.dir)), sorted(expected))
|
|
2258
|
+
|
|
2117
2259
|
def test_jsonpatch_in_place_preserves_original_on_replace_error(self):
|
|
2118
2260
|
doc = self.write('doc.json', {'a': 1})
|
|
2119
2261
|
patch = self.write('patch.json', [{'op': 'replace', 'path': '/a', 'value': 2}])
|
|
@@ -2177,6 +2319,92 @@ class CommandLineTests(unittest.TestCase):
|
|
|
2177
2319
|
self.assertEqual(res.stdout, '{0} {1}\n'.format(script, jsonpatch.__version__))
|
|
2178
2320
|
|
|
2179
2321
|
|
|
2322
|
+
class DocumentationTests(ScriptRunner, unittest.TestCase):
|
|
2323
|
+
""" The code examples in the documentation run and give the shown output """
|
|
2324
|
+
|
|
2325
|
+
doc_dir = os.path.join(os.path.dirname(os.path.abspath(__file__)), 'doc')
|
|
2326
|
+
|
|
2327
|
+
def doc_path(self, name):
|
|
2328
|
+
path = os.path.join(self.doc_dir, name)
|
|
2329
|
+
if not os.path.exists(path):
|
|
2330
|
+
self.skipTest('documentation not available')
|
|
2331
|
+
return path
|
|
2332
|
+
|
|
2333
|
+
def test_tutorial(self):
|
|
2334
|
+
path = self.doc_path('tutorial.rst')
|
|
2335
|
+
out = io.StringIO()
|
|
2336
|
+
with contextlib.redirect_stdout(out):
|
|
2337
|
+
failed, attempted = doctest.testfile(
|
|
2338
|
+
path, module_relative=False, optionflags=doctest.ELLIPSIS)
|
|
2339
|
+
self.assertGreater(attempted, 0)
|
|
2340
|
+
self.assertEqual(failed, 0, out.getvalue())
|
|
2341
|
+
|
|
2342
|
+
def shell_sessions(self, path):
|
|
2343
|
+
""" Yield (command, expected output) for each "$ " line of the
|
|
2344
|
+
shell examples in ``.. code-block:: bash`` blocks """
|
|
2345
|
+
with open(path, encoding='utf-8') as f:
|
|
2346
|
+
lines = f.read().splitlines()
|
|
2347
|
+
in_block = False
|
|
2348
|
+
command, output = None, []
|
|
2349
|
+
for line in lines + ['']:
|
|
2350
|
+
if line.startswith('.. code-block:: bash'):
|
|
2351
|
+
in_block = True
|
|
2352
|
+
continue
|
|
2353
|
+
if in_block and line and not line[0].isspace():
|
|
2354
|
+
in_block = False
|
|
2355
|
+
text = line.strip()
|
|
2356
|
+
if command is not None and (not in_block or not text or
|
|
2357
|
+
text.startswith(('$ ', '#'))):
|
|
2358
|
+
yield command, output
|
|
2359
|
+
command, output = None, []
|
|
2360
|
+
if not in_block:
|
|
2361
|
+
continue
|
|
2362
|
+
if text.startswith('$ '):
|
|
2363
|
+
command = text[2:]
|
|
2364
|
+
elif command is not None:
|
|
2365
|
+
# keep indentation relative to the code block
|
|
2366
|
+
output.append(line[4:])
|
|
2367
|
+
|
|
2368
|
+
def test_commandline(self):
|
|
2369
|
+
path = self.doc_path('commandline.rst')
|
|
2370
|
+
tmp = tempfile.TemporaryDirectory()
|
|
2371
|
+
self.addCleanup(tmp.cleanup)
|
|
2372
|
+
sessions = list(self.shell_sessions(path))
|
|
2373
|
+
self.assertGreater(len(sessions), 0)
|
|
2374
|
+
|
|
2375
|
+
for command, output in sessions:
|
|
2376
|
+
with self.subTest(command=command):
|
|
2377
|
+
args = shlex.split(command)
|
|
2378
|
+
expected = ''.join(line + '\n' for line in output)
|
|
2379
|
+
program, args = args[0], args[1:]
|
|
2380
|
+
|
|
2381
|
+
if program == 'cat':
|
|
2382
|
+
# "cat" introduces the input files of the examples
|
|
2383
|
+
filename = os.path.join(tmp.name, args[0])
|
|
2384
|
+
if not os.path.exists(filename):
|
|
2385
|
+
with open(filename, 'w', encoding='utf-8') as f:
|
|
2386
|
+
f.write(expected)
|
|
2387
|
+
with open(filename, encoding='utf-8') as f:
|
|
2388
|
+
self.assertEqual(f.read(), expected)
|
|
2389
|
+
continue
|
|
2390
|
+
|
|
2391
|
+
self.assertIn(program, ['jsondiff', 'jsonpatch'])
|
|
2392
|
+
redirect = None
|
|
2393
|
+
if '>' in args:
|
|
2394
|
+
redirect = args[args.index('>') + 1]
|
|
2395
|
+
args = args[:args.index('>')]
|
|
2396
|
+
|
|
2397
|
+
res = self.run_script(program, *args, cwd=tmp.name)
|
|
2398
|
+
self.assertEqual(res.stderr, "")
|
|
2399
|
+
|
|
2400
|
+
if redirect:
|
|
2401
|
+
with open(os.path.join(tmp.name, redirect), 'w',
|
|
2402
|
+
encoding='utf-8') as f:
|
|
2403
|
+
f.write(res.stdout)
|
|
2404
|
+
res.stdout = ''
|
|
2405
|
+
self.assertEqual(res.stdout, expected)
|
|
2406
|
+
|
|
2407
|
+
|
|
2180
2408
|
if __name__ == '__main__':
|
|
2181
2409
|
modules = ['jsonpatch']
|
|
2182
2410
|
|
|
@@ -2200,6 +2428,7 @@ if __name__ == '__main__':
|
|
|
2200
2428
|
suite.addTest(unittest.defaultTestLoader.loadTestsFromTestCase(CustomJsonPointerTests))
|
|
2201
2429
|
suite.addTest(unittest.defaultTestLoader.loadTestsFromTestCase(CustomOperationTests))
|
|
2202
2430
|
suite.addTest(unittest.defaultTestLoader.loadTestsFromTestCase(CommandLineTests))
|
|
2431
|
+
suite.addTest(unittest.defaultTestLoader.loadTestsFromTestCase(DocumentationTests))
|
|
2203
2432
|
return suite
|
|
2204
2433
|
|
|
2205
2434
|
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|