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) * RFC 4627. The application/json Media Type for JavaScript Object Notation (JSON) * ECMA-262 3rd edition (1999) * IEEE 754-1985: Standard for Binary Floating-Point Arithmetic. 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__ = | 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__ = | 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__ = | 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 ' __credits__ = 'Copyright (c) 2006-2011 Deron E. Meranda