demjson (version 1.6, 2011-04-01)
index
demjson.py

JSON data encoder and decoder.
 
This Python module implements the JSON (http://json.org/) data
encoding format; a subset of ECMAScript (aka JavaScript) for encoding
primitive data types (numbers, strings, booleans, lists, and
associative arrays) in a language-neutral simple text-based syntax.
 
It can encode or decode between JSON formatted strings and native
Python data types.  Normally you would use the encode() and decode()
functions defined by this module, but if you want more control over
the processing you can use the JSON class.
 
This implementation tries to be as completely cormforming to all
intricacies of the standards as possible.  It can operate in strict
mode (which only allows JSON-compliant syntax) or a non-strict mode
(which allows much more of the whole ECMAScript permitted syntax).
This includes complete support for Unicode strings (including
surrogate-pairs for non-BMP characters), and all number formats
including negative zero and IEEE 754 non-numbers such a NaN or
Infinity.
 
The JSON/ECMAScript to Python type mappings are:
   ---JSON---             ---Python---
   null                   None
   undefined              undefined  (note 1)
   Boolean (true,false)   bool  (True or False)
   Integer                int or long  (note 2)
   Float                  float
   String                 str or unicode  ( "..." or u"..." )
   Array [a, ...]         list  ( [...] )
   Object {a:b, ...}      dict  ( {...} )
   
   -- Note 1. an 'undefined' object is declared in this module which
      represents the native Python value for this type when in
      non-strict mode.
 
   -- Note 2. some ECMAScript integers may be up-converted to Python
      floats, such as 1e+40.  Also integer -0 is converted to
      float -0, so as to preserve the sign (which ECMAScript requires).
 
In addition, when operating in non-strict mode, several IEEE 754
non-numbers are also handled, and are mapped to specific Python
objects declared in this module:
 
    NaN (not a number)     nan    (float('nan'))
    Infinity, +Infinity    inf    (float('inf'))
    -Infinity              neginf (float('-inf'))
 
When encoding Python objects into JSON, you may use types other than
native lists or dictionaries, as long as they support the minimal
interfaces required of all sequences or mappings.  This means you can
use generators and iterators, tuples, UserDict subclasses, etc.
 
To make it easier to produce JSON encoded representations of user
defined classes, if the object has a method named json_equivalent(),
then it will call that method and attempt to encode the object
returned from it instead.  It will do this recursively as needed and
before any attempt to encode the object using it's default
strategies.  Note that any json_equivalent() method should return
"equivalent" Python objects to be encoded, not an already-encoded
JSON-formatted string.  There is no such aid provided to decode
JSON back into user-defined classes as that would dramatically
complicate the interface.
 
When decoding strings with this module it may operate in either
strict or non-strict mode.  The strict mode only allows syntax which
is conforming to RFC 4627 (JSON), while the non-strict allows much
more of the permissible ECMAScript syntax.
 
The following are permitted when processing in NON-STRICT mode:
 
   * Unicode format control characters are allowed anywhere in the input.
   * All Unicode line terminator characters are recognized.
   * All Unicode white space characters are recognized.
   * The 'undefined' keyword is recognized.
   * Hexadecimal number literals are recognized (e.g., 0xA6, 0177).
   * String literals may use either single or double quote marks.
   * Strings may contain \x (hexadecimal) escape sequences, as well as the
     \v and \0 escape sequences.
   * Lists may have omitted (elided) elements, e.g., [,,,,,], with
     missing elements interpreted as 'undefined' values.
   * Object properties (dictionary keys) can be of any of the
     types: string literals, numbers, or identifiers (the later of
     which are treated as if they are string literals)---as permitted
     by ECMAScript.  JSON only permits strings literals as keys.
 
Concerning non-strict and non-ECMAScript allowances:
 
   * Octal numbers: If you allow the 'octal_numbers' behavior (which
     is never enabled by default), then you can use octal integers
     and octal character escape sequences (per the ECMAScript
     standard Annex B.1.2).  This behavior is allowed, if enabled,
     because it was valid JavaScript at one time.
 
   * Multi-line string literals:  Strings which are more than one
     line long (contain embedded raw newline characters) are never
     permitted. This is neither valid JSON nor ECMAScript.  Some other
     JSON implementations may allow this, but this module considers
     that behavior to be a mistake.
 
References:
   * JSON (JavaScript Object Notation)
     <http://json.org/>
   * RFC 4627. The application/json Media Type for JavaScript Object Notation (JSON)
     <http://www.ietf.org/rfc/rfc4627.txt>
   * ECMA-262 3rd edition (1999)
     <http://www.ecma-international.org/publications/files/ecma-st/ECMA-262.pdf>
   * IEEE 754-1985: Standard for Binary Floating-Point Arithmetic.
     <http://www.cs.berkeley.edu/~ejr/Projects/ieee754/>

 
Modules
       
decimal

 
Classes
       
__builtin__.object
JSON
exceptions.ValueError(exceptions.StandardError)
JSONError
JSONDecodeError
JSONEncodeError

 
class JSON(__builtin__.object)
    An encoder/decoder for JSON data streams.
 
Usually you will call the encode() or decode() methods.  The other
methods are for lower-level processing.
 
Whether the JSON parser runs in strict mode (which enforces exact
compliance with the JSON spec) or the more forgiving non-string mode
can be affected by setting the 'strict' argument in the object's
initialization; or by assigning True or False to the 'strict'
property of the object.
 
You can also adjust a finer-grained control over strictness by
allowing or preventing specific behaviors.  You can get a list of
all the available behaviors by accessing the 'behaviors' property.
Likewise the allowed_behaviors and prevented_behaviors list which
behaviors will be allowed and which will not.  Call the allow()
or prevent() methods to adjust these.
 
  Methods defined here:
__init__(self, strict=False, compactly=True, escape_unicode=False)
Creates a JSON encoder/decoder object.
 
If 'strict' is set to True, then only strictly-conforming JSON
output will be produced.  Note that this means that some types
of values may not be convertable and will result in a
JSONEncodeError exception.
 
If 'compactly' is set to True, then the resulting string will
have all extraneous white space removed; if False then the
string will be "pretty printed" with whitespace and indentation
added to make it more readable.
 
If 'escape_unicode' is set to True, then all non-ASCII characters
will be represented as a unicode escape sequence; if False then
the actual real unicode character will be inserted if possible.
 
The 'escape_unicode' can also be a function, which when called
with a single argument of a unicode character will return True
if the character should be escaped or False if it should not.
 
If you wish to extend the encoding to ba able to handle
additional types, you should subclass this class and override
the encode_default() method.
allow(self, behavior)
Allow the specified behavior (turn off a strictness check).
 
The list of all possible behaviors is available in the behaviors property.
You can see which behaviors are currently allowed by accessing the
allowed_behaviors property.
decode(self, txt)
Decodes a JSON-endoded string into a Python object.
decode_boolean(self, s, i=0)
Intermediate-level decode for JSON boolean literals.
 
Takes a string and a starting index, and returns a Python bool
(True or False) and the index of the next unparsed character.
decode_composite(self, txt, i=0, imax=None)
Intermediate-level JSON decoder for composite literal types (array and object).
 
Takes text and a starting index, and returns either a Python list or
dictionary and the index of the next unparsed character.
decode_javascript_identifier(self, name)
Convert a JavaScript identifier into a Python string object.
 
This method can be overriden by a subclass to redefine how JavaScript
identifiers are turned into Python objects.  By default this just
converts them into strings.
decode_null(self, s, i=0)
Intermediate-level decoder for ECMAScript 'null' keyword.
 
Takes a string and a starting index, and returns a Python
None object and the index of the next unparsed character.
decode_number(self, s, i=0, imax=None)
Intermediate-level decoder for JSON numeric literals.
 
Takes a string and a starting index, and returns a Python
suitable numeric type and the index of the next unparsed character.
 
The returned numeric type can be either of a Python int,
long, or float.  In addition some special non-numbers may
also be returned such as nan, inf, and neginf (technically
which are Python floats, but have no numeric value.)
 
Ref. ECMAScript section 8.5.
decode_string(self, s, i=0, imax=None)
Intermediate-level decoder for JSON string literals.
 
Takes a string and a starting index, and returns a Python
string (or unicode string) and the index of the next unparsed
character.
decodeobj(self, txt, i=0, imax=None, identifier_as_string=False, only_object_or_array=False)
Intermediate-level JSON decoder.
 
Takes a string and a starting index, and returns a two-tuple consting
of a Python object and the index of the next unparsed character.
 
If there is no value at all (empty string, etc), the None is
returned instead of a tuple.
encode(self, obj, nest_level=0)
Encodes the Python object into a JSON string representation.
 
This method will first attempt to encode an object by seeing
if it has a json_equivalent() method.  If so than it will
call that method and then recursively attempt to encode
the object resulting from that call.
 
Next it will attempt to determine if the object is a native
type or acts like a squence or dictionary.  If so it will
encode that object directly.
 
Finally, if no other strategy for encoding the object of that
type exists, it will call the encode_default() method.  That
method currently raises an error, but it could be overridden
by subclasses to provide a hook for extending the types which
can be encoded.
encode_boolean(self, b)
Encodes the Python boolean into a JSON Boolean literal.
encode_composite(self, chunklist, obj, nest_level)
Encodes just dictionaries, lists, or sequences.
 
Basically handles any python type for which iter() can create
an iterator object.
 
This method is not intended to be called directly.  Use the
encode() method instead.
encode_default(self, obj, nest_level=0)
This method is used to encode objects into JSON which are not straightforward.
 
This method is intended to be overridden by subclasses which wish
to extend this encoder to handle additional types.
encode_equivalent(self, obj, nest_level=0)
This method is used to encode user-defined class objects.
 
The object being encoded should have a json_equivalent()
method defined which returns another equivalent object which
is easily JSON-encoded.  If the object in question has no
json_equivalent() method available then None is returned
instead of a string so that the encoding will attempt the next
strategy.
 
If a caller wishes to disable the calling of json_equivalent()
methods, then subclass this class and override this method
to just return None.
encode_helper(self, chunklist, obj, nest_level)
encode_null(self)
Produces the JSON 'null' keyword.
encode_number(self, n)
Encodes a Python numeric type into a JSON numeric literal.
 
The special non-numeric values of float('nan'), float('inf')
and float('-inf') are translated into appropriate JSON
literals.
 
Note that Python complex types are not handled, as there is no
ECMAScript equivalent type.
encode_string(self, s)
Encodes a Python string into a JSON string literal.
encode_undefined(self)
Produces the ECMAScript 'undefined' keyword.
islineterm(self, c)
Determines if the given character is considered a line terminator.
 
Ref. ECMAScript section 7.3
isws(self, c)
Determines if the given character is considered as white space.
 
Note that Javscript is much more permissive on what it considers
to be whitespace than does JSON.
 
Ref. ECMAScript section 7.2
prevent(self, behavior)
Prevent the specified behavior (turn on a strictness check).
 
The list of all possible behaviors is available in the behaviors property.
You can see which behaviors are currently prevented by accessing the
prevented_behaviors property.
skip_comment(self, txt, i=0)
Skips an ECMAScript comment, either // or /* style.
 
The contents of the comment are returned as a string, as well
as the index of the character immediately after the comment.
skipws(self, txt, i=0, imax=None, skip_comments=True)
Skips whitespace.
skipws_any(self, txt, i=0, imax=None, skip_comments=True)
Skips all whitespace, including comments and unicode whitespace
 
Takes a string and a starting index, and returns the index of the
next non-whitespace character.
 
If skip_comments is True and not running in strict JSON mode, then
comments will be skipped over just like whitespace.
strip_format_control_chars(self, txt)
Filters out all Unicode format control characters from the string.
 
ECMAScript permits any Unicode "format control characters" to
appear at any place in the source code.  They are to be
ignored as if they are not there before any other lexical
tokenization occurs.  Note that JSON does not allow them.
 
Ref. ECMAScript section 7.1.

Data descriptors defined here:
__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)
allowed_behaviors
List of known behaviors that are currently allowed
behaviors
List of known behaviors that can be passed to allow() or prevent() methods
prevented_behaviors
List of known behaviors that are currently prevented
strict
True if adherence to RFC 4627 syntax is strict, or False is more generous ECMAScript syntax is permitted

 
class JSONDecodeError(JSONError)
    An exception class raised when a JSON decoding error (syntax error) occurs.
 
 
