2
A simple, fast, extensible JSON encoder and decoder
4
JSON (JavaScript Object Notation) <http://json.org> is a subset of
1
r"""JSON (JavaScript Object Notation) <http://json.org> is a subset of
5
2
JavaScript syntax (ECMA-262 3rd edition) used as a lightweight data
8
simplejson exposes an API familiar to uses of the standard library
9
marshal and pickle modules.
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::
14
>>> simplejson.dumps(['foo', {'bar': ('baz', None, 1.0, 2)}])
14
>>> import simplejson as json
15
>>> json.dumps(['foo', {'bar': ('baz', None, 1.0, 2)}])
15
16
'["foo", {"bar": ["baz", null, 1.0, 2]}]'
16
>>> print simplejson.dumps("\"foo\bar")
17
>>> print json.dumps("\"foo\bar")
18
>>> print simplejson.dumps(u'\u1234')
19
>>> print json.dumps(u'\u1234')
20
>>> print simplejson.dumps('\\')
21
>>> print json.dumps('\\')
22
>>> print simplejson.dumps({"c": 0, "b": 0, "a": 0}, sort_keys=True)
23
>>> print json.dumps({"c": 0, "b": 0, "a": 0}, sort_keys=True)
23
24
{"a": 0, "b": 0, "c": 0}
24
25
>>> from StringIO import StringIO
25
26
>>> io = StringIO()
26
>>> simplejson.dump(['streaming API'], io)
27
>>> json.dump(['streaming API'], io)
28
29
'["streaming API"]'
33
>>> simplejson.dumps([1,2,3,{'4': 5, '6': 7}], separators=(',',':'))
33
>>> import simplejson as json
34
>>> json.dumps([1,2,3,{'4': 5, '6': 7}], separators=(',',':'))
34
35
'[1,2,3,{"4":5,"6":7}]'
39
>>> print simplejson.dumps({'4': 5, '6': 7}, sort_keys=True, indent=4)
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()])
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"')
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
53
>>> json.loads('"\\"foo\\bar"') == u'"foo\x08ar'
52
55
>>> from StringIO import StringIO
53
56
>>> io = StringIO('["streaming API"]')
54
>>> simplejson.load(io)
57
>>> json.load(io)[0] == 'streaming API'
57
60
Specializing JSON object decoding::
62
>>> import simplejson as json
60
63
>>> def as_complex(dct):
61
64
... if '__complex__' in dct:
62
65
... return complex(dct['real'], dct['imag'])
65
>>> simplejson.loads('{"__complex__": true, "real": 1, "imag": 2}',
68
>>> json.loads('{"__complex__": true, "real": 1, "imag": 2}',
66
69
... object_hook=as_complex)
69
>>> simplejson.loads('1.1', parse_float=decimal.Decimal)
72
Extending JSONEncoder::
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)
81
>>> dumps(2 + 1j, cls=ComplexEncoder)
83
>>> ComplexEncoder().encode(2 + 1j)
85
>>> list(ComplexEncoder().iterencode(2 + 1j))
86
['[', '2.0', ', ', '1.0', ']']
89
Using simplejson from the shell to validate and
72
>>> json.loads('1.1', parse_float=decimal.Decimal) == decimal.Decimal('1.1')
75
Specializing JSON object encoding::
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,))
83
>>> json.dumps(2 + 1j, default=encode_complex)
85
>>> json.JSONEncoder(default=encode_complex).encode(2 + 1j)
87
>>> ''.join(json.JSONEncoder(default=encode_complex).iterencode(2 + 1j))
91
Using simplejson.tool from the shell to validate and pretty-print::
92
93
$ echo '{"json":"obj"}' | python -msimplejson.tool
96
97
$ echo '{ 1.2:3.4}' | python -msimplejson.tool
97
98
Expecting property name: line 1 column 2 (char 2)
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.
102
__version__ = '1.9.2'
104
'dump', 'dumps', 'load', 'loads',
105
'JSONDecoder', 'JSONEncoder',
108
if __name__ == '__main__':
110
warnings.warn('python -msimplejson is deprecated, use python -msiplejson.tool', DeprecationWarning)
101
# Django modification: try to use the system version first, providing it's
102
# either of a later version of has the C speedups in place. Otherwise, fall
103
# back to our local copy.
105
__version__ = '2.0.7'
107
use_system_version = False
109
# The system-installed version has priority providing it is either not an
110
# earlier version or it contains the C speedups.
112
if (simplejson.__version__.split('.') >= __version__.split('.') or
113
hasattr(simplejson, '_speedups')):
114
from simplejson import *
115
use_system_version = True
119
if not use_system_version:
121
from json import * # Python 2.6 preferred over local copy.
123
# There is a "json" package around that is not Python's "json", so we
124
# check for something that is only in the namespace of the version we
128
use_system_version = True
129
except (ImportError, NameError):
132
# If all else fails, we have a bundled version that can be used.
133
if not use_system_version:
135
'dump', 'dumps', 'load', 'loads',
136
'JSONDecoder', 'JSONEncoder',
111
139
from django.utils.simplejson.decoder import JSONDecoder
112
140
from django.utils.simplejson.encoder import JSONEncoder
114
from decoder import JSONDecoder
115
from encoder import JSONEncoder
117
_default_encoder = JSONEncoder(
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):
132
Serialize ``obj`` as a JSON formatted stream to ``fp`` (a
133
``.write()``-supporting file-like object).
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``.
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
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).
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``).
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.
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.
162
``encoding`` is the character encoding for str instances, default is UTF-8.
164
``default(obj)`` is a function that should return a serializable version
165
of obj or raise TypeError. The default simply raises TypeError.
167
To use a custom ``JSONEncoder`` subclass (e.g. one that overrides the
168
``.default()`` method to serialize additional types), specify it with
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)
142
_default_encoder = JSONEncoder(
153
def dump(obj, fp, skipkeys=False, ensure_ascii=True, check_circular=True,
154
allow_nan=True, cls=None, indent=None, separators=None,
155
encoding='utf-8', default=None, **kw):
156
"""Serialize ``obj`` as a JSON formatted stream to ``fp`` (a
157
``.write()``-supporting file-like object).
159
If ``skipkeys`` is ``True`` then ``dict`` keys that are not basic types
160
(``str``, ``unicode``, ``int``, ``long``, ``float``, ``bool``, ``None``)
161
will be skipped instead of raising a ``TypeError``.
163
If ``ensure_ascii`` is ``False``, then the some chunks written to ``fp``
164
may be ``unicode`` instances, subject to normal Python ``str`` to
165
``unicode`` coercion rules. Unless ``fp.write()`` explicitly
166
understands ``unicode`` (as in ``codecs.getwriter()``) this is likely
169
If ``check_circular`` is ``False``, then the circular reference check
170
for container types will be skipped and a circular reference will
171
result in an ``OverflowError`` (or worse).
173
If ``allow_nan`` is ``False``, then it will be a ``ValueError`` to
174
serialize out of range ``float`` values (``nan``, ``inf``, ``-inf``)
175
in strict compliance of the JSON specification, instead of using the
176
JavaScript equivalents (``NaN``, ``Infinity``, ``-Infinity``).
178
If ``indent`` is a non-negative integer, then JSON array elements and object
179
members will be pretty-printed with that indent level. An indent level
180
of 0 will only insert newlines. ``None`` is the most compact representation.
182
If ``separators`` is an ``(item_separator, dict_separator)`` tuple
183
then it will be used instead of the default ``(', ', ': ')`` separators.
184
``(',', ':')`` is the most compact JSON representation.
186
``encoding`` is the character encoding for str instances, default is UTF-8.
188
``default(obj)`` is a function that should return a serializable version
189
of obj or raise TypeError. The default simply raises TypeError.
191
To use a custom ``JSONEncoder`` subclass (e.g. one that overrides the
192
``.default()`` method to serialize additional types), specify it with
197
if (skipkeys is False and ensure_ascii is True and
198
check_circular is True and allow_nan is True and
199
cls is None and indent is None and separators is None and
200
encoding == 'utf-8' and default is None and not kw):
201
iterable = _default_encoder.iterencode(obj)
205
iterable = cls(skipkeys=skipkeys, ensure_ascii=ensure_ascii,
206
check_circular=check_circular, allow_nan=allow_nan, indent=indent,
207
separators=separators, encoding=encoding,
208
default=default, **kw).iterencode(obj)
209
# could accelerate with writelines in some versions of Python, at
210
# a debuggability cost
211
for chunk in iterable:
215
def dumps(obj, skipkeys=False, ensure_ascii=True, check_circular=True,
216
allow_nan=True, cls=None, indent=None, separators=None,
217
encoding='utf-8', default=None, **kw):
218
"""Serialize ``obj`` to a JSON formatted ``str``.
220
If ``skipkeys`` is ``True`` then ``dict`` keys that are not basic types
221
(``str``, ``unicode``, ``int``, ``long``, ``float``, ``bool``, ``None``)
222
will be skipped instead of raising a ``TypeError``.
224
If ``ensure_ascii`` is ``False``, then the return value will be a
225
``unicode`` instance subject to normal Python ``str`` to ``unicode``
226
coercion rules instead of being escaped to an ASCII ``str``.
228
If ``check_circular`` is ``False``, then the circular reference check
229
for container types will be skipped and a circular reference will
230
result in an ``OverflowError`` (or worse).
232
If ``allow_nan`` is ``False``, then it will be a ``ValueError`` to
233
serialize out of range ``float`` values (``nan``, ``inf``, ``-inf``) in
234
strict compliance of the JSON specification, instead of using the
235
JavaScript equivalents (``NaN``, ``Infinity``, ``-Infinity``).
237
If ``indent`` is a non-negative integer, then JSON array elements and
238
object members will be pretty-printed with that indent level. An indent
239
level of 0 will only insert newlines. ``None`` is the most compact
242
If ``separators`` is an ``(item_separator, dict_separator)`` tuple
243
then it will be used instead of the default ``(', ', ': ')`` separators.
244
``(',', ':')`` is the most compact JSON representation.
246
``encoding`` is the character encoding for str instances, default is UTF-8.
248
``default(obj)`` is a function that should return a serializable version
249
of obj or raise TypeError. The default simply raises TypeError.
251
To use a custom ``JSONEncoder`` subclass (e.g. one that overrides the
252
``.default()`` method to serialize additional types), specify it with
257
if (skipkeys is False and ensure_ascii is True and
258
check_circular is True and allow_nan is True and
259
cls is None and indent is None and separators is None and
260
encoding == 'utf-8' and default is None and not kw):
261
return _default_encoder.encode(obj)
179
263
cls = JSONEncoder
180
iterable = cls(skipkeys=skipkeys, ensure_ascii=ensure_ascii,
265
skipkeys=skipkeys, ensure_ascii=ensure_ascii,
181
266
check_circular=check_circular, allow_nan=allow_nan, indent=indent,
182
separators=separators, encoding=encoding,
183
default=default, **kw).iterencode(obj)
184
# could accelerate with writelines in some versions of Python, at
185
# a debuggability cost
186
for chunk in iterable:
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):
194
Serialize ``obj`` to a JSON formatted ``str``.
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``.
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``.
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).
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``).
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
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.
222
``encoding`` is the character encoding for str instances, default is UTF-8.
224
``default(obj)`` is a function that should return a serializable version
225
of obj or raise TypeError. The default simply raises TypeError.
227
To use a custom ``JSONEncoder`` subclass (e.g. one that overrides the
228
``.default()`` method to serialize additional types), specify it with
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)
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,
246
_default_decoder = JSONDecoder(encoding=None, object_hook=None)
249
def load(fp, encoding=None, cls=None, object_hook=None, parse_float=None,
250
parse_int=None, parse_constant=None, **kw):
252
Deserialize ``fp`` (a ``.read()``-supporting file-like object containing
253
a JSON document) to a Python object.
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()``
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).
267
To use a custom ``JSONDecoder`` subclass, specify it with the ``cls``
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)
276
def loads(s, encoding=None, cls=None, object_hook=None, parse_float=None,
277
parse_int=None, parse_constant=None, **kw):
279
Deserialize ``s`` (a ``str`` or ``unicode`` instance containing a JSON
280
document) to a Python object.
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.
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).
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).
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).
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
307
To use a custom ``JSONDecoder`` subclass, specify it with the ``cls``
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)
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)
328
# Compatibility cruft from other libraries
334
demjson, python-cjson API compatibility hook. Use loads(s) instead.
337
warnings.warn("simplejson.loads(s) should be used instead of decode(s)",
344
demjson, python-cjson compatibility hook. Use dumps(s) instead.
347
warnings.warn("simplejson.dumps(s) should be used instead of encode(s)",
354
jsonlib, JsonUtils, python-json, json-py API compatibility hook.
355
Use loads(s) instead.
358
warnings.warn("simplejson.loads(s) should be used instead of read(s)",
365
jsonlib, JsonUtils, python-json, json-py API compatibility hook.
366
Use dumps(s) instead.
369
warnings.warn("simplejson.dumps(s) should be used instead of write(s)",
374
if __name__ == '__main__':
375
import simplejson.tool
376
simplejson.tool.main()
267
separators=separators, encoding=encoding, default=default,
271
_default_decoder = JSONDecoder(encoding=None, object_hook=None)
274
def load(fp, encoding=None, cls=None, object_hook=None, parse_float=None,
275
parse_int=None, parse_constant=None, **kw):
276
"""Deserialize ``fp`` (a ``.read()``-supporting file-like object containing
277
a JSON document) to a Python object.
279
If the contents of ``fp`` is encoded with an ASCII based encoding other
280
than utf-8 (e.g. latin-1), then an appropriate ``encoding`` name must
281
be specified. Encodings that are not ASCII based (such as UCS-2) are
282
not allowed, and should be wrapped with
283
``codecs.getreader(fp)(encoding)``, or simply decoded to a ``unicode``
284
object and passed to ``loads()``
286
``object_hook`` is an optional function that will be called with the
287
result of any object literal decode (a ``dict``). The return value of
288
``object_hook`` will be used instead of the ``dict``. This feature
289
can be used to implement custom decoders (e.g. JSON-RPC class hinting).
291
To use a custom ``JSONDecoder`` subclass, specify it with the ``cls``
295
return loads(fp.read(),
296
encoding=encoding, cls=cls, object_hook=object_hook,
297
parse_float=parse_float, parse_int=parse_int,
298
parse_constant=parse_constant, **kw)
301
def loads(s, encoding=None, cls=None, object_hook=None, parse_float=None,
302
parse_int=None, parse_constant=None, **kw):
303
"""Deserialize ``s`` (a ``str`` or ``unicode`` instance containing a JSON
304
document) to a Python object.
306
If ``s`` is a ``str`` instance and is encoded with an ASCII based encoding
307
other than utf-8 (e.g. latin-1) then an appropriate ``encoding`` name
308
must be specified. Encodings that are not ASCII based (such as UCS-2)
309
are not allowed and should be decoded to ``unicode`` first.
311
``object_hook`` is an optional function that will be called with the
312
result of any object literal decode (a ``dict``). The return value of
313
``object_hook`` will be used instead of the ``dict``. This feature
314
can be used to implement custom decoders (e.g. JSON-RPC class hinting).
316
``parse_float``, if specified, will be called with the string
317
of every JSON float to be decoded. By default this is equivalent to
318
float(num_str). This can be used to use another datatype or parser
319
for JSON floats (e.g. decimal.Decimal).
321
``parse_int``, if specified, will be called with the string
322
of every JSON int to be decoded. By default this is equivalent to
323
int(num_str). This can be used to use another datatype or parser
324
for JSON integers (e.g. float).
326
``parse_constant``, if specified, will be called with one of the
327
following strings: -Infinity, Infinity, NaN, null, true, false.
328
This can be used to raise an exception if invalid JSON numbers
331
To use a custom ``JSONDecoder`` subclass, specify it with the ``cls``
335
if (cls is None and encoding is None and object_hook is None and
336
parse_int is None and parse_float is None and
337
parse_constant is None and not kw):
338
return _default_decoder.decode(s)
341
if object_hook is not None:
342
kw['object_hook'] = object_hook
343
if parse_float is not None:
344
kw['parse_float'] = parse_float
345
if parse_int is not None:
346
kw['parse_int'] = parse_int
347
if parse_constant is not None:
348
kw['parse_constant'] = parse_constant
349
return cls(encoding=encoding, **kw).decode(s)
added
removed
django/utils/simplejson/__init__.py
