1 r"""
2 A simple, fast, extensible JSON encoder and decoder
3
4 JSON (JavaScript Object Notation) <http://json.org> is a subset of
5 JavaScript syntax (ECMA-262 3rd edition) used as a lightweight data
6 interchange format.
7
8 simplejson exposes an API familiar to uses of the standard library
9 marshal and pickle modules.
10
11 Encoding basic Python object hierarchies::
12
13 >>> import simplejson
14 >>> simplejson.dumps(['foo', {'bar': ('baz', None, 1.0, 2)}])
15 '["foo", {"bar": ["baz", null, 1.0, 2]}]'
16 >>> print simplejson.dumps("\"foo\bar")
17 "\"foo\bar"
18 >>> print simplejson.dumps(u'\u1234')
19 "\u1234"
20 >>> print simplejson.dumps('\\')
21 "\\"
22 >>> print simplejson.dumps({"c": 0, "b": 0, "a": 0}, sort_keys=True)
23 {"a": 0, "b": 0, "c": 0}
24 >>> from StringIO import StringIO
25 >>> io = StringIO()
26 >>> simplejson.dump(['streaming API'], io)
27 >>> io.getvalue()
28 '["streaming API"]'
29
30 Compact encoding::
31
32 >>> import simplejson
33 >>> simplejson.dumps([1,2,3,{'4': 5, '6': 7}], separators=(',',':'))
34 '[1,2,3,{"4":5,"6":7}]'
35
36 Pretty printing::
37
38 >>> import simplejson
39 >>> print simplejson.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 simplejson
48 >>> simplejson.loads('["foo", {"bar":["baz", null, 1.0, 2]}]')
49 [u'foo', {u'bar': [u'baz', None, 1.0, 2]}]
50 >>> simplejson.loads('"\\"foo\\bar"')
51 u'"foo\x08ar'
52 >>> from StringIO import StringIO
53 >>> io = StringIO('["streaming API"]')
54 >>> simplejson.load(io)
55 [u'streaming API']
56
57 Specializing JSON object decoding::
58
59 >>> import simplejson
60 >>> def as_complex(dct):
61 ... if '__complex__' in dct:
62 ... return complex(dct['real'], dct['imag'])
63 ... return dct
64 ...
65 >>> simplejson.loads('{"__complex__": true, "real": 1, "imag": 2}',
66 ... object_hook=as_complex)
67 (1+2j)
68 >>> import decimal
69 >>> simplejson.loads('1.1', parse_float=decimal.Decimal)
70 Decimal("1.1")
71
72 Extending JSONEncoder::
73
74 >>> import simplejson
75 >>> class ComplexEncoder(simplejson.JSONEncoder):
76 ... def default(self, obj):
77 ... if isinstance(obj, complex):
78 ... return [obj.real, obj.imag]
79 ... return simplejson.JSONEncoder.default(self, obj)
80 ...
81 >>> dumps(2 + 1j, cls=ComplexEncoder)
82 '[2.0, 1.0]'
83 >>> ComplexEncoder().encode(2 + 1j)
84 '[2.0, 1.0]'
85 >>> list(ComplexEncoder().iterencode(2 + 1j))
86 ['[', '2.0', ', ', '1.0', ']']
87
88
89 Using simplejson from the shell to validate and
90 pretty-print::
91
92 $ echo '{"json":"obj"}' | python -msimplejson.tool
93 {
94 "json": "obj"
95 }
96 $ echo '{ 1.2:3.4}' | python -msimplejson.tool
97 Expecting property name: line 1 column 2 (char 2)
98
99 Note that the JSON produced by this module's default settings
100 is a subset of YAML, so it may be used as a serializer for that as well.
101 """
102 __version__ = '1.9.2'
103 __all__ = [
104 'dump', 'dumps', 'load', 'loads',
105 'JSONDecoder', 'JSONEncoder',
106 ]
107
108 if __name__ == '__main__':
109 import warnings
110 warnings.warn('python -msimplejson is deprecated, use python -msiplejson.tool', DeprecationWarning)
111 from django.utils.simplejson.decoder import JSONDecoder
112 from django.utils.simplejson.encoder import JSONEncoder
113 else:
114 from decoder import JSONDecoder
115 from encoder import JSONEncoder
116
117 _default_encoder = JSONEncoder(
118 skipkeys=False,
119 ensure_ascii=True,
120 check_circular=True,
121 allow_nan=True,
122 indent=None,
123 separators=None,
124 encoding='utf-8',
125 default=None,
126 )
127
128 -def dump(obj, fp, skipkeys=False, ensure_ascii=True, check_circular=True,
129 allow_nan=True, cls=None, indent=None, separators=None,
130 encoding='utf-8', default=None, **kw):
131 """
132 Serialize ``obj`` as a JSON formatted stream to ``fp`` (a
133 ``.write()``-supporting file-like object).
134
135 If ``skipkeys`` is ``True`` then ``dict`` keys that are not basic types
136 (``str``, ``unicode``, ``int``, ``long``, ``float``, ``bool``, ``None``)
137 will be skipped instead of raising a ``TypeError``.
138
139 If ``ensure_ascii`` is ``False``, then the some chunks written to ``fp``
140 may be ``unicode`` instances, subject to normal Python ``str`` to
141 ``unicode`` coercion rules. Unless ``fp.write()`` explicitly
142 understands ``unicode`` (as in ``codecs.getwriter()``) this is likely
143 to cause an error.
144
145 If ``check_circular`` is ``False``, then the circular reference check
146 for container types will be skipped and a circular reference will
147 result in an ``OverflowError`` (or worse).
148
149 If ``allow_nan`` is ``False``, then it will be a ``ValueError`` to
150 serialize out of range ``float`` values (``nan``, ``inf``, ``-inf``)
151 in strict compliance of the JSON specification, instead of using the
152 JavaScript equivalents (``NaN``, ``Infinity``, ``-Infinity``).
153
154 If ``indent`` is a non-negative integer, then JSON array elements and object
155 members will be pretty-printed with that indent level. An indent level
156 of 0 will only insert newlines. ``None`` is the most compact representation.
157
158 If ``separators`` is an ``(item_separator, dict_separator)`` tuple
159 then it will be used instead of the default ``(', ', ': ')`` separators.
160 ``(',', ':')`` is the most compact JSON representation.
161
162 ``encoding`` is the character encoding for str instances, default is UTF-8.
163
164 ``default(obj)`` is a function that should return a serializable version
165 of obj or raise TypeError. The default simply raises TypeError.
166
167 To use a custom ``JSONEncoder`` subclass (e.g. one that overrides the
168 ``.default()`` method to serialize additional types), specify it with
169 the ``cls`` kwarg.
170 """
171
172 if (skipkeys is False and ensure_ascii is True and
173 check_circular is True and allow_nan is True and
174 cls is None and indent is None and separators is None and
175 encoding == 'utf-8' and default is None and not kw):
176 iterable = _default_encoder.iterencode(obj)
177 else:
178 if cls is None:
179 cls = JSONEncoder
180 iterable = cls(skipkeys=skipkeys, ensure_ascii=ensure_ascii,
181 check_circular=check_circular, allow_nan=allow_nan, indent=indent,
182 separators=separators, encoding=encoding,
183 default=default, **kw).iterencode(obj)
184
185
186 for chunk in iterable:
187 fp.write(chunk)
188
189
190 -def dumps(obj, skipkeys=False, ensure_ascii=True, check_circular=True,
191 allow_nan=True, cls=None, indent=None, separators=None,
192 encoding='utf-8', default=None, **kw):
193 """
194 Serialize ``obj`` to a JSON formatted ``str``.
195
196 If ``skipkeys`` is ``True`` then ``dict`` keys that are not basic types
197 (``str``, ``unicode``, ``int``, ``long``, ``float``, ``bool``, ``None``)
198 will be skipped instead of raising a ``TypeError``.
199
200 If ``ensure_ascii`` is ``False``, then the return value will be a
201 ``unicode`` instance subject to normal Python ``str`` to ``unicode``
202 coercion rules instead of being escaped to an ASCII ``str``.
203
204 If ``check_circular`` is ``False``, then the circular reference check
205 for container types will be skipped and a circular reference will
206 result in an ``OverflowError`` (or worse).
207
208 If ``allow_nan`` is ``False``, then it will be a ``ValueError`` to
209 serialize out of range ``float`` values (``nan``, ``inf``, ``-inf``) in
210 strict compliance of the JSON specification, instead of using the
211 JavaScript equivalents (``NaN``, ``Infinity``, ``-Infinity``).
212
213 If ``indent`` is a non-negative integer, then JSON array elements and
214 object members will be pretty-printed with that indent level. An indent
215 level of 0 will only insert newlines. ``None`` is the most compact
216 representation.
217
218 If ``separators`` is an ``(item_separator, dict_separator)`` tuple
219 then it will be used instead of the default ``(', ', ': ')`` separators.
220 ``(',', ':')`` is the most compact JSON representation.
221
222 ``encoding`` is the character encoding for str instances, default is UTF-8.
223
224 ``default(obj)`` is a function that should return a serializable version
225 of obj or raise TypeError. The default simply raises TypeError.
226
227 To use a custom ``JSONEncoder`` subclass (e.g. one that overrides the
228 ``.default()`` method to serialize additional types), specify it with
229 the ``cls`` kwarg.
230 """
231
232 if (skipkeys is False and ensure_ascii is True and
233 check_circular is True and allow_nan is True and
234 cls is None and indent is None and separators is None and
235 encoding == 'utf-8' and default is None and not kw):
236 return _default_encoder.encode(obj)
237 if cls is None:
238 cls = JSONEncoder
239 return cls(
240 skipkeys=skipkeys, ensure_ascii=ensure_ascii,
241 check_circular=check_circular, allow_nan=allow_nan, indent=indent,
242 separators=separators, encoding=encoding, default=default,
243 **kw).encode(obj)
244
245
246 _default_decoder = JSONDecoder(encoding=None, object_hook=None)
247
248
249 -def load(fp, encoding=None, cls=None, object_hook=None, parse_float=None,
250 parse_int=None, parse_constant=None, **kw):
251 """
252 Deserialize ``fp`` (a ``.read()``-supporting file-like object containing
253 a JSON document) to a Python object.
254
255 If the contents of ``fp`` is encoded with an ASCII based encoding other
256 than utf-8 (e.g. latin-1), then an appropriate ``encoding`` name must
257 be specified. Encodings that are not ASCII based (such as UCS-2) are
258 not allowed, and should be wrapped with
259 ``codecs.getreader(fp)(encoding)``, or simply decoded to a ``unicode``
260 object and passed to ``loads()``
261
262 ``object_hook`` is an optional function that will be called with the
263 result of any object literal decode (a ``dict``). The return value of
264 ``object_hook`` will be used instead of the ``dict``. This feature
265 can be used to implement custom decoders (e.g. JSON-RPC class hinting).
266
267 To use a custom ``JSONDecoder`` subclass, specify it with the ``cls``
268 kwarg.
269 """
270 return loads(fp.read(),
271 encoding=encoding, cls=cls, object_hook=object_hook,
272 parse_float=parse_float, parse_int=parse_int,
273 parse_constant=parse_constant, **kw)
274
275
276 -def loads(s, encoding=None, cls=None, object_hook=None, parse_float=None,
277 parse_int=None, parse_constant=None, **kw):
278 """
279 Deserialize ``s`` (a ``str`` or ``unicode`` instance containing a JSON
280 document) to a Python object.
281
282 If ``s`` is a ``str`` instance and is encoded with an ASCII based encoding
283 other than utf-8 (e.g. latin-1) then an appropriate ``encoding`` name
284 must be specified. Encodings that are not ASCII based (such as UCS-2)
285 are not allowed and should be decoded to ``unicode`` first.
286
287 ``object_hook`` is an optional function that will be called with the
288 result of any object literal decode (a ``dict``). The return value of
289 ``object_hook`` will be used instead of the ``dict``. This feature
290 can be used to implement custom decoders (e.g. JSON-RPC class hinting).
291
292 ``parse_float``, if specified, will be called with the string
293 of every JSON float to be decoded. By default this is equivalent to
294 float(num_str). This can be used to use another datatype or parser
295 for JSON floats (e.g. decimal.Decimal).
296
297 ``parse_int``, if specified, will be called with the string
298 of every JSON int to be decoded. By default this is equivalent to
299 int(num_str). This can be used to use another datatype or parser
300 for JSON integers (e.g. float).
301
302 ``parse_constant``, if specified, will be called with one of the
303 following strings: -Infinity, Infinity, NaN, null, true, false.
304 This can be used to raise an exception if invalid JSON numbers
305 are encountered.
306
307 To use a custom ``JSONDecoder`` subclass, specify it with the ``cls``
308 kwarg.
309 """
310 if (cls is None and encoding is None and object_hook is None and
311 parse_int is None and parse_float is None and
312 parse_constant is None and not kw):
313 return _default_decoder.decode(s)
314 if cls is None:
315 cls = JSONDecoder
316 if object_hook is not None:
317 kw['object_hook'] = object_hook
318 if parse_float is not None:
319 kw['parse_float'] = parse_float
320 if parse_int is not None:
321 kw['parse_int'] = parse_int
322 if parse_constant is not None:
323 kw['parse_constant'] = parse_constant
324 return cls(encoding=encoding, **kw).decode(s)
325
326
327
328
329
330
331
333 """
334 demjson, python-cjson API compatibility hook. Use loads(s) instead.
335 """
336 import warnings
337 warnings.warn("simplejson.loads(s) should be used instead of decode(s)",
338 DeprecationWarning)
339 return loads(s)
340
341
343 """
344 demjson, python-cjson compatibility hook. Use dumps(s) instead.
345 """
346 import warnings
347 warnings.warn("simplejson.dumps(s) should be used instead of encode(s)",
348 DeprecationWarning)
349 return dumps(obj)
350
351
353 """
354 jsonlib, JsonUtils, python-json, json-py API compatibility hook.
355 Use loads(s) instead.
356 """
357 import warnings
358 warnings.warn("simplejson.loads(s) should be used instead of read(s)",
359 DeprecationWarning)
360 return loads(s)
361
362
364 """
365 jsonlib, JsonUtils, python-json, json-py API compatibility hook.
366 Use dumps(s) instead.
367 """
368 import warnings
369 warnings.warn("simplejson.dumps(s) should be used instead of write(s)",
370 DeprecationWarning)
371 return dumps(obj)
372
373
374 if __name__ == '__main__':
375 import simplejson.tool
376 simplejson.tool.main()
377