Help on module demjson:

NAME
    demjson - A JSON data encoder and decoder.

FILE
    demjson.py

DESCRIPTION
    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/>

CLASSES
    exceptions.ValueError(exceptions.StandardError)
        JSONError
            JSONDecodeError
            JSONEncodeError
    __builtin__.object
        JSON
    
    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.
     |  
     |  ----------------------------------------------------------------------
     |  Properties defined here:
     |  
     |  allowed_behaviors
     |      List of known behaviors that are currently allowed
     |  
     |      <get> = _get_allowed_behaviors(self)
     |  
     |  behaviors
     |      List of known behaviors that can be passed to allow() or prevent() methods
     |  
     |      <get> = _get_behaviors(self)
     |  
     |  prevented_behaviors
     |      List of known behaviors that are currently prevented
     |  
     |      <get> = _get_prevented_behaviors(self)
     |  
     |  strict
     |      True if adherence to RFC 4627 syntax is strict, or False is more generous ECMAScript syntax is permitted
     |  
     |      <get> = _is_strict(self)
     |  
     |      <set> = _set_strictness(self, strict)
     |          Changes the strictness behavior.
     |          
     |          Pass True to be very strict about JSON syntax, or False to be looser.
     |  
     |  ----------------------------------------------------------------------
     |  Data and other attributes defined here:
     |  
     |  __dict__ = <dictproxy object>
     |      dictionary for instance variables (if defined)
     |  
     |  __weakref__ = <attribute '__weakref__' of 'JSON' objects>
     |      list of weak references to the object (if defined)
    
    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
     |  
     |  Methods inherited from JSONError:
     |  
     |  pretty_description(self)
     |  
     |  ----------------------------------------------------------------------
     |  Methods inherited from exceptions.Exception:
     |  
     |  __getitem__(...)
     |  
     |  __init__(...)
     |  
     |  __str__(...)
    
    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
     |  
     |  Methods inherited from JSONError:
     |  
     |  pretty_description(self)
     |  
     |  ----------------------------------------------------------------------
     |  Methods inherited from exceptions.Exception:
     |  
     |  __getitem__(...)
     |  
     |  __init__(...)
     |  
     |  __str__(...)
    
    class JSONError(exceptions.ValueError)
     |  Our base class for all JSON-related errors.
     |  
     |  Method resolution order:
     |      JSONError
     |      exceptions.ValueError
     |      exceptions.StandardError
     |      exceptions.Exception
     |  
     |  Methods defined here:
     |  
     |  pretty_description(self)
     |  
     |  ----------------------------------------------------------------------
     |  Methods inherited from exceptions.Exception:
     |  
     |  __getitem__(...)
     |  
     |  __init__(...)
     |  
     |  __str__(...)

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-2008 Deron E. Meranda <http:/.../lic...
    __date__ = '2008-12-17'
    __version__ = '1.4'
    content_type = 'application/json'
    decimal = None
    file_ext = 'json'
    float_maxexp = 307
    float_sigdigits = 15
    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...

VERSION
    1.4

DATE
    2008-12-17

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

CREDITS
    Copyright (c) 2006-2008 Deron E. Meranda <http://deron.meranda.us/>
    Licensed under GNU LGPL 3.0 (GNU Lesser General Public License) 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/>.


