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