Metadata-Version: 1.0
Name: jsonlib
Version: 1.3.6
Summary: JSON serializer/deserializer for Python
Home-page: https://launchpad.net/jsonlib
Author: John Millikin
Author-email: jmillikin@gmail.com
License: MIT
Download-URL: http://cheeseshop.python.org/pypi/jsonlib/1.3.6
Description: :Author: John Millikin
        :Copyright: This document has been placed in the public domain.
        
        Overview
        ========
        
        `JSON <http://json.org/>`_ is a lightweight data-interchange format. It
        is often used for exchanging data between a web server and user agent.
        
        This module aims to produce a library for serializing and deserializing
        JSON that conforms strictly to RFC 4627.
        
        .. contents::
        
        Usage
        =====
        
        jsonlib has two functions of interest, ``read`` and ``write``. It also
        defines some exception: ``ReadError``, ``WriteError``, and
        ``UnknownSerializerError``.
        
        Deserialization
        ---------------
        
        To deserialize a JSON expression, call the ``jsonlib.read`` function with
        an instance of ``str`` or ``unicode``. ::
        
        >>> import jsonlib
        >>> jsonlib.read ('["Hello world!"]')
        [u'Hello world!']
        
        Serialization
        -------------
        
        Serialization has more options, but they are set to reasonable defaults.
        The simplest use is to call ``jsonlib.write`` with a Python value. ::
        
        >>> import jsonlib
        >>> jsonlib.write (['Hello world!'])
        '["Hello world!"]'
        
        Pretty-Printing
        ~~~~~~~~~~~~~~~
        
        To "pretty-print" the output, pass a value for the ``indent`` parameter. ::
        
        >>> print jsonlib.write (['Hello world!'], indent = '    ')
        [
        "Hello world!"
        ]
        >>>
        
        Mapping Key Sorting
        ~~~~~~~~~~~~~~~~~~~
        
        By default, mapping keys are serialized in whatever order they are
        stored by Python. To force a consistent ordering (for example, in doctests)
        use the ``sort_keys`` parameter. ::
        
        >>> jsonlib.write ({'e': 'Hello', 'm': 'World!'})
        '{"m":"World!","e":"Hello"}'
        >>> jsonlib.write ({'e': 'Hello', 'm': 'World!'}, sort_keys = True)
        '{"e":"Hello","m":"World!"}'
        
        Encoding and Unicode
        ~~~~~~~~~~~~~~~~~~~~
        
        By default, the output is encoded in UTF-8. If you require a different
        encoding, pass the name of a Python codec as the ``encoding`` parameter. ::
        
        >>> jsonlib.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 unencoded ``unicode`` instance, pass ``None`` for the
        encoding. ::
        
        >>> jsonlib.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, set ``ascii_only`` to ``False``. ::
        
        >>> jsonlib.write ([u'Hello \u266a'], encoding = None)
        u'["Hello \\u266a"]'
        >>> jsonlib.write ([u'Hello \u266a'], encoding = None, ascii_only = False)
        u'["Hello \u266a"]'
        
        Mapping Key Coercion
        ~~~~~~~~~~~~~~~~~~~~
        
        Because JSON objects must have string keys, an exception will be raised when
        non-string keys are encountered in a mapping. It can be useful to coerce
        mapping keys to strings, so the ``coerce_keys`` parameter is available. ::
        
        >>> jsonlib.write ({True: 1})
        Traceback (most recent call last):
        WriteError: Only strings may be used as object keys.
        >>> jsonlib.write ({True: 1}, coerce_keys = True)
        '{"true":1}'
        
        Serializing Other Types
        ~~~~~~~~~~~~~~~~~~~~~~~
        
        If 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 from ``str``, ``unicode``, or
        ``UserString.UserString`` will 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 jsonlib, use the ``on_unknown`` parameter
        to ``write``::
        
        >>> from datetime import date
        >>> def unknown_handler (value):
        ...     if isinstance (value, date): return str (value)
        ...     raise jsonlib.UnknownSerializerError
        >>> jsonlib.write ([date (2000, 1, 1)], on_unknown = unknown_handler)
        '["2000-01-01"]'
        
        Streaming Serializer
        ~~~~~~~~~~~~~~~~~~~~
        
        When serializing large objects, the use of an in-memory buffer may cause
        too much memory to be used. For these situations, use the ``dump`` function
        to write objects to a file-like object::
        
        >>> import sys
        >>> jsonlib.dump (["Written to stdout"], sys.stdout)
        ["Written to stdout"]
        >>>
        
        Exceptions
        -----------
        
        ReadError
        ~~~~~~~~~
        
        Raised by ``read`` if an error was encountered parsing the expression. Will
        contain the line, column, and character position of the error.
        
        Note that this will report the *character*, not the *byte*, of the character
        that caused the error.
        
        WriteError
        ~~~~~~~~~~
        
        Raised by ``write`` or ``dump`` if an error was encountered serializing
        the passed value.
        
        UnknownSerializerError
        ~~~~~~~~~~~~~~~~~~~~~~
        
        A subclass of ``WriteError`` that is raised when a value cannot be
        serialized. See the ``on_unknown`` parameter to ``write``.
        
        Change Log
        ==========
        
        1.3.6
        -----
        * If 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 of ``UserString`` to be used as object keys.
        * Implemented the ``dump()`` function.
        
        1.3.5
        -----
        * Bugfix release, corrects serialization of ``dict`` when ``PyDict_Next()``
        skips indexes.
        
        1.3.4
        -----
        * Fixes an issue with reporting the column of a syntax error when the
        error is followed by a newline.
        * Removed remaining Python wrapper for ``read``.
        
        1.3.3
        -----
        * Support the ``on_unknown`` parameter to ``write``.
        * Corrected typo in invalid whitespace detection.
        * Added ``__version__`` attribute.
        * Merged all code into ``jsonlib`` and ``_jsonlib`` modules, instead of
        a package.
        
        1.3.2
        -----
        * Improved the README.
        * Support for reading text encoded with the ``utf-8-sig`` codec.
        * Use ``codecs`` module for detecting BOMs in input data.
        * Forbid non-whitespace strings from being used for indentation.
        
        1.3.1
        -----
        * Removed 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.0
        -----
        * Allow ``python setup.py test`` to work.
        * Added ``encoding`` parameter to ``write``, which controls the output
        encoding. The default encoding is ``utf-8``. If the encoding is ``None``,
        a ``unicode`` string will be returned.
        * Implemented ``write`` using a C extension module.
        
        1.2.7
        -----
        * Improved error messages when an error is encountered deserializing an
        expression.
        * Modified to work with Python 2.4.
        
        1.2.6
        -----
        
        Thanks to Deron Meranda (author of ``demjson``) for his excellent `JSON
        library comparison <http://deron.meranda.us/python/comparing_json_modules/>`_,
        which revealed many areas for improvement:
        
        * Use ``repr`` instead of ``unicode`` for 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:
        
        - ``generator``
        - ``set``
        - ``frozenset``
        - ``complex``, for values with no imaginary component.
        - ``array.array``
        - ``collections.deque``
        - ``collections.defaultdict``
        - ``UserList.UserList``
        - ``UserDict.UserDict``
        - ``UserString.UserString``
        
        * Raise 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 of ``Infinity`` and ``NaN`` on Windows.
        * Support for decoding UTF-32 on UCS2 builds of Python.
        * Faster detection of self-recursive containers.
        
        1.2.5
        -----
        * Return Unicode strings from ``write``, so the user can control the final
        encoding.
        * Prevent ``Infinity``, ``-Infinity``, and ``NaN`` from being serialized
        because JSON does not support these values.
        * Added ``coerce_keys`` parameter to ``write``. If ``True``, mapping keys
        will be coerced to strings. Defaults to ``False``.
        * Added ``ascii_only`` parameter to ``write``. If ``True``, non-ASCII
        codepoints will always be escaped to a \u sequence. Defaults to ``True``.
        * Real detection of self-recursive container types.
        * Escape the solidus to prevent against `security issues
        <http://t3.dotgnu.info/blog/insecurity/quotes-dont-help.html>`_.
        
        1.2.4
        -----
        * Fixed bug that prevented characters from being read after reading a
        Unicode escape sequence.
        * Moved test cases into ``jsonlib.tests`` subpackage.
        
        1.2.3
        -----
        * Port to setuptools.
        * Corrected false positive in detection of illegal leading zeroes.
        
        1.2.2
        -----
        * Raise an exception if values in an object or array are not separated by
        commas.
        
        1.2.1
        -----
        * Support for building on Windows.
        
        1.2.0
        -----
        * Added ``sort_keys`` parameter to ``write``. This allows mapping types to
        be serialized to a predictable value, regardless of key ordering.
        * Added ``indent`` to ``write``. Any string passed as this value will be
        used for indentation. If the value is not `None`, pretty-printing will
        be activated.
        
        1.1.0
        -----
        * Support for reading astral Unicode codepoints on UCS2 builds of Python.
        
        1.0.0
        -----
        * Initial release.
        
Keywords: json
Platform: Platform Independent
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Topic :: Software Development :: Libraries :: Python Modules