Method resolution order:
JSONDecodeError
JSONError
exceptions.ValueError
exceptions.StandardError
exceptions.Exception
exceptions.BaseException
__builtin__.object

Methods inherited from JSONError:
pretty_description(self)

Data descriptors inherited from JSONError:
__weakref__
list of weak references to the object (if defined)

Methods inherited from exceptions.ValueError:
__init__(...)
x.__init__(...) initializes x; see x.__class__.__doc__ for signature

Data and other attributes inherited from exceptions.ValueError:
__new__ = <built-in method __new__ of type object>
T.__new__(S, ...) -> a new object with type S, a subtype of T

Methods inherited from exceptions.BaseException:
__delattr__(...)
x.__delattr__('name') <==> del x.name
__getattribute__(...)
x.__getattribute__('name') <==> x.name
__getitem__(...)
x.__getitem__(y) <==> x[y]
__getslice__(...)
x.__getslice__(i, j) <==> x[i:j]
 
Use of negative indices is not supported.
__reduce__(...)
__repr__(...)
x.__repr__() <==> repr(x)
__setattr__(...)
x.__setattr__('name', value) <==> x.name = value
__setstate__(...)
__str__(...)
x.__str__() <==> str(x)
__unicode__(...)

Data descriptors inherited from exceptions.BaseException:
__dict__
args
message

 
class JSONEncodeError(JSONError)
    An exception class raised when a python object can not be encoded as a JSON string.
 
 
