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    # cached encoder
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    # could accelerate with writelines in some versions of Python, at
0183    # a debuggability cost
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    # cached encoder
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# Compatibility cruft from other libraries
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# Pretty printer:
0374#     curl http://mochikit.com/examples/ajax_tables/domains.json | python -msimplejson
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()