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()