Method resolution order:
JSONEncodeError
JSONError
exceptions.ValueError
exceptions.StandardError
exceptions.Exception
exceptions.BaseException
__builtin__.object

Methods inherited from JSONError:
pretty_description(self)

Data descriptors inherited from JSONError:
__weakref__
list of weak references to the object (if defined)

Methods inherited from exceptions.ValueError:
__init__(...)
x.__init__(...) initializes x; see x.__class__.__doc__ for signature

Data and other attributes inherited from exceptions.ValueError:
__new__ = <built-in method __new__ of type object>
T.__new__(S, ...) -> a new object with type S, a subtype of T

Methods inherited from exceptions.BaseException:
__delattr__(...)
x.__delattr__('name') <==> del x.name
__getattribute__(...)
x.__getattribute__('name') <==> x.name
__getitem__(...)
x.__getitem__(y) <==> x[y]
__getslice__(...)
x.__getslice__(i, j) <==> x[i:j]
 
Use of negative indices is not supported.
__reduce__(...)
__repr__(...)
x.__repr__() <==> repr(x)
__setattr__(...)
x.__setattr__('name', value) <==> x.name = value
__setstate__(...)
__str__(...)
x.__str__() <==> str(x)
__unicode__(...)

Data descriptors inherited from exceptions.BaseException:
__dict__
args
message

 
class JSONError(exceptions.ValueError)
    Our base class for all JSON-related errors.
 
 
Method resolution order:
JSONError
exceptions.ValueError
exceptions.StandardError
exceptions.Exception
exceptions.BaseException
__builtin__.object

Methods defined here:
pretty_description(self)

Data descriptors defined here:
__weakref__
list of weak references to the object (if defined)

Methods inherited from exceptions.ValueError:
__init__(...)
x.__init__(...) initializes x; see x.__class__.__doc__ for signature

Data and other attributes inherited from exceptions.ValueError:
__new__ = <built-in method __new__ of type object>
T.__new__(S, ...) -> a new object with type S, a subtype of T

Methods inherited from exceptions.BaseException:
__delattr__(...)
x.__delattr__('name') <==> del x.name
__getattribute__(...)
x.__getattribute__('name') <==> x.name
__getitem__(...)
x.__getitem__(y) <==> x[y]
__getslice__(...)
x.__getslice__(i, j) <==> x[i:j]
 
Use of negative indices is not supported.
__reduce__(...)
__repr__(...)
x.__repr__() <==> repr(x)
__setattr__(...)
x.__setattr__('name', value) <==> x.name = value
__setstate__(...)
__str__(...)
x.__str__() <==> str(x)
__unicode__(...)

Data descriptors inherited from exceptions.BaseException:
__dict__
args
message

 
Functions
       
auto_unicode_decode(s)
Takes a string and tries to convert it to a Unicode string.
 
This will return a Python unicode string type corresponding to the
input string (either str or unicode).  The character encoding is
guessed by looking for either a Unicode BOM prefix, or by the
rules specified by RFC 4627.  When in doubt it is assumed the
input is encoded in UTF-8 (the default for JSON).
decode(txt, strict=False, encoding=None, **kw)
Decodes a JSON-encoded string into a Python object.
 
If 'strict' is set to True, then those strings that are not
entirely strictly conforming to JSON will result in a
JSONDecodeError exception.
 
The input string can be either a python string or a python unicode
string.  If it is already a unicode string, then it is assumed
that no character set decoding is required.
 
However, if you pass in a non-Unicode text string (i.e., a python
type 'str') then an attempt will be made to auto-detect and decode
the character encoding.  This will be successful if the input was
encoded in any of UTF-8, UTF-16 (BE or LE), or UTF-32 (BE or LE),
and of course plain ASCII works too.
 
Note though that if you know the character encoding, then you
should convert to a unicode string yourself, or pass it the name
of the 'encoding' to avoid the guessing made by the auto
detection, as with
 
    python_object = demjson.decode( input_bytes, encoding='utf8' )
 
Optional keywords arguments must be of the form
    allow_xxxx=True/False
or
    prevent_xxxx=True/False
where each will allow or prevent the specific behavior, after the
evaluation of the 'strict' argument.  For example, if strict=True
then by also passing 'allow_comments=True' then comments will be
allowed.  If strict=False then prevent_comments=True will allow
everything except comments.
decode_hex(hexstring)
Decodes a hexadecimal string into it's integer value.
decode_octal(octalstring)
Decodes an octal string into it's integer value.
determine_float_precision()
Returns a tuple (significant_digits, max_exponent) for the float type.
encode(obj, strict=False, compactly=True, escape_unicode=False, encoding=None)
Encodes a Python object into a JSON-encoded string.
 
If 'strict' is set to True, then only strictly-conforming JSON
output will be produced.  Note that this means that some types
of values may not be convertable and will result in a
JSONEncodeError exception.
 
If 'compactly' is set to True, then the resulting string will
have all extraneous white space removed; if False then the
string will be "pretty printed" with whitespace and indentation
added to make it more readable.
 
If 'escape_unicode' is set to True, then all non-ASCII characters
will be represented as a unicode escape sequence; if False then
the actual real unicode character will be inserted.
 
If no encoding is specified (encoding=None) then the output will
either be a Python string (if entirely ASCII) or a Python unicode
string type.
 
However if an encoding name is given then the returned value will
be a python string which is the byte sequence encoding the JSON
value.  As the default/recommended encoding for JSON is UTF-8,
you should almost always pass in encoding='utf8'.
extend_and_flatten_list_with_sep(orig_seq, extension_seq, separator='')
extend_list_with_sep(orig_seq, extension_seq, sepchar='')
isnumbertype(obj)
Is the object of a Python number type (excluding complex)?
isstringtype(obj)
Is the object of a Python string type?
skipstringsafe(s, start=0, end=None)
skipstringsafe_slow(s, start=0, end=None)
surrogate_pair_as_unicode(c1, c2)
Takes a pair of unicode surrogates and returns the equivalent unicode character.
 
The input pair must be a surrogate pair, with c1 in the range
U+D800 to U+DBFF and c2 in the range U+DC00 to U+DFFF.
unicode_as_surrogate_pair(c)
Takes a single unicode character and returns a sequence of surrogate pairs.
 
The output of this function is a tuple consisting of one or two unicode
characters, such that if the input character is outside the BMP range
then the output is a two-character surrogate pair representing that character.
 
If the input character is inside the BMP then the output tuple will have
just a single character...the same one.
utf32be_decode(obj, errors='strict')
Decodes a UTF-32BE byte string into a Unicode string.
utf32be_encode(obj, errors='strict')
Encodes a Unicode string into a UTF-32BE encoded byte string.
utf32le_decode(obj, errors='strict')
Decodes a UTF-32LE byte string into a Unicode string.
utf32le_encode(obj, errors='strict')
Encodes a Unicode string into a UTF-32LE encoded byte string.

 
Data
        __author__ = 'Deron Meranda <http://deron.meranda.us/>'
__credits__ = 'Copyright (c) 2006-2011 Deron E. Meranda <http:/.../licenses/>\nor <http://www.fsf.org/licensing/>.\n\n'
__date__ = '2011-04-01'
__version__ = '1.6'
content_type = 'application/json'
file_ext = 'json'
float_maxexp = 307
float_sigdigits = 14
hexdigits = '0123456789ABCDEFabcdef'
i = 31
inf = inf
nan = nan
neginf = -inf
octaldigits = '01234567'
undefined = demjson.undefined
unsafe_string_chars = '"\\\x00\x01\x02\x03\x04\x05\x06\x07\x08\t\n\x0b\x0c\r\x0e\x0f\x10\x11\x12\x13\x14\x15\x16\x17\x18\x19\x1a\x1b\x1c\x1d\x1e\x1f'

 
Author
        Deron Meranda <http://deron.meranda.us/>

 
Credits
        Copyright (c) 2006-2011 Deron E. Meranda <http://deron.meranda.us/>
 
Licensed under GNU LGPL (GNU Lesser General Public License) version 3.0
or later.  See LICENSE.txt included with this software.
 
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Lesser General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.
 
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.
 
You should have received a copy of the GNU Lesser General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>
or <http://www.fsf.org/licensing/>.