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.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
93 {
94 "json": "obj"
95 }
96 $ echo '{ 1.2:3.4}' | python -msimplejson
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.8.1'
103 __all__ = [
104 'dump', 'dumps', 'load', 'loads',
105 'JSONDecoder', 'JSONEncoder',
106 ]
107
108 if __name__ == '__main__':
109 from simplejson.decoder import JSONDecoder
110 from simplejson.encoder import JSONEncoder
111 else:
112 from decoder import JSONDecoder
113 from encoder import JSONEncoder
114
115 _default_encoder = JSONEncoder(
116 skipkeys=False,
117 ensure_ascii=True,
118 check_circular=True,
119 allow_nan=True,
120 indent=None,
121 separators=None,
122 encoding='utf-8',
123 default=None,
124 )
125
126 -def dump(obj, fp, skipkeys=False, ensure_ascii=True, check_circular=True,
127 allow_nan=True, cls=None, indent=None, separators=None,
128 encoding='utf-8', default=None, **kw):
129 """
130 Serialize ``obj`` as a JSON formatted stream to ``fp`` (a
131 ``.write()``-supporting file-like object).
132
133 If ``skipkeys`` is ``True`` then ``dict`` keys that are not basic types
134 (``str``, ``unicode``, ``int``, ``long``, ``float``, ``bool``, ``None``)
135 will be skipped instead of raising a ``TypeError``.
136
137 If ``ensure_ascii`` is ``False``, then the some chunks written to ``fp``
138 may be ``unicode`` instances, subject to normal Python ``str`` to
139 ``unicode`` coercion rules. Unless ``fp.write()`` explicitly
140 understands ``unicode`` (as in ``codecs.getwriter()``) this is likely
141 to cause an error.
142
143 If ``check_circular`` is ``False``, then the circular reference check
144 for container types will be skipped and a circular reference will
145 result in an ``OverflowError`` (or worse).
146
147 If ``allow_nan`` is ``False``, then it will be a ``ValueError`` to
148 serialize out of range ``float`` values (``nan``, ``inf``, ``-inf``)
149 in strict compliance of the JSON specification, instead of using the
150 JavaScript equivalents (``NaN``, ``Infinity``, ``-Infinity``).
151
152 If ``indent`` is a non-negative integer, then JSON array elements and object
153 members will be pretty-printed with that indent level. An indent level
154 of 0 will only insert newlines. ``None`` is the most compact representation.
155
156 If ``separators`` is an ``(item_separator, dict_separator)`` tuple
157 then it will be used instead of the default ``(', ', ': ')`` separators.
158 ``(',', ':')`` is the most compact JSON representation.
159
160 ``encoding`` is the character encoding for str instances, default is UTF-8.
161
162 ``default(obj)`` is a function that should return a serializable version
163 of obj or raise TypeError. The default simply raises TypeError.
164
165 To use a custom ``JSONEncoder`` subclass (e.g. one that overrides the
166 ``.default()`` method to serialize additional types), specify it with
167 the ``cls`` kwarg.
168 """
169
170 if (skipkeys is False and ensure_ascii is True and
171 check_circular is True and allow_nan is True and
172 cls is None and indent is None and separators is None and
173 encoding == 'utf-8' and default is None and not kw):
174 iterable = _default_encoder.iterencode(obj)
175 else:
176 if cls is None:
177 cls = JSONEncoder
178 iterable = cls(skipkeys=skipkeys, ensure_ascii=ensure_ascii,
179 check_circular=check_circular, allow_nan=allow_nan, indent=indent,
180 separators=separators, encoding=encoding,
181 default=default, **kw).iterencode(obj)
182
183
184 for chunk in iterable:
185 fp.write(chunk)
186
187
188 -def dumps(obj, skipkeys=False, ensure_ascii=True, check_circular=True,
189 allow_nan=True, cls=None, indent=None, separators=None,
190 encoding='utf-8', default=None, **kw):
191 """
192 Serialize ``obj`` to a JSON formatted ``str``.
193
194 If ``skipkeys`` is ``True`` then ``dict`` keys that are not basic types
195 (``str``, ``unicode``, ``int``, ``long``, ``float``, ``bool``, ``None``)
196 will be skipped instead of raising a ``TypeError``.
197
198 If ``ensure_ascii`` is ``False``, then the return value will be a
199 ``unicode`` instance subject to normal Python ``str`` to ``unicode``
200 coercion rules instead of being escaped to an ASCII ``str``.
201
202 If ``check_circular`` is ``False``, then the circular reference check
203 for container types will be skipped and a circular reference will
204 result in an ``OverflowError`` (or worse).
205
206 If ``allow_nan`` is ``False``, then it will be a ``ValueError`` to
207 serialize out of range ``float`` values (``nan``, ``inf``, ``-inf``) in
208 strict compliance of the JSON specification, instead of using the
209 JavaScript equivalents (``NaN``, ``Infinity``, ``-Infinity``).
210
211 If ``indent`` is a non-negative integer, then JSON array elements and
212 object members will be pretty-printed with that indent level. An indent
213 level of 0 will only insert newlines. ``None`` is the most compact
214 representation.
215
216 If ``separators`` is an ``(item_separator, dict_separator)`` tuple
217 then it will be used instead of the default ``(', ', ': ')`` separators.
218 ``(',', ':')`` is the most compact JSON representation.
219
220 ``encoding`` is the character encoding for str instances, default is UTF-8.
221
222 ``default(obj)`` is a function that should return a serializable version
223 of obj or raise TypeError. The default simply raises TypeError.
224
225 To use a custom ``JSONEncoder`` subclass (e.g. one that overrides the
226 ``.default()`` method to serialize additional types), specify it with
227 the ``cls`` kwarg.
228 """
229
230 if (skipkeys is False and ensure_ascii is True and
231 check_circular is True and allow_nan is True and
232 cls is None and indent is None and separators is None and
233 encoding == 'utf-8' and default is None and not kw):
234 return _default_encoder.encode(obj)
235 if cls is None:
236 cls = JSONEncoder
237 return cls(
238 skipkeys=skipkeys, ensure_ascii=ensure_ascii,
239 check_circular=check_circular, allow_nan=allow_nan, indent=indent,
240 separators=separators, encoding=encoding, default=default,
241 **kw).encode(obj)
242
243 _default_decoder = JSONDecoder(encoding=None, object_hook=None)
244
245 -def load(fp, encoding=None, cls=None, object_hook=None, parse_float=None,
246 parse_int=None, parse_constant=None, **kw):
247 """
248 Deserialize ``fp`` (a ``.read()``-supporting file-like object containing
249 a JSON document) to a Python object.
250
251 If the contents of ``fp`` is encoded with an ASCII based encoding other
252 than utf-8 (e.g. latin-1), then an appropriate ``encoding`` name must
253 be specified. Encodings that are not ASCII based (such as UCS-2) are
254 not allowed, and should be wrapped with
255 ``codecs.getreader(fp)(encoding)``, or simply decoded to a ``unicode``
256 object and passed to ``loads()``
257
258 ``object_hook`` is an optional function that will be called with the
259 result of any object literal decode (a ``dict``). The return value of
260 ``object_hook`` will be used instead of the ``dict``. This feature
261 can be used to implement custom decoders (e.g. JSON-RPC class hinting).
262
263 To use a custom ``JSONDecoder`` subclass, specify it with the ``cls``
264 kwarg.
265 """
266 return loads(fp.read(),
267 encoding=encoding, cls=cls, object_hook=object_hook,
268 parse_float=parse_float, parse_int=parse_int,
269 parse_constant=parse_constant, **kw)
270
271 -def loads(s, encoding=None, cls=None, object_hook=None, parse_float=None,
272 parse_int=None, parse_constant=None, **kw):
273 """
274 Deserialize ``s`` (a ``str`` or ``unicode`` instance containing a JSON
275 document) to a Python object.
276
277 If ``s`` is a ``str`` instance and is encoded with an ASCII based encoding
278 other than utf-8 (e.g. latin-1) then an appropriate ``encoding`` name
279 must be specified. Encodings that are not ASCII based (such as UCS-2)
280 are not allowed and should be decoded to ``unicode`` first.
281
282 ``object_hook`` is an optional function that will be called with the
283 result of any object literal decode (a ``dict``). The return value of
284 ``object_hook`` will be used instead of the ``dict``. This feature
285 can be used to implement custom decoders (e.g. JSON-RPC class hinting).
286
287 ``parse_float``, if specified, will be called with the string
288 of every JSON float to be decoded. By default this is equivalent to
289 float(num_str). This can be used to use another datatype or parser
290 for JSON floats (e.g. decimal.Decimal).
291
292 ``parse_int``, if specified, will be called with the string
293 of every JSON int to be decoded. By default this is equivalent to
294 int(num_str). This can be used to use another datatype or parser
295 for JSON integers (e.g. float).
296
297 ``parse_constant``, if specified, will be called with one of the
298 following strings: -Infinity, Infinity, NaN, null, true, false.
299 This can be used to raise an exception if invalid JSON numbers
300 are encountered.
301
302 To use a custom ``JSONDecoder`` subclass, specify it with the ``cls``
303 kwarg.
304 """
305 if (cls is None and encoding is None and object_hook is None and
306 parse_int is None and parse_float is None and
307 parse_constant is None and not kw):
308 return _default_decoder.decode(s)
309 if cls is None:
310 cls = JSONDecoder
311 if object_hook is not None:
312 kw['object_hook'] = object_hook
313 if parse_float is not None:
314 kw['parse_float'] = parse_float
315 if parse_int is not None:
316 kw['parse_int'] = parse_int
317 if parse_constant is not None:
318 kw['parse_constant'] = parse_constant
319 return cls(encoding=encoding, **kw).decode(s)
320
321
322
323
324
326 """
327 demjson, python-cjson API compatibility hook. Use loads(s) instead.
328 """
329 import warnings
330 warnings.warn("simplejson.loads(s) should be used instead of decode(s)",
331 DeprecationWarning)
332 return loads(s)
333
335 """
336 demjson, python-cjson compatibility hook. Use dumps(s) instead.
337 """
338 import warnings
339 warnings.warn("simplejson.dumps(s) should be used instead of encode(s)",
340 DeprecationWarning)
341 return dumps(obj)
342
344 """
345 jsonlib, JsonUtils, python-json, json-py API compatibility hook.
346 Use loads(s) instead.
347 """
348 import warnings
349 warnings.warn("simplejson.loads(s) should be used instead of read(s)",
350 DeprecationWarning)
351 return loads(s)
352
354 """
355 jsonlib, JsonUtils, python-json, json-py API compatibility hook.
356 Use dumps(s) instead.
357 """
358 import warnings
359 warnings.warn("simplejson.dumps(s) should be used instead of write(s)",
360 DeprecationWarning)
361 return dumps(obj)
362
363
364
365
366
367
369 import sys
370 if len(sys.argv) == 1:
371 infile = sys.stdin
372 outfile = sys.stdout
373 elif len(sys.argv) == 2:
374 infile = open(sys.argv[1], 'rb')
375 outfile = sys.stdout
376 elif len(sys.argv) == 3:
377 infile = open(sys.argv[1], 'rb')
378 outfile = open(sys.argv[2], 'wb')
379 else:
380 raise SystemExit("%s [infile [outfile]]" % (sys.argv[0],))
381 try:
382 obj = load(infile)
383 except ValueError, e:
384 raise SystemExit(e)
385 dump(obj, outfile, sort_keys=True, indent=4)
386 outfile.write('\n')
387
388 if __name__ == '__main__':
389 main()
390