Package: jsonlib2
Author:John MillikinCopyright:This document has been placed in the public domain.OverviewThis is yet another library for reading/writing json. The goal is to
be API compatible withsimplejson, except that it is written
purely in C and is thus 5x-20x faster for both encoding and decoding,
depending on the data.This is a fork of thejsonlibproject by the folks over atFreebasewho
have data coming from a variety of internal sources in different
encodings and formats, not all of which could simply be represented by
strict JSON.Thus, the intent of this fork is to be more lenient in its
encoding and decoding (as simplejson is) allowing things like
NaN/-NaN/Infinity, automatic handling of unicode, and more. The first
release of jsonlib2 was version 1.4, which was forked from jsonlib
1.3.10.ContentsOverviewUsageDeserializationFloating-point valuesSerializationPretty-PrintingMapping Key SortingEncoding and UnicodeMapping Key CoercionSerializing Other TypesStreaming SerializerExceptionsReadErrorWriteErrorUnknownSerializerErrorChange Log1.5.11.51.4.21.4.11.41.3.101.3.91.3.81.3.71.3.61.3.51.3.41.3.31.3.21.3.11.3.01.2.71.2.61.2.51.2.41.2.31.2.21.2.11.2.01.1.01.0.0Usagejsonlib2 has two functions of interest,readandwrite. It also
defines some exception:ReadError,WriteError, andUnknownSerializerError.For compatibility with the standard library,readis aliased toloadsandwriteis aliased todumps. They do not have the
same set of advanced parameters, but may be used interchangeably for
simple invocations.DeserializationTo deserialize a JSON expression, call thejsonlib2.readfunction with
an instance ofstrorunicode.>>> import jsonlib2
>>> jsonlib2.read ('["Hello world!"]')
[u'Hello world!']Floating-point valuesBy default,jsonlib2will parse values such as “1.1” into an instance ofdecimal.Decimal. To use the built-in value typefloatinstead, set
theuse_floatparameter toTrue. Please note that this may cause a
loss of precision when parsing some values.>>> jsonlib2.read ('[1.5]', use_float = True)
[1.5]
>>> jsonlib2.read ('[1.1]', use_float = True)
[1.1000000000000001]
>>> jsonlib2.read ('[3.14159265358979323846]', use_float = True)
[3.1415926535897931]SerializationSerialization has more options, but they are set to reasonable defaults.
The simplest use is to calljsonlib2.writewith a Python value.>>> import jsonlib2
>>> jsonlib2.write (['Hello world!'])
'["Hello world!"]'Pretty-PrintingTo “pretty-print” the output, pass a value for theindentparameter.>>> print jsonlib2.write (['Hello world!'], indent = '    ')
[
    "Hello world!"
]
>>>Mapping Key SortingBy default, mapping keys are serialized in whatever order they are
stored by Python. To force a consistent ordering (for example, in doctests)
use thesort_keysparameter.>>> jsonlib2.write ({'e': 'Hello', 'm': 'World!'})
'{"m":"World!","e":"Hello"}'
>>> jsonlib2.write ({'e': 'Hello', 'm': 'World!'}, sort_keys = True)
'{"e":"Hello","m":"World!"}'Encoding and UnicodeBy default, the output is encoded in UTF-8. If you require a different
encoding, pass the name of a Python codec as theencodingparameter.>>> jsonlib2.write (['Hello world!'], encoding = 'utf-16-be')
'\x00[\x00"\x00H\x00e\x00l\x00l\x00o\x00 \x00w\x00o\x00r\x00l\x00d\x00!\x00"\x00]'To retrieve an unencodedunicodeinstance, passNonefor the
encoding.>>> jsonlib2.write (['Hello world!'], encoding = None)
u'["Hello world!"]'By default, non-ASCII codepoints are forbidden in the output. To include
higher codepoints in the output, setensure_asciitoFalse.>>> jsonlib2.write ([u'Hello \u266a'], encoding = None)
u'["Hello \\u266a"]'
>>> jsonlib2.write ([u'Hello \u266a'], encoding = None, ensure_ascii = False)
u'["Hello \u266a"]'Mapping Key CoercionBecause JSON objects must have string keys, strings will be ‘coerced’
to strings. You can override this with thecoerce_keysparameter,
whcih will raise exception when non-string keys are encountered in a
mapping.>>> jsonlib2.write ({True: 1})
'{"true":1}'
>>> jsonlib2.write ({True: 1}, coerce_keys = False)
Traceback (most recent call last):
WriteError: Only strings may be used as object keys.Serializing Other TypesIf the object implements the iterator or mapping protocol, it will be
handled automatically. If the object is intended for use as a basic value,
it should subclass one of the supported basic values.String-like objects that do not inherit fromstr,unicode, orUserString.UserStringwill likely be serialized as a list. This will
not be changed. If iterating them returns an instance of the same type, the
serializer might crash. This (hopefully) will be changed.To serialize a type not known to jsonlib2, use thedefaultparameter
towrite:>>> from datetime import date
>>> def default_handler (value):
...     if isinstance (value, date): return str (value)
...     raise jsonlib2.UnknownSerializerError
>>> jsonlib2.write ([date (2000, 1, 1)], default = default_handler)
'["2000-01-01"]'Streaming SerializerWhen serializing large objects, the use of an in-memory buffer may cause
too much memory to be used. For these situations, use thedumpfunction
to write objects to a file-like object:>>> import sys
>>> jsonlib2.dump (["Written to stdout"], sys.stdout)
["Written to stdout"]
>>>ExceptionsReadErrorRaised byreadif an error was encountered parsing the expression. Will
contain the line, column, and character position of the error.Note that this will report thecharacter, not thebyte, of the character
that caused the error.WriteErrorRaised bywriteordumpif an error was encountered serializing
the passed value.UnknownSerializerErrorA subclass ofWriteErrorthat is raised when a value cannot be
serialized. See thedefaultparameter towrite.Change Log1.5.1Fixed problem compiling on Python before version 2.6, as reported by
Carlo Barrettara and others1.5Major API change - add lots of support for simplejson keywordsdropped use of Decimal module, and thus theuse_floatparameter
inload. Indump, usedefault.inload, added parsing support for Infinity, -Infinity, NaNinload, added support forparse_float,parse_int,parse_constantindump,allow_non_numbersbecameallow_nanindump,allow_nan(formerlyallow_non_numbers) is now
True by defaultindump,on_unknownbecamedefaultindump,ascii_onlybecameensure_asciiindump,coerce_keysis now True by defaultRemoved JSON-strict restriction, allowing bothloadanddumpto deal with objects that are not lists or dictionaries at the root
level.1.4.2Memory leak fix1.4.1Addedescape_slashparameter towrite()to stop escaping the
‘/’ character1.4First release as jsonlib21.3.10Implemented theuse_floatparameter toread().1.3.9Fixed a crash on some platforms when passing a non-string object for
indentation.1.3.8Fixed memory leak when auto-decoding bytestrings.Fixed potential memory leak when usingon_unknownhandlers that
return invalid objects.1.3.7Fixed error reporting positions of syntax errors that occur immediately
after a newline.Addloads()anddumps()as aliases toread()andwrite(),
respectively, for compatibility with the newjsonstandard library
module.Small fixes to the test suite to clear spurious errors caused by
differences between the behavior ofrepr()on instances ofdecimal.DecimalandUnicodeDecodeError.1.3.6If an unterminated object or array is encountered, report its start
location properly.Improved reporting of unknown escape codes.Raise an exception when parsing a root value that is not an array
or object.Allow instances ofUserStringto be used as object keys.Implemented thedump()function.1.3.5Bugfix release, corrects serialization ofdictwhenPyDict_Next()skips indexes.1.3.4Fixes an issue with reporting the column of a syntax error when the
error is followed by a newline.Removed remaining Python wrapper forread.1.3.3Support theon_unknownparameter towrite.Corrected typo in invalid whitespace detection.Added__version__attribute.Merged all code intojsonlib2and_jsonlibmodules, instead of
a package.1.3.2Improved the README.Support for reading text encoded with theutf-8-sigcodec.Usecodecsmodule for detecting BOMs in input data.Forbid non-whitespace strings from being used for indentation.1.3.1Removed the Python implementations of the serializer and deserializer.Detect and raise an exception if invalid surrogate pairs are serialized
or deserialized.Detect and raise an exception if reserved codepoints are serialized or
deserialized.Added support for operating in a process with multiple Python interpreters.Performance improvements.1.3.0Allowpython setup.py testto work.Addedencodingparameter towrite, which controls the output
encoding. The default encoding isutf-8. If the encoding isNone,
aunicodestring will be returned.Implementedwriteusing a C extension module.1.2.7Improved error messages when an error is encountered deserializing an
expression.Modified to work with Python 2.4.1.2.6Thanks to Deron Meranda (author ofdemjson) for his excellentJSON
library comparison,
which revealed many areas for improvement:Usereprinstead ofunicodefor serializing floating-point values,
to avoid unnecessary rounding.Fixed bug that prevented plus signs in an exponent from being parsed
correctly.Added support for serializing the following types:generatorsetfrozensetcomplex, for values with no imaginary component.array.arraycollections.dequecollections.defaultdictUserList.UserListUserDict.UserDictUserString.UserStringRaise an exception if a control character is encountered in a string.Added support for detecting Unicode byte order marks in the auto decoder.Allow only arrays and objects to be serialized directly. All other types
must be contained within an array or object.Stricter detection of whitespace.Also includes some other miscellaneous fixes:More reliable detection ofInfinityandNaNon Windows.Support for decoding UTF-32 on UCS2 builds of Python.Faster detection of self-recursive containers.1.2.5Return Unicode strings fromwrite, so the user can control the final
encoding.PreventInfinity,-Infinity, andNaNfrom being serialized
because JSON does not support these values.Addedcoerce_keysparameter towrite. IfTrue, mapping keys
will be coerced to strings. Defaults toFalse.Addedascii_onlyparameter towrite. IfTrue, non-ASCII
codepoints will always be escaped to a u sequence. Defaults toTrue.Real detection of self-recursive container types.Escape the solidus to prevent againstsecurity issues.1.2.4Fixed bug that prevented characters from being read after reading a
Unicode escape sequence.Moved test cases intojsonlib2.testssubpackage.1.2.3Port to setuptools.Corrected false positive in detection of illegal leading zeroes.1.2.2Raise an exception if values in an object or array are not separated by
commas.1.2.1Support for building on Windows.1.2.0Addedsort_keysparameter towrite. This allows mapping types to
be serialized to a predictable value, regardless of key ordering.Addedindenttowrite. Any string passed as this value will be
used for indentation. If the value is notNone, pretty-printing will
be activated.1.1.0Support for reading astral Unicode codepoints on UCS2 builds of Python.1.0.0Initial release.