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("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.9'
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
0244_default_decoder = JSONDecoder(encoding=None, object_hook=None)
0245
0246
0247def load(fp, encoding=None, cls=None, object_hook=None, parse_float=None,
0248 parse_int=None, parse_constant=None, **kw):
0249 """
0250 Deserialize ``fp`` (a ``.read()``-supporting file-like object containing
0251 a JSON document) to a Python object.
0252
0253 If the contents of ``fp`` is encoded with an ASCII based encoding other
0254 than utf-8 (e.g. latin-1), then an appropriate ``encoding`` name must
0255 be specified. Encodings that are not ASCII based (such as UCS-2) are
0256 not allowed, and should be wrapped with
0257 ``codecs.getreader(fp)(encoding)``, or simply decoded to a ``unicode``
0258 object and passed to ``loads()``
0259
0260 ``object_hook`` is an optional function that will be called with the
0261 result of any object literal decode (a ``dict``). The return value of
0262 ``object_hook`` will be used instead of the ``dict``. This feature
0263 can be used to implement custom decoders (e.g. JSON-RPC class hinting).
0264
0265 To use a custom ``JSONDecoder`` subclass, specify it with the ``cls``
0266 kwarg.
0267 """
0268 return loads(fp.read(),
0269 encoding=encoding, cls=cls, object_hook=object_hook,
0270 parse_float=parse_float, parse_int=parse_int,
0271 parse_constant=parse_constant, **kw)
0272
0273
0274def loads(s, encoding=None, cls=None, object_hook=None, parse_float=None,
0275 parse_int=None, parse_constant=None, **kw):
0276 """
0277 Deserialize ``s`` (a ``str`` or ``unicode`` instance containing a JSON
0278 document) to a Python object.
0279
0280 If ``s`` is a ``str`` instance and is encoded with an ASCII based encoding
0281 other than utf-8 (e.g. latin-1) then an appropriate ``encoding`` name
0282 must be specified. Encodings that are not ASCII based (such as UCS-2)
0283 are not allowed and should be decoded to ``unicode`` first.
0284
0285 ``object_hook`` is an optional function that will be called with the
0286 result of any object literal decode (a ``dict``). The return value of
0287 ``object_hook`` will be used instead of the ``dict``. This feature
0288 can be used to implement custom decoders (e.g. JSON-RPC class hinting).
0289
0290 ``parse_float``, if specified, will be called with the string
0291 of every JSON float to be decoded. By default this is equivalent to
0292 float(num_str). This can be used to use another datatype or parser
0293 for JSON floats (e.g. decimal.Decimal).
0294
0295 ``parse_int``, if specified, will be called with the string
0296 of every JSON int to be decoded. By default this is equivalent to
0297 int(num_str). This can be used to use another datatype or parser
0298 for JSON integers (e.g. float).
0299
0300 ``parse_constant``, if specified, will be called with one of the
0301 following strings: -Infinity, Infinity, NaN, null, true, false.
0302 This can be used to raise an exception if invalid JSON numbers
0303 are encountered.
0304
0305 To use a custom ``JSONDecoder`` subclass, specify it with the ``cls``
0306 kwarg.
0307 """
0308 if (cls is None and encoding is None and object_hook is None and
0309 parse_int is None and parse_float is None and
0310 parse_constant is None and not kw):
0311 return _default_decoder.decode(s)
0312 if cls is None:
0313 cls = JSONDecoder
0314 if object_hook is not None:
0315 kw['object_hook'] = object_hook
0316 if parse_float is not None:
0317 kw['parse_float'] = parse_float
0318 if parse_int is not None:
0319 kw['parse_int'] = parse_int
0320 if parse_constant is not None:
0321 kw['parse_constant'] = parse_constant
0322 return cls(encoding=encoding, **kw).decode(s)
0323
0324
0325
0326
0327
0328
0329
0330def decode(s):
0331 """
0332 demjson, python-cjson API compatibility hook. Use loads(s) instead.
0333 """
0334 import warnings
0335 warnings.warn("simplejson.loads(s) should be used instead of decode(s)",
0336 DeprecationWarning)
0337 return loads(s)
0338
0339
0340def encode(obj):
0341 """
0342 demjson, python-cjson compatibility hook. Use dumps(s) instead.
0343 """
0344 import warnings
0345 warnings.warn("simplejson.dumps(s) should be used instead of encode(s)",
0346 DeprecationWarning)
0347 return dumps(obj)
0348
0349
0350def read(s):
0351 """
0352 jsonlib, JsonUtils, python-json, json-py API compatibility hook.
0353 Use loads(s) instead.
0354 """
0355 import warnings
0356 warnings.warn("simplejson.loads(s) should be used instead of read(s)",
0357 DeprecationWarning)
0358 return loads(s)
0359
0360
0361def write(obj):
0362 """
0363 jsonlib, JsonUtils, python-json, json-py API compatibility hook.
0364 Use dumps(s) instead.
0365 """
0366 import warnings
0367 warnings.warn("simplejson.dumps(s) should be used instead of write(s)",
0368 DeprecationWarning)
0369 return dumps(obj)
0370
0371
0372
0373
0374
0375
0376
0377
0378def main():
0379 import sys
0380 if len(sys.argv) == 1:
0381 infile = sys.stdin
0382 outfile = sys.stdout
0383 elif len(sys.argv) == 2:
0384 infile = open(sys.argv[1], 'rb')
0385 outfile = sys.stdout
0386 elif len(sys.argv) == 3:
0387 infile = open(sys.argv[1], 'rb')
0388 outfile = open(sys.argv[2], 'wb')
0389 else:
0390 raise SystemExit("%s [infile [outfile]]" % (sys.argv[0],))
0391 try:
0392 obj = load(infile)
0393 except ValueError, e:
0394 raise SystemExit(e)
0395 dump(obj, outfile, sort_keys=True, indent=4)
0396 outfile.write('\n')
0397
0398
0399if __name__ == '__main__':
0400 main()