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