1 r"""JSON (JavaScript Object Notation) <http://json.org> is a subset of 2 JavaScript syntax (ECMA-262 3rd edition) used as a lightweight data 3 interchange format. 4 5 :mod:`json` exposes an API familiar to users of the standard library 6 :mod:`marshal` and :mod:`pickle` modules. It is derived from a 7 version of the externally maintained simplejson library. 8 9 Encoding basic Python object hierarchies:: 10 11 >>> import json 12 >>> json.dumps(['foo', {'bar': ('baz', None, 1.0, 2)}]) 13 '["foo", {"bar": ["baz", null, 1.0, 2]}]' 14 >>> print(json.dumps(""fooar")) 15 ""fooar" 16 >>> print(json.dumps('u1234')) 17 "u1234" 18 >>> print(json.dumps('\')) 19 "\" 20 >>> print(json.dumps({"c": 0, "b": 0, "a": 0}, sort_keys=True)) 21 {"a": 0, "b": 0, "c": 0} 22 >>> from io import StringIO 23 >>> io = StringIO() 24 >>> json.dump(['streaming API'], io) 25 >>> io.getvalue() 26 '["streaming API"]' 27 28 Compact encoding:: 29 30 >>> import json 31 >>> from collections import OrderedDict 32 >>> mydict = OrderedDict([('4', 5), ('6', 7)]) 33 >>> json.dumps([1,2,3,mydict], separators=(',', ':')) 34 '[1,2,3,{"4":5,"6":7}]' 35 36 Pretty printing:: 37 38 >>> import json 39 >>> print(json.dumps({'4': 5, '6': 7}, sort_keys=True, indent=4)) 40 { 41 "4": 5, 42 "6": 7 43 } 44 45 Decoding JSON:: 46 47 >>> import json 48 >>> obj = ['foo', {'bar': ['baz', None, 1.0, 2]}] 49 >>> json.loads('["foo", {"bar":["baz", null, 1.0, 2]}]') == obj 50 True 51 >>> json.loads('"\"foo\bar"') == '"foox08ar' 52 True 53 >>> from io import StringIO 54 >>> io = StringIO('["streaming API"]') 55 >>> json.load(io)[0] == 'streaming API' 56 True 57 58 Specializing JSON object decoding:: 59 60 >>> import json 61 >>> def as_complex(dct): 62 ... if '__complex__' in dct: 63 ... return complex(dct['real'], dct['imag']) 64 ... return dct 65 ... 66 >>> json.loads('{"__complex__": true, "real": 1, "imag": 2}', 67 ... object_hook=as_complex) 68 (1+2j) 69 >>> from decimal import Decimal 70 >>> json.loads('1.1', parse_float=Decimal) == Decimal('1.1') 71 True 72 73 Specializing JSON object encoding:: 74 75 >>> import json 76 >>> def encode_complex(obj): 77 ... if isinstance(obj, complex): 78 ... return [obj.real, obj.imag] 79 ... raise TypeError(repr(obj) + " is not JSON serializable") 80 ... 81 >>> json.dumps(2 + 1j, default=encode_complex) 82 '[2.0, 1.0]' 83 >>> json.JSONEncoder(default=encode_complex).encode(2 + 1j) 84 '[2.0, 1.0]' 85 >>> ''.join(json.JSONEncoder(default=encode_complex).iterencode(2 + 1j)) 86 '[2.0, 1.0]' 87 88 89 Using json.tool from the shell to validate and pretty-print:: 90 91 $ echo '{"json":"obj"}' | python -m json.tool 92 { 93 "json": "obj" 94 } 95 $ echo '{ 1.2:3.4}' | python -m json.tool 96 Expecting property name enclosed in double quotes: line 1 column 3 (char 2) 97 """ 98 __version__ = '2.0.9' 99 __all__ = [ 100 'dump', 'dumps', 'load', 'loads', 101 'JSONDecoder', 'JSONDecodeError', 'JSONEncoder', 102 ] 103 104 __author__ = 'Bob Ippolito <bob@redivi.com>' 105 106 from .decoder import JSONDecoder, JSONDecodeError 107 from .encoder import JSONEncoder 108 import codecs 109 110 _default_encoder = JSONEncoder( 111 skipkeys=False, 112 ensure_ascii=True, 113 check_circular=True, 114 allow_nan=True, 115 indent=None, 116 separators=None, 117 default=None, 118 ) 119 120 def dump(obj, fp, *, skipkeys=False, ensure_ascii=True, check_circular=True, 121 allow_nan=True, cls=None, indent=None, separators=None, 122 default=None, sort_keys=False, **kw): 123 """Serialize ``obj`` as a JSON formatted stream to ``fp`` (a 124 ``.write()``-supporting file-like object). 125 126 If ``skipkeys`` is true then ``dict`` keys that are not basic types 127 (``str``, ``int``, ``float``, ``bool``, ``None``) will be skipped 128 instead of raising a ``TypeError``. 129 130 If ``ensure_ascii`` is false, then the strings written to ``fp`` can 131 contain non-ASCII characters if they appear in strings contained in 132 ``obj``. Otherwise, all such characters are escaped in JSON strings. 133 134 If ``check_circular`` is false, then the circular reference check 135 for container types will be skipped and a circular reference will 136 result in an ``OverflowError`` (or worse). 137 138 If ``allow_nan`` is false, then it will be a ``ValueError`` to 139 serialize out of range ``float`` values (``nan``, ``inf``, ``-inf``) 140 in strict compliance of the JSON specification, instead of using the 141 JavaScript equivalents (``NaN``, ``Infinity``, ``-Infinity``). 142 143 If ``indent`` is a non-negative integer, then JSON array elements and 144 object members will be pretty-printed with that indent level. An indent 145 level of 0 will only insert newlines. ``None`` is the most compact 146 representation. 147 148 If specified, ``separators`` should be an ``(item_separator, key_separator)`` 149 tuple. The default is ``(', ', ': ')`` if *indent* is ``None`` and 150 ``(',', ': ')`` otherwise. To get the most compact JSON representation, 151 you should specify ``(',', ':')`` to eliminate whitespace. 152 153 ``default(obj)`` is a function that should return a serializable version 154 of obj or raise TypeError. The default simply raises TypeError. 155 156 If *sort_keys* is true (default: ``False``), then the output of 157 dictionaries will be sorted by key. 158 159 To use a custom ``JSONEncoder`` subclass (e.g. one that overrides the 160 ``.default()`` method to serialize additional types), specify it with 161 the ``cls`` kwarg; otherwise ``JSONEncoder`` is used. 162 163 """ 164 # cached encoder 165 if (not skipkeys and ensure_ascii and 166 check_circular and allow_nan and 167 cls is None and indent is None and separators is None and 168 default is None and not sort_keys and not kw): 169 iterable = _default_encoder.iterencode(obj) 170 else: 171 if cls is None: 172 cls = JSONEncoder 173 iterable = cls(skipkeys=skipkeys, ensure_ascii=ensure_ascii, 174 check_circular=check_circular, allow_nan=allow_nan, indent=indent, 175 separators=separators, 176 default=default, sort_keys=sort_keys, **kw).iterencode(obj) 177 # could accelerate with writelines in some versions of Python, at 178 # a debuggability cost 179 for chunk in iterable: 180 fp.write(chunk) 181 182 183 def dumps(obj, *, skipkeys=False, ensure_ascii=True, check_circular=True, 184 allow_nan=True, cls=None, indent=None, separators=None, 185 default=None, sort_keys=False, **kw): 186 """Serialize ``obj`` to a JSON formatted ``str``. 187 188 If ``skipkeys`` is true then ``dict`` keys that are not basic types 189 (``str``, ``int``, ``float``, ``bool``, ``None``) will be skipped 190 instead of raising a ``TypeError``. 191 192 If ``ensure_ascii`` is false, then the return value can contain non-ASCII 193 characters if they appear in strings contained in ``obj``. Otherwise, all 194 such characters are escaped in JSON strings. 195 196 If ``check_circular`` is false, then the circular reference check 197 for container types will be skipped and a circular reference will 198 result in an ``OverflowError`` (or worse). 199 200 If ``allow_nan`` is false, then it will be a ``ValueError`` to 201 serialize out of range ``float`` values (``nan``, ``inf``, ``-inf``) in 202 strict compliance of the JSON specification, instead of using the 203 JavaScript equivalents (``NaN``, ``Infinity``, ``-Infinity``). 204 205 If ``indent`` is a non-negative integer, then JSON array elements and 206 object members will be pretty-printed with that indent level. An indent 207 level of 0 will only insert newlines. ``None`` is the most compact 208 representation. 209 210 If specified, ``separators`` should be an ``(item_separator, key_separator)`` 211 tuple. The default is ``(', ', ': ')`` if *indent* is ``None`` and 212 ``(',', ': ')`` otherwise. To get the most compact JSON representation, 213 you should specify ``(',', ':')`` to eliminate whitespace. 214 215 ``default(obj)`` is a function that should return a serializable version 216 of obj or raise TypeError. The default simply raises TypeError. 217 218 If *sort_keys* is true (default: ``False``), then the output of 219 dictionaries will be sorted by key. 220 221 To use a custom ``JSONEncoder`` subclass (e.g. one that overrides the 222 ``.default()`` method to serialize additional types), specify it with 223 the ``cls`` kwarg; otherwise ``JSONEncoder`` is used. 224 225 """ 226 # cached encoder 227 if (not skipkeys and ensure_ascii and 228 check_circular and allow_nan and 229 cls is None and indent is None and separators is None and 230 default is None and not sort_keys and not kw): 231 return _default_encoder.encode(obj) 232 if cls is None: 233 cls = JSONEncoder 234 return cls( 235 skipkeys=skipkeys, ensure_ascii=ensure_ascii, 236 check_circular=check_circular, allow_nan=allow_nan, indent=indent, 237 separators=separators, default=default, sort_keys=sort_keys, 238 **kw).encode(obj) 239 240 241 _default_decoder = JSONDecoder(object_hook=None, object_pairs_hook=None) 242 243 244 def detect_encoding(b): 245 bstartswith = b.startswith 246 if bstartswith((codecs.BOM_UTF32_BE, codecs.BOM_UTF32_LE)): 247 return 'utf-32' 248 if bstartswith((codecs.BOM_UTF16_BE, codecs.BOM_UTF16_LE)): 249 return 'utf-16' 250 if bstartswith(codecs.BOM_UTF8): 251 return 'utf-8-sig' 252 253 if len(b) >= 4: 254 if not b[0]: 255 # 00 00 -- -- - utf-32-be 256 # 00 XX -- -- - utf-16-be 257 return 'utf-16-be' if b[1] else 'utf-32-be' 258 if not b[1]: 259 # XX 00 00 00 - utf-32-le 260 # XX 00 00 XX - utf-16-le 261 # XX 00 XX -- - utf-16-le 262 return 'utf-16-le' if b[2] or b[3] else 'utf-32-le' 263 elif len(b) == 2: 264 if not b[0]: 265 # 00 XX - utf-16-be 266 return 'utf-16-be' 267 if not b[1]: 268 # XX 00 - utf-16-le 269 return 'utf-16-le' 270 # default 271 return 'utf-8' 272 273 274 def load(fp, *, cls=None, object_hook=None, parse_float=None, 275 parse_int=None, parse_constant=None, object_pairs_hook=None, **kw): 276 """Deserialize ``fp`` (a ``.read()``-supporting file-like object containing 277 a JSON document) to a Python object. 278 279 ``object_hook`` is an optional function that will be called with the 280 result of any object literal decode (a ``dict``). The return value of 281 ``object_hook`` will be used instead of the ``dict``. This feature 282 can be used to implement custom decoders (e.g. JSON-RPC class hinting). 283 284 ``object_pairs_hook`` is an optional function that will be called with the 285 result of any object literal decoded with an ordered list of pairs. The 286 return value of ``object_pairs_hook`` will be used instead of the ``dict``. 287 This feature can be used to implement custom decoders that rely on the 288 order that the key and value pairs are decoded (for example, 289 collections.OrderedDict will remember the order of insertion). If 290 ``object_hook`` is also defined, the ``object_pairs_hook`` takes priority. 291 292 To use a custom ``JSONDecoder`` subclass, specify it with the ``cls`` 293 kwarg; otherwise ``JSONDecoder`` is used. 294 295 """ 296 return loads(fp.read(), 297 cls=cls, object_hook=object_hook, 298 parse_float=parse_float, parse_int=parse_int, 299 parse_constant=parse_constant, object_pairs_hook=object_pairs_hook, **kw) 300 301 302 def loads(s, *, encoding=None, cls=None, object_hook=None, parse_float=None, 303 parse_int=None, parse_constant=None, object_pairs_hook=None, **kw): 304 """Deserialize ``s`` (a ``str``, ``bytes`` or ``bytearray`` instance 305 containing a JSON document) to a Python object. 306 307 ``object_hook`` is an optional function that will be called with the 308 result of any object literal decode (a ``dict``). The return value of 309 ``object_hook`` will be used instead of the ``dict``. This feature 310 can be used to implement custom decoders (e.g. JSON-RPC class hinting). 311 312 ``object_pairs_hook`` is an optional function that will be called with the 313 result of any object literal decoded with an ordered list of pairs. The 314 return value of ``object_pairs_hook`` will be used instead of the ``dict``. 315 This feature can be used to implement custom decoders that rely on the 316 order that the key and value pairs are decoded (for example, 317 collections.OrderedDict will remember the order of insertion). If 318 ``object_hook`` is also defined, the ``object_pairs_hook`` takes priority. 319 320 ``parse_float``, if specified, will be called with the string 321 of every JSON float to be decoded. By default this is equivalent to 322 float(num_str). This can be used to use another datatype or parser 323 for JSON floats (e.g. decimal.Decimal). 324 325 ``parse_int``, if specified, will be called with the string 326 of every JSON int to be decoded. By default this is equivalent to 327 int(num_str). This can be used to use another datatype or parser 328 for JSON integers (e.g. float). 329 330 ``parse_constant``, if specified, will be called with one of the 331 following strings: -Infinity, Infinity, NaN. 332 This can be used to raise an exception if invalid JSON numbers 333 are encountered. 334 335 To use a custom ``JSONDecoder`` subclass, specify it with the ``cls`` 336 kwarg; otherwise ``JSONDecoder`` is used. 337 338 The ``encoding`` argument is ignored and deprecated. 339 340 """ 341 if isinstance(s, str): 342 if s.startswith('ufeff'): 343 raise JSONDecodeError("Unexpected UTF-8 BOM (decode using utf-8-sig)", 344 s, 0) 345 else: 346 if not isinstance(s, (bytes, bytearray)): 347 raise TypeError('the JSON object must be str, bytes or bytearray, ' 348 'not {!r}'.format(s.__class__.__name__)) 349 s = s.decode(detect_encoding(s), 'surrogatepass') 350 351 if (cls is None and object_hook is None and 352 parse_int is None and parse_float is None and 353 parse_constant is None and object_pairs_hook is None and not kw): 354 return _default_decoder.decode(s) 355 if cls is None: 356 cls = JSONDecoder 357 if object_hook is not None: 358 kw['object_hook'] = object_hook 359 if object_pairs_hook is not None: 360 kw['object_pairs_hook'] = object_pairs_hook 361 if parse_float is not None: 362 kw['parse_float'] = parse_float 363 if parse_int is not None: 364 kw['parse_int'] = parse_int 365 if parse_constant is not None: 366 kw['parse_constant'] = parse_constant 367 return cls(**kw).decode(s)