0001r"""
0002A simple, fast, extensible JSON encoder and decoder
0003
0004JSON (JavaScript Object Notation) <http://json.org> is a subset of
0005JavaScript syntax (ECMA-262 3rd edition) used as a lightweight data
0006interchange format.
0007
0008simplejson exposes an API familiar to uses of the standard library
0009marshal and pickle modules.
0010
0011Encoding basic Python object hierarchies::
0012
0013 >>> import simplejson
0014 >>> simplejson.dumps(['foo', {'bar': ('baz', None, 1.0, 2)}])
0015 '["foo", {"bar": ["baz", null, 1.0, 2]}]'
0016 >>> print simplejson.dumps("\"foo\bar")
0017 "\"foo\bar"
0018 >>> print simplejson.dumps(u'\u1234')
0019 "\u1234"
0020 >>> print simplejson.dumps('\\')
0021 "\\"
0022 >>> print simplejson.dumps({"c": 0, "b": 0, "a": 0}, sort_keys=True)
0023 {"a": 0, "b": 0, "c": 0}
0024 >>> from StringIO import StringIO
0025 >>> io = StringIO()
0026 >>> simplejson.dump(['streaming API'], io)
0027 >>> io.getvalue()
0028 '["streaming API"]'
0029
0030Compact encoding::
0031
0032 >>> import simplejson
0033 >>> simplejson.dumps([1,2,3,{'4': 5, '6': 7}], separators=(',',':'))
0034 '[1,2,3,{"4":5,"6":7}]'
0035
0036Pretty printing::
0037
0038 >>> import simplejson
0039 >>> print simplejson.dumps({'4': 5, '6': 7}, sort_keys=True, indent=4)
0040 {
0041 "4": 5,
0042 "6": 7
0043 }
0044
0045Decoding JSON::
0046
0047 >>> import simplejson
0048 >>> simplejson.loads('["foo", {"bar":["baz", null, 1.0, 2]}]')
0049 [u'foo', {u'bar': [u'baz', None, 1.0, 2]}]
0050 >>> simplejson.loads('"\\"foo\\bar"')
0051 u'"foo\x08ar'
0052 >>> from StringIO import StringIO
0053 >>> io = StringIO('["streaming API"]')
0054 >>> simplejson.load(io)
0055 [u'streaming API']
0056
0057Specializing JSON object decoding::
0058
0059 >>> import simplejson
0060 >>> def as_complex(dct):
0061 ... if '__complex__' in dct:
0062 ... return complex(dct['real'], dct['imag'])
0063 ... return dct
0064 ...
0065 >>> simplejson.loads('{"__complex__": true, "real": 1, "imag": 2}',
0066 ... object_hook=as_complex)
0067 (1+2j)
0068 >>> import decimal
0069 >>> simplejson.loads('1.1', parse_float=decimal.Decimal)
0070 decimal.Decimal(1.1)
0071
0072Extending JSONEncoder::
0073
0074 >>> import simplejson
0075 >>> class ComplexEncoder(simplejson.JSONEncoder):
0076 ... def default(self, obj):
0077 ... if isinstance(obj, complex):
0078 ... return [obj.real, obj.imag]
0079 ... return simplejson.JSONEncoder.default(self, obj)
0080 ...
0081 >>> dumps(2 + 1j, cls=ComplexEncoder)
0082 '[2.0, 1.0]'
0083 >>> ComplexEncoder().encode(2 + 1j)
0084 '[2.0, 1.0]'
0085 >>> list(ComplexEncoder().iterencode(2 + 1j))
0086 ['[', '2.0', ', ', '1.0', ']']
0087
0088
0089Using simplejson from the shell to validate and
0090pretty-print::
0091
0092 $ echo '{"json":"obj"}' | python -msimplejson
0093 {
0094 "json": "obj"
0095 }
0096 $ echo '{ 1.2:3.4}' | python -msimplejson
0097 Expecting property name: line 1 column 2 (char 2)
0098
0099Note that the JSON produced by this module's default settings
0100is a subset of YAML, so it may be used as a serializer for that as well.
0101"""
0102__version__ = '1.8.1'
0103__all__ = [
0104 'dump', 'dumps', 'load', 'loads',
0105 'JSONDecoder', 'JSONEncoder',
0106]
0107
0108if __name__ == '__main__':
0109 from simplejson.decoder import JSONDecoder
0110 from simplejson.encoder import JSONEncoder
0111else:
0112 from decoder import JSONDecoder
0113 from encoder import JSONEncoder
0114
0115_default_encoder = JSONEncoder(
0116 skipkeys=False,
0117 ensure_ascii=True,
0118 check_circular=True,
0119 allow_nan=True,
0120 indent=None,
0121 separators=None,
0122 encoding='utf-8',
0123 default=None,
0124)
0125
0126def dump(obj, fp, skipkeys=False, ensure_ascii=True, check_circular=True,
0127 allow_nan=True, cls=None, indent=None, separators=None,
0128 encoding='utf-8', default=None, **kw):
0129 """
0130 Serialize ``obj`` as a JSON formatted stream to ``fp`` (a
0131 ``.write()``-supporting file-like object).
0132
0133 If ``skipkeys`` is ``True`` then ``dict`` keys that are not basic types
0134 (``str``, ``unicode``, ``int``, ``long``, ``float``, ``bool``, ``None``)
0135 will be skipped instead of raising a ``TypeError``.
0136
0137 If ``ensure_ascii`` is ``False``, then the some chunks written to ``fp``
0138 may be ``unicode`` instances, subject to normal Python ``str`` to
0139 ``unicode`` coercion rules. Unless ``fp.write()`` explicitly
0140 understands ``unicode`` (as in ``codecs.getwriter()``) this is likely
0141 to cause an error.
0142
0143 If ``check_circular`` is ``False``, then the circular reference check
0144 for container types will be skipped and a circular reference will
0145 result in an ``OverflowError`` (or worse).
0146
0147 If ``allow_nan`` is ``False``, then it will be a ``ValueError`` to
0148 serialize out of range ``float`` values (``nan``, ``inf``, ``-inf``)
0149 in strict compliance of the JSON specification, instead of using the
0150 JavaScript equivalents (``NaN``, ``Infinity``, ``-Infinity``).
0151
0152 If ``indent`` is a non-negative integer, then JSON array elements and object
0153 members will be pretty-printed with that indent level. An indent level
0154 of 0 will only insert newlines. ``None`` is the most compact representation.
0155
0156 If ``separators`` is an ``(item_separator, dict_separator)`` tuple
0157 then it will be used instead of the default ``(', ', ': ')`` separators.
0158 ``(',', ':')`` is the most compact JSON representation.
0159
0160 ``encoding`` is the character encoding for str instances, default is UTF-8.
0161
0162 ``default(obj)`` is a function that should return a serializable version
0163 of obj or raise TypeError. The default simply raises TypeError.
0164
0165 To use a custom ``JSONEncoder`` subclass (e.g. one that overrides the
0166 ``.default()`` method to serialize additional types), specify it with
0167 the ``cls`` kwarg.
0168 """
0169
0170 if (skipkeys is False and ensure_ascii is True and
0171 check_circular is True and allow_nan is True and
0172 cls is None and indent is None and separators is None and
0173 encoding == 'utf-8' and default is None and not kw):
0174 iterable = _default_encoder.iterencode(obj)
0175 else:
0176 if cls is None:
0177 cls = JSONEncoder
0178 iterable = cls(skipkeys=skipkeys, ensure_ascii=ensure_ascii,
0179 check_circular=check_circular, allow_nan=allow_nan, indent=indent,
0180 separators=separators, encoding=encoding,
0181 default=default, **kw).iterencode(obj)
0182
0183
0184 for chunk in iterable:
0185 fp.write(chunk)
0186
0187
0188def dumps(obj, skipkeys=False, ensure_ascii=True, check_circular=True,
0189 allow_nan=True, cls=None, indent=None, separators=None,
0190 encoding='utf-8', default=None, **kw):
0191 """
0192 Serialize ``obj`` to a JSON formatted ``str``.
0193
0194 If ``skipkeys`` is ``True`` then ``dict`` keys that are not basic types
0195 (``str``, ``unicode``, ``int``, ``long``, ``float``, ``bool``, ``None``)
0196 will be skipped instead of raising a ``TypeError``.
0197
0198 If ``ensure_ascii`` is ``False``, then the return value will be a
0199 ``unicode`` instance subject to normal Python ``str`` to ``unicode``
0200 coercion rules instead of being escaped to an ASCII ``str``.
0201
0202 If ``check_circular`` is ``False``, then the circular reference check
0203 for container types will be skipped and a circular reference will
0204 result in an ``OverflowError`` (or worse).
0205
0206 If ``allow_nan`` is ``False``, then it will be a ``ValueError`` to
0207 serialize out of range ``float`` values (``nan``, ``inf``, ``-inf``) in
0208 strict compliance of the JSON specification, instead of using the
0209 JavaScript equivalents (``NaN``, ``Infinity``, ``-Infinity``).
0210
0211 If ``indent`` is a non-negative integer, then JSON array elements and
0212 object members will be pretty-printed with that indent level. An indent
0213 level of 0 will only insert newlines. ``None`` is the most compact
0214 representation.
0215
0216 If ``separators`` is an ``(item_separator, dict_separator)`` tuple
0217 then it will be used instead of the default ``(', ', ': ')`` separators.
0218 ``(',', ':')`` is the most compact JSON representation.
0219
0220 ``encoding`` is the character encoding for str instances, default is UTF-8.
0221
0222 ``default(obj)`` is a function that should return a serializable version
0223 of obj or raise TypeError. The default simply raises TypeError.
0224
0225 To use a custom ``JSONEncoder`` subclass (e.g. one that overrides the
0226 ``.default()`` method to serialize additional types), specify it with
0227 the ``cls`` kwarg.
0228 """
0229
0230 if (skipkeys is False and ensure_ascii is True and
0231 check_circular is True and allow_nan is True and
0232 cls is None and indent is None and separators is None and
0233 encoding == 'utf-8' and default is None and not kw):
0234 return _default_encoder.encode(obj)
0235 if cls is None:
0236 cls = JSONEncoder
0237 return cls(
0238 skipkeys=skipkeys, ensure_ascii=ensure_ascii,
0239 check_circular=check_circular, allow_nan=allow_nan, indent=indent,
0240 separators=separators, encoding=encoding, default=default,
0241 **kw).encode(obj)
0242
0243_default_decoder = JSONDecoder(encoding=None, object_hook=None)
0244
0245def load(fp, encoding=None, cls=None, object_hook=None, parse_float=None,
0246 parse_int=None, parse_constant=None, **kw):
0247 """
0248 Deserialize ``fp`` (a ``.read()``-supporting file-like object containing
0249 a JSON document) to a Python object.
0250
0251 If the contents of ``fp`` is encoded with an ASCII based encoding other
0252 than utf-8 (e.g. latin-1), then an appropriate ``encoding`` name must
0253 be specified. Encodings that are not ASCII based (such as UCS-2) are
0254 not allowed, and should be wrapped with
0255 ``codecs.getreader(fp)(encoding)``, or simply decoded to a ``unicode``
0256 object and passed to ``loads()``
0257
0258 ``object_hook`` is an optional function that will be called with the
0259 result of any object literal decode (a ``dict``). The return value of
0260 ``object_hook`` will be used instead of the ``dict``. This feature
0261 can be used to implement custom decoders (e.g. JSON-RPC class hinting).
0262
0263 To use a custom ``JSONDecoder`` subclass, specify it with the ``cls``
0264 kwarg.
0265 """
0266 return loads(fp.read(),
0267 encoding=encoding, cls=cls, object_hook=object_hook,
0268 parse_float=parse_float, parse_int=parse_int,
0269 parse_constant=parse_constant, **kw)
0270
0271def loads(s, encoding=None, cls=None, object_hook=None, parse_float=None,
0272 parse_int=None, parse_constant=None, **kw):
0273 """
0274 Deserialize ``s`` (a ``str`` or ``unicode`` instance containing a JSON
0275 document) to a Python object.
0276
0277 If ``s`` is a ``str`` instance and is encoded with an ASCII based encoding
0278 other than utf-8 (e.g. latin-1) then an appropriate ``encoding`` name
0279 must be specified. Encodings that are not ASCII based (such as UCS-2)
0280 are not allowed and should be decoded to ``unicode`` first.
0281
0282 ``object_hook`` is an optional function that will be called with the
0283 result of any object literal decode (a ``dict``). The return value of
0284 ``object_hook`` will be used instead of the ``dict``. This feature
0285 can be used to implement custom decoders (e.g. JSON-RPC class hinting).
0286
0287 ``parse_float``, if specified, will be called with the string
0288 of every JSON float to be decoded. By default this is equivalent to
0289 float(num_str). This can be used to use another datatype or parser
0290 for JSON floats (e.g. decimal.Decimal).
0291
0292 ``parse_int``, if specified, will be called with the string
0293 of every JSON int to be decoded. By default this is equivalent to
0294 int(num_str). This can be used to use another datatype or parser
0295 for JSON integers (e.g. float).
0296
0297 ``parse_constant``, if specified, will be called with one of the
0298 following strings: -Infinity, Infinity, NaN, null, true, false.
0299 This can be used to raise an exception if invalid JSON numbers
0300 are encountered.
0301
0302 To use a custom ``JSONDecoder`` subclass, specify it with the ``cls``
0303 kwarg.
0304 """
0305 if (cls is None and encoding is None and object_hook is None and
0306 parse_int is None and parse_float is None and
0307 parse_constant is None and not kw):
0308 return _default_decoder.decode(s)
0309 if cls is None:
0310 cls = JSONDecoder
0311 if object_hook is not None:
0312 kw['object_hook'] = object_hook
0313 if parse_float is not None:
0314 kw['parse_float'] = parse_float
0315 if parse_int is not None:
0316 kw['parse_int'] = parse_int
0317 if parse_constant is not None:
0318 kw['parse_constant'] = parse_constant
0319 return cls(encoding=encoding, **kw).decode(s)
0320
0321
0322
0323
0324
0325def decode(s):
0326 """
0327 demjson, python-cjson API compatibility hook. Use loads(s) instead.
0328 """
0329 import warnings
0330 warnings.warn("simplejson.loads(s) should be used instead of decode(s)",
0331 DeprecationWarning)
0332 return loads(s)
0333
0334def encode(obj):
0335 """
0336 demjson, python-cjson compatibility hook. Use dumps(s) instead.
0337 """
0338 import warnings
0339 warnings.warn("simplejson.dumps(s) should be used instead of encode(s)",
0340 DeprecationWarning)
0341 return dumps(obj)
0342
0343def read(s):
0344 """
0345 jsonlib, JsonUtils, python-json, json-py API compatibility hook.
0346 Use loads(s) instead.
0347 """
0348 import warnings
0349 warnings.warn("simplejson.loads(s) should be used instead of read(s)",
0350 DeprecationWarning)
0351 return loads(s)
0352
0353def write(obj):
0354 """
0355 jsonlib, JsonUtils, python-json, json-py API compatibility hook.
0356 Use dumps(s) instead.
0357 """
0358 import warnings
0359 warnings.warn("simplejson.dumps(s) should be used instead of write(s)",
0360 DeprecationWarning)
0361 return dumps(obj)
0362
0363
0364
0365
0366
0367
0368def main():
0369 import sys
0370 if len(sys.argv) == 1:
0371 infile = sys.stdin
0372 outfile = sys.stdout
0373 elif len(sys.argv) == 2:
0374 infile = open(sys.argv[1], 'rb')
0375 outfile = sys.stdout
0376 elif len(sys.argv) == 3:
0377 infile = open(sys.argv[1], 'rb')
0378 outfile = open(sys.argv[2], 'wb')
0379 else:
0380 raise SystemExit("%s [infile [outfile]]" % (sys.argv[0],))
0381 try:
0382 obj = load(infile)
0383 except ValueError, e:
0384 raise SystemExit(e)
0385 dump(obj, outfile, sort_keys=True, indent=4)
0386 outfile.write('\n')
0387
0388if __name__ == '__main__':
0389 main()