| 10 | 10 |
# are met:
|
| 11 | 11 |
#
|
| 12 | 12 |
# 1. Redistributions of source code must retain the above copyright
|
| 13 | |
# notice, this list of conditions and the following disclaimer.
|
|
13 |
# notice, this list of conditions and the following disclaimer.
|
| 14 | 14 |
# 2. Redistributions in binary form must reproduce the above copyright
|
| 15 | |
# notice, this list of conditions and the following disclaimer in the
|
| 16 | |
# documentation and/or other materials provided with the distribution.
|
|
15 |
# notice, this list of conditions and the following disclaimer in the
|
|
16 |
# documentation and/or other materials provided with the distribution.
|
| 17 | 17 |
# 3. The name of the author may not be used to endorse or promote products
|
| 18 | |
# derived from this software without specific prior written permission.
|
|
18 |
# derived from this software without specific prior written permission.
|
| 19 | 19 |
#
|
| 20 | 20 |
# THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
|
| 21 | 21 |
# IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
|
|
| 29 | 29 |
# THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
| 30 | 30 |
#
|
| 31 | 31 |
|
|
32 |
""" Identify specific nodes in a JSON document (RFC 6901) """
|
|
33 |
|
| 32 | 34 |
from __future__ import unicode_literals
|
| 33 | 35 |
|
| 34 | |
""" Identify specific nodes in a JSON document (RFC 6901) """
|
|
36 |
# Will be parsed by setup.py to determine package metadata
|
|
37 |
__author__ = 'Stefan Kögl <stefan@skoegl.net>'
|
|
38 |
__version__ = '2.0'
|
|
39 |
__website__ = 'https://github.com/stefankoegl/python-json-pointer'
|
|
40 |
__license__ = 'Modified BSD License'
|
|
41 |
|
|
42 |
|
|
43 |
try:
|
|
44 |
from itertools import izip
|
|
45 |
str = unicode
|
|
46 |
except ImportError: # Python 3
|
|
47 |
izip = zip
|
| 35 | 48 |
|
| 36 | 49 |
try:
|
| 37 | 50 |
from collections.abc import Mapping, Sequence
|
| 38 | |
except ImportError:
|
|
51 |
except ImportError: # Python 3
|
| 39 | 52 |
from collections import Mapping, Sequence
|
| 40 | |
|
| 41 | |
# Will be parsed by setup.py to determine package metadata
|
| 42 | |
__author__ = 'Stefan Kögl <stefan@skoegl.net>'
|
| 43 | |
__version__ = '1.10'
|
| 44 | |
__website__ = 'https://github.com/stefankoegl/python-json-pointer'
|
| 45 | |
__license__ = 'Modified BSD License'
|
| 46 | |
|
| 47 | |
|
| 48 | |
try:
|
| 49 | |
from urllib import unquote
|
| 50 | |
from itertools import izip
|
| 51 | |
str = unicode
|
| 52 | |
except ImportError: # Python 3
|
| 53 | |
from urllib.parse import unquote
|
| 54 | |
izip = zip
|
| 55 | 53 |
|
| 56 | 54 |
from itertools import tee
|
| 57 | 55 |
import re
|
| 58 | 56 |
import copy
|
| 59 | 57 |
|
| 60 | 58 |
|
| 61 | |
# array indices must not contain leading zeros, signs, spaces, decimals, etc
|
| 62 | |
RE_ARRAY_INDEX=re.compile('0|[1-9][0-9]*$')
|
|
59 |
_nothing = object()
|
|
60 |
|
|
61 |
|
|
62 |
def set_pointer(doc, pointer, value, inplace=True):
|
|
63 |
"""Resolves pointer against doc and sets the value of the target within doc.
|
|
64 |
|
|
65 |
With inplace set to true, doc is modified as long as pointer is not the
|
|
66 |
root.
|
|
67 |
|
|
68 |
>>> obj = {'foo': {'anArray': [ {'prop': 44}], 'another prop': {'baz': 'A string' }}}
|
|
69 |
|
|
70 |
>>> set_pointer(obj, '/foo/anArray/0/prop', 55) == \
|
|
71 |
{'foo': {'another prop': {'baz': 'A string'}, 'anArray': [{'prop': 55}]}}
|
|
72 |
True
|
|
73 |
|
|
74 |
>>> set_pointer(obj, '/foo/yet another prop', 'added prop') == \
|
|
75 |
{'foo': {'another prop': {'baz': 'A string'}, 'yet another prop': 'added prop', 'anArray': [{'prop': 55}]}}
|
|
76 |
True
|
|
77 |
|
|
78 |
>>> obj = {'foo': {}}
|
|
79 |
>>> set_pointer(obj, '/foo/a%20b', 'x') == \
|
|
80 |
{'foo': {'a%20b': 'x' }}
|
|
81 |
True
|
|
82 |
"""
|
|
83 |
|
|
84 |
pointer = JsonPointer(pointer)
|
|
85 |
return pointer.set(doc, value, inplace)
|
|
86 |
|
|
87 |
|
|
88 |
def resolve_pointer(doc, pointer, default=_nothing):
|
|
89 |
""" Resolves pointer against doc and returns the referenced object
|
|
90 |
|
|
91 |
>>> obj = {'foo': {'anArray': [ {'prop': 44}], 'another prop': {'baz': 'A string' }}, 'a%20b': 1, 'c d': 2}
|
|
92 |
|
|
93 |
>>> resolve_pointer(obj, '') == obj
|
|
94 |
True
|
|
95 |
|
|
96 |
>>> resolve_pointer(obj, '/foo') == obj['foo']
|
|
97 |
True
|
|
98 |
|
|
99 |
>>> resolve_pointer(obj, '/foo/another prop') == obj['foo']['another prop']
|
|
100 |
True
|
|
101 |
|
|
102 |
>>> resolve_pointer(obj, '/foo/another prop/baz') == obj['foo']['another prop']['baz']
|
|
103 |
True
|
|
104 |
|
|
105 |
>>> resolve_pointer(obj, '/foo/anArray/0') == obj['foo']['anArray'][0]
|
|
106 |
True
|
|
107 |
|
|
108 |
>>> resolve_pointer(obj, '/some/path', None) == None
|
|
109 |
True
|
|
110 |
|
|
111 |
>>> resolve_pointer(obj, '/a b', None) == None
|
|
112 |
True
|
|
113 |
|
|
114 |
>>> resolve_pointer(obj, '/a%20b') == 1
|
|
115 |
True
|
|
116 |
|
|
117 |
>>> resolve_pointer(obj, '/c d') == 2
|
|
118 |
True
|
|
119 |
|
|
120 |
>>> resolve_pointer(obj, '/c%20d', None) == None
|
|
121 |
True
|
|
122 |
"""
|
|
123 |
|
|
124 |
pointer = JsonPointer(pointer)
|
|
125 |
return pointer.resolve(doc, default)
|
|
126 |
|
|
127 |
|
|
128 |
def pairwise(iterable):
|
|
129 |
""" Transforms a list to a list of tuples of adjacent items
|
|
130 |
|
|
131 |
s -> (s0,s1), (s1,s2), (s2, s3), ...
|
|
132 |
|
|
133 |
>>> list(pairwise([]))
|
|
134 |
[]
|
|
135 |
|
|
136 |
>>> list(pairwise([1]))
|
|
137 |
[]
|
|
138 |
|
|
139 |
>>> list(pairwise([1, 2, 3, 4]))
|
|
140 |
[(1, 2), (2, 3), (3, 4)]
|
|
141 |
"""
|
|
142 |
a, b = tee(iterable)
|
|
143 |
for _ in b:
|
|
144 |
break
|
|
145 |
return izip(a, b)
|
| 63 | 146 |
|
| 64 | 147 |
|
| 65 | 148 |
class JsonPointerException(Exception):
|
|
| 67 | 150 |
|
| 68 | 151 |
|
| 69 | 152 |
class EndOfList(object):
|
| 70 | |
""" Result of accessing element "-" of a list """
|
|
153 |
"""Result of accessing element "-" of a list"""
|
| 71 | 154 |
|
| 72 | 155 |
def __init__(self, list_):
|
| 73 | 156 |
self.list_ = list_
|
| 74 | 157 |
|
| 75 | |
|
| 76 | 158 |
def __repr__(self):
|
| 77 | 159 |
return '{cls}({lst})'.format(cls=self.__class__.__name__,
|
| 78 | |
lst=repr(self.list_))
|
| 79 | |
|
| 80 | |
|
| 81 | |
_nothing = object()
|
| 82 | |
|
| 83 | |
|
| 84 | |
def resolve_pointer(doc, pointer, default=_nothing):
|
| 85 | |
"""
|
| 86 | |
Resolves pointer against doc and returns the referenced object
|
| 87 | |
|
| 88 | |
>>> obj = {"foo": {"anArray": [ {"prop": 44}], "another prop": {"baz": "A string" }}}
|
| 89 | |
|
| 90 | |
>>> resolve_pointer(obj, '') == obj
|
| 91 | |
True
|
| 92 | |
|
| 93 | |
>>> resolve_pointer(obj, '/foo') == obj['foo']
|
| 94 | |
True
|
| 95 | |
|
| 96 | |
>>> resolve_pointer(obj, '/foo/another%20prop') == obj['foo']['another prop']
|
| 97 | |
True
|
| 98 | |
|
| 99 | |
>>> resolve_pointer(obj, '/foo/another%20prop/baz') == obj['foo']['another prop']['baz']
|
| 100 | |
True
|
| 101 | |
|
| 102 | |
>>> resolve_pointer(obj, '/foo/anArray/0') == obj['foo']['anArray'][0]
|
| 103 | |
True
|
| 104 | |
|
| 105 | |
>>> resolve_pointer(obj, '/some/path', None) == None
|
| 106 | |
True
|
| 107 | |
|
| 108 | |
"""
|
| 109 | |
|
| 110 | |
pointer = JsonPointer(pointer)
|
| 111 | |
return pointer.resolve(doc, default)
|
| 112 | |
|
| 113 | |
def set_pointer(doc, pointer, value, inplace=True):
|
| 114 | |
"""
|
| 115 | |
Resolves pointer against doc and sets the value of the target within doc.
|
| 116 | |
|
| 117 | |
With inplace set to true, doc is modified as long as pointer is not the
|
| 118 | |
root.
|
| 119 | |
|
| 120 | |
>>> obj = {"foo": {"anArray": [ {"prop": 44}], "another prop": {"baz": "A string" }}}
|
| 121 | |
|
| 122 | |
>>> set_pointer(obj, '/foo/anArray/0/prop', 55) == \
|
| 123 | |
{'foo': {'another prop': {'baz': 'A string'}, 'anArray': [{'prop': 55}]}}
|
| 124 | |
True
|
| 125 | |
|
| 126 | |
>>> set_pointer(obj, '/foo/yet%20another%20prop', 'added prop') == \
|
| 127 | |
{'foo': {'another prop': {'baz': 'A string'}, 'yet another prop': 'added prop', 'anArray': [{'prop': 55}]}}
|
| 128 | |
True
|
| 129 | |
|
| 130 | |
"""
|
| 131 | |
|
| 132 | |
pointer = JsonPointer(pointer)
|
| 133 | |
return pointer.set(doc, value, inplace)
|
|
160 |
lst=repr(self.list_))
|
| 134 | 161 |
|
| 135 | 162 |
|
| 136 | 163 |
class JsonPointer(object):
|
| 137 | |
""" A JSON Pointer that can reference parts of an JSON document """
|
|
164 |
"""A JSON Pointer that can reference parts of an JSON document"""
|
|
165 |
|
|
166 |
# Array indices must not contain:
|
|
167 |
# leading zeros, signs, spaces, decimals, etc
|
|
168 |
_RE_ARRAY_INDEX = re.compile('0|[1-9][0-9]*$')
|
|
169 |
_RE_INVALID_ESCAPE = re.compile('(~[^01]|~$)')
|
| 138 | 170 |
|
| 139 | 171 |
def __init__(self, pointer):
|
|
172 |
|
|
173 |
# validate escapes
|
|
174 |
invalid_escape = self._RE_INVALID_ESCAPE.search(pointer)
|
|
175 |
if invalid_escape:
|
|
176 |
raise JsonPointerException('Found invalid escape {}'.format(
|
|
177 |
invalid_escape.group()))
|
|
178 |
|
| 140 | 179 |
parts = pointer.split('/')
|
| 141 | 180 |
if parts.pop(0) != '':
|
| 142 | 181 |
raise JsonPointerException('location must starts with /')
|
| 143 | 182 |
|
| 144 | |
parts = map(unquote, parts)
|
| 145 | |
parts = [part.replace('~1', '/') for part in parts]
|
| 146 | |
parts = [part.replace('~0', '~') for part in parts]
|
|
183 |
parts = [unescape(part) for part in parts]
|
| 147 | 184 |
self.parts = parts
|
| 148 | 185 |
|
| 149 | |
|
| 150 | 186 |
def to_last(self, doc):
|
| 151 | |
""" Resolves ptr until the last step, returns (sub-doc, last-step) """
|
|
187 |
"""Resolves ptr until the last step, returns (sub-doc, last-step)"""
|
| 152 | 188 |
|
| 153 | 189 |
if not self.parts:
|
| 154 | 190 |
return doc, None
|
|
| 157 | 193 |
doc = self.walk(doc, part)
|
| 158 | 194 |
|
| 159 | 195 |
return doc, self.get_part(doc, self.parts[-1])
|
| 160 | |
|
| 161 | 196 |
|
| 162 | 197 |
def resolve(self, doc, default=_nothing):
|
| 163 | 198 |
"""Resolves the pointer against doc and returns the referenced object"""
|
|
| 174 | 209 |
|
| 175 | 210 |
return doc
|
| 176 | 211 |
|
| 177 | |
|
| 178 | 212 |
get = resolve
|
| 179 | 213 |
|
| 180 | 214 |
def set(self, doc, value, inplace=True):
|
| 181 | |
""" Resolve the pointer against the doc and replace the target with value. """
|
|
215 |
"""Resolve the pointer against the doc and replace the target with value."""
|
| 182 | 216 |
|
| 183 | 217 |
if len(self.parts) == 0:
|
| 184 | 218 |
if inplace:
|
|
| 194 | 228 |
return doc
|
| 195 | 229 |
|
| 196 | 230 |
def get_part(self, doc, part):
|
| 197 | |
""" Returns the next step in the correct type """
|
|
231 |
"""Returns the next step in the correct type"""
|
| 198 | 232 |
|
| 199 | 233 |
if isinstance(doc, Mapping):
|
| 200 | 234 |
return part
|
|
| 204 | 238 |
if part == '-':
|
| 205 | 239 |
return part
|
| 206 | 240 |
|
| 207 | |
if not RE_ARRAY_INDEX.match(str(part)):
|
| 208 | |
raise JsonPointerException("'%s' is not a valid list index" % (part, ))
|
|
241 |
if not self._RE_ARRAY_INDEX.match(str(part)):
|
|
242 |
raise JsonPointerException("'%s' is not a valid sequence index" % part)
|
| 209 | 243 |
|
| 210 | 244 |
return int(part)
|
| 211 | 245 |
|
| 212 | 246 |
elif hasattr(doc, '__getitem__'):
|
| 213 | |
# Allow indexing via ducktyping if the target has defined __getitem__
|
|
247 |
# Allow indexing via ducktyping
|
|
248 |
# if the target has defined __getitem__
|
| 214 | 249 |
return part
|
| 215 | 250 |
|
| 216 | 251 |
else:
|
| 217 | 252 |
raise JsonPointerException("Document '%s' does not support indexing, "
|
| 218 | |
"must be dict/list or support __getitem__" % type(doc))
|
|
253 |
"must be mapping/sequence or support __getitem__" % type(doc))
|
| 219 | 254 |
|
| 220 | 255 |
|
| 221 | 256 |
def walk(self, doc, part):
|
|
| 223 | 258 |
|
| 224 | 259 |
part = self.get_part(doc, part)
|
| 225 | 260 |
|
| 226 | |
assert (type(doc) in (dict, list) or hasattr(doc, '__getitem__')), "invalid document type %s" % (type(doc),)
|
| 227 | |
|
| 228 | |
if isinstance(doc, Mapping):
|
|
261 |
assert hasattr(doc, '__getitem__'), "invalid document type %s" % (type(doc),)
|
|
262 |
|
|
263 |
if isinstance(doc, Sequence):
|
|
264 |
if part == '-':
|
|
265 |
return EndOfList(doc)
|
|
266 |
|
| 229 | 267 |
try:
|
| 230 | 268 |
return doc[part]
|
| 231 | 269 |
|
| 232 | |
except KeyError:
|
| 233 | |
raise JsonPointerException("member '%s' not found in %s" % (part, doc))
|
| 234 | |
|
| 235 | |
elif isinstance(doc, Sequence):
|
| 236 | |
|
| 237 | |
if part == '-':
|
| 238 | |
return EndOfList(doc)
|
| 239 | |
|
| 240 | |
try:
|
| 241 | |
return doc[part]
|
| 242 | |
|
| 243 | 270 |
except IndexError:
|
| 244 | 271 |
raise JsonPointerException("index '%s' is out of bounds" % (part, ))
|
| 245 | 272 |
|
| 246 | |
else:
|
| 247 | |
# Object supports __getitem__, assume custom indexing
|
|
273 |
# Else the object is a mapping or supports __getitem__(so assume custom indexing)
|
|
274 |
try:
|
| 248 | 275 |
return doc[part]
|
| 249 | 276 |
|
|
277 |
except KeyError:
|
|
278 |
raise JsonPointerException("member '%s' not found in %s" % (part, doc))
|
|
279 |
|
|
280 |
|
| 250 | 281 |
def contains(self, ptr):
|
| 251 | |
"""Returns True if self contains the given ptr"""
|
|
282 |
""" Returns True if self contains the given ptr """
|
| 252 | 283 |
return self.parts[:len(ptr.parts)] == ptr.parts
|
| 253 | 284 |
|
| 254 | 285 |
def __contains__(self, item):
|
| 255 | |
"""Returns True if self contains the given ptr"""
|
|
286 |
""" Returns True if self contains the given ptr """
|
| 256 | 287 |
return self.contains(item)
|
| 257 | 288 |
|
| 258 | 289 |
@property
|
| 259 | 290 |
def path(self):
|
| 260 | |
""" Returns the string representation of the pointer
|
|
291 |
"""Returns the string representation of the pointer
|
| 261 | 292 |
|
| 262 | 293 |
>>> ptr = JsonPointer('/~0/0/~1').path == '/~0/0/~1'
|
| 263 | 294 |
"""
|
| 264 | |
parts = [part.replace('~', '~0') for part in self.parts]
|
| 265 | |
parts = [part.replace('/', '~1') for part in parts]
|
|
295 |
parts = [escape(part) for part in self.parts]
|
| 266 | 296 |
return ''.join('/' + part for part in parts)
|
| 267 | 297 |
|
| 268 | 298 |
def __eq__(self, other):
|
| 269 | |
""" compares a pointer to another object
|
|
299 |
"""Compares a pointer to another object
|
| 270 | 300 |
|
| 271 | 301 |
Pointers can be compared by comparing their strings (or splitted
|
| 272 | 302 |
strings), because no two different parts can point to the same
|
| 273 | |
structure in an object (eg no different number representations) """
|
|
303 |
structure in an object (eg no different number representations)
|
|
304 |
"""
|
| 274 | 305 |
|
| 275 | 306 |
if not isinstance(other, JsonPointer):
|
| 276 | 307 |
return False
|
| 277 | 308 |
|
| 278 | 309 |
return self.parts == other.parts
|
| 279 | 310 |
|
| 280 | |
|
| 281 | 311 |
def __hash__(self):
|
| 282 | 312 |
return hash(tuple(self.parts))
|
| 283 | 313 |
|
| 284 | 314 |
@classmethod
|
| 285 | 315 |
def from_parts(cls, parts):
|
| 286 | |
""" Constructs a JsonPointer from a list of (unescaped) paths
|
|
316 |
"""Constructs a JsonPointer from a list of (unescaped) paths
|
| 287 | 317 |
|
| 288 | 318 |
>>> JsonPointer.from_parts(['a', '~', '/', 0]).path == '/a/~0/~1/0'
|
| 289 | 319 |
True
|
| 290 | 320 |
"""
|
| 291 | |
parts = [str(part) for part in parts]
|
| 292 | |
parts = [part.replace('~', '~0') for part in parts]
|
| 293 | |
parts = [part.replace('/', '~1') for part in parts]
|
|
321 |
parts = [escape(str(part)) for part in parts]
|
| 294 | 322 |
ptr = cls(''.join('/' + part for part in parts))
|
| 295 | 323 |
return ptr
|
| 296 | 324 |
|
| 297 | 325 |
|
| 298 | |
|
| 299 | |
def pairwise(iterable):
|
| 300 | |
""" s -> (s0,s1), (s1,s2), (s2, s3), ...
|
| 301 | |
|
| 302 | |
>>> list(pairwise([]))
|
| 303 | |
[]
|
| 304 | |
|
| 305 | |
>>> list(pairwise([1]))
|
| 306 | |
[]
|
| 307 | |
|
| 308 | |
>>> list(pairwise([1, 2, 3, 4]))
|
| 309 | |
[(1, 2), (2, 3), (3, 4)]
|
| 310 | |
"""
|
| 311 | |
a, b = tee(iterable)
|
| 312 | |
for _ in b:
|
| 313 | |
break
|
| 314 | |
return izip(a, b)
|
|
326 |
def escape(s):
|
|
327 |
return s.replace('~', '~0').replace('/', '~1')
|
|
328 |
|
|
329 |
def unescape(s):
|
|
330 |
return s.replace('~1', '/').replace('~0', '~')
|