xoutil.json
- Encode and decode the JSON format¶
Extensions to the json standard library module.
It just adds the ability to encode/decode datetimes. But you should use the JSONEncoder yourself.
You may use this module as drop-in replacement to Python’s json. Also it contains definitions to use C library JSON speedups or Python replacements in case that library is not installed in your system.
-
xoutil.json.
dump
()[source]¶ Serialize
obj
as a JSON formatted stream tofp
(a.write()
-supporting file-like object).If
skipkeys
is true thendict
keys that are not basic types (str
,unicode
,int
,long
,float
,bool
,None
) will be skipped instead of raising aTypeError
.If
ensure_ascii
is true (the default), all non-ASCII characters in the output are escaped with\uXXXX
sequences, and the result is astr
instance consisting of ASCII characters only. Ifensure_ascii
isFalse
, some chunks written tofp
may beunicode
instances. This usually happens because the input contains unicode strings or theencoding
parameter is used. Unlessfp.write()
explicitly understandsunicode
(as incodecs.getwriter
) this is likely to cause an error.If
check_circular
is false, then the circular reference check for container types will be skipped and a circular reference will result in anOverflowError
(or worse).If
allow_nan
is false, then it will be aValueError
to serialize out of rangefloat
values (nan
,inf
,-inf
) in strict compliance of the JSON specification, instead of using the JavaScript equivalents (NaN
,Infinity
,-Infinity
).If
indent
is a non-negative integer, then JSON array elements and object members will be pretty-printed with that indent level. An indent level of 0 will only insert newlines.None
is the most compact representation. Since the default item separator is', '
, the output might include trailing whitespace whenindent
is specified. You can useseparators=(',', ': ')
to avoid this.If
separators
is an(item_separator, dict_separator)
tuple then it will be used instead of the default(', ', ': ')
separators.(',', ':')
is the most compact JSON representation.encoding
is the character encoding for str instances, default is UTF-8.default(obj)
is a function that should return a serializable version of obj or raise TypeError. The default simply raises TypeError.If sort_keys is
True
(default:False
), then the output of dictionaries will be sorted by key.To use a custom
JSONEncoder
subclass (e.g. one that overrides the.default()
method to serialize additional types), specify it with thecls
kwarg; otherwiseJSONEncoder
is used.
-
xoutil.json.
dumps
()[source]¶ Serialize
obj
to a JSON formattedstr
.If
skipkeys
is true thendict
keys that are not basic types (str
,unicode
,int
,long
,float
,bool
,None
) will be skipped instead of raising aTypeError
.If
ensure_ascii
is false, all non-ASCII characters are not escaped, and the return value may be aunicode
instance. Seedump
for details.If
check_circular
is false, then the circular reference check for container types will be skipped and a circular reference will result in anOverflowError
(or worse).If
allow_nan
is false, then it will be aValueError
to serialize out of rangefloat
values (nan
,inf
,-inf
) in strict compliance of the JSON specification, instead of using the JavaScript equivalents (NaN
,Infinity
,-Infinity
).If
indent
is a non-negative integer, then JSON array elements and object members will be pretty-printed with that indent level. An indent level of 0 will only insert newlines.None
is the most compact representation. Since the default item separator is', '
, the output might include trailing whitespace whenindent
is specified. You can useseparators=(',', ': ')
to avoid this.If
separators
is an(item_separator, dict_separator)
tuple then it will be used instead of the default(', ', ': ')
separators.(',', ':')
is the most compact JSON representation.encoding
is the character encoding for str instances, default is UTF-8.default(obj)
is a function that should return a serializable version of obj or raise TypeError. The default simply raises TypeError.If sort_keys is
True
(default:False
), then the output of dictionaries will be sorted by key.To use a custom
JSONEncoder
subclass (e.g. one that overrides the.default()
method to serialize additional types), specify it with thecls
kwarg; otherwiseJSONEncoder
is used.
-
xoutil.json.
load
()[source]¶ Deserialize
fp
(a.read()
-supporting file-like object containing a JSON document) to a Python object.If the contents of
fp
is encoded with an ASCII based encoding other than utf-8 (e.g. latin-1), then an appropriateencoding
name must be specified. Encodings that are not ASCII based (such as UCS-2) are not allowed, and should be wrapped withcodecs.getreader(fp)(encoding)
, or simply decoded to aunicode
object and passed toloads()
object_hook
is an optional function that will be called with the result of any object literal decode (adict
). The return value ofobject_hook
will be used instead of thedict
. This feature can be used to implement custom decoders (e.g. JSON-RPC class hinting).object_pairs_hook
is an optional function that will be called with the result of any object literal decoded with an ordered list of pairs. The return value ofobject_pairs_hook
will be used instead of thedict
. This feature can be used to implement custom decoders that rely on the order that the key and value pairs are decoded (for example, collections.OrderedDict will remember the order of insertion). Ifobject_hook
is also defined, theobject_pairs_hook
takes priority.To use a custom
JSONDecoder
subclass, specify it with thecls
kwarg; otherwiseJSONDecoder
is used.
-
xoutil.json.
loads
()[source]¶ Deserialize
s
(astr
orunicode
instance containing a JSON document) to a Python object.If
s
is astr
instance and is encoded with an ASCII based encoding other than utf-8 (e.g. latin-1) then an appropriateencoding
name must be specified. Encodings that are not ASCII based (such as UCS-2) are not allowed and should be decoded tounicode
first.object_hook
is an optional function that will be called with the result of any object literal decode (adict
). The return value ofobject_hook
will be used instead of thedict
. This feature can be used to implement custom decoders (e.g. JSON-RPC class hinting).object_pairs_hook
is an optional function that will be called with the result of any object literal decoded with an ordered list of pairs. The return value ofobject_pairs_hook
will be used instead of thedict
. This feature can be used to implement custom decoders that rely on the order that the key and value pairs are decoded (for example, collections.OrderedDict will remember the order of insertion). Ifobject_hook
is also defined, theobject_pairs_hook
takes priority.parse_float
, if specified, will be called with the string of every JSON float to be decoded. By default this is equivalent to float(num_str). This can be used to use another datatype or parser for JSON floats (e.g. decimal.Decimal).parse_int
, if specified, will be called with the string of every JSON int to be decoded. By default this is equivalent to int(num_str). This can be used to use another datatype or parser for JSON integers (e.g. float).parse_constant
, if specified, will be called with one of the following strings: -Infinity, Infinity, NaN, null, true, false. This can be used to raise an exception if invalid JSON numbers are encountered.To use a custom
JSONDecoder
subclass, specify it with thecls
kwarg; otherwiseJSONDecoder
is used.
-
class
xoutil.json.
JSONDecoder
[source]¶ Simple JSON <http://json.org> decoder
Performs the following translations in decoding by default:
JSON Python object dict array list string unicode number (int) int, long number (real) float true True false False null None It also understands
NaN
,Infinity
, and-Infinity
as their correspondingfloat
values, which is outside the JSON spec.
-
class
xoutil.json.
JSONEncoder
[source]¶ Extensible JSON <http://json.org> encoder for Python data structures.
Supports the following objects and types by default:
Python JSON dict object list, tuple array str, unicode string int, long, float number True true False false None null To extend this to recognize other objects, subclass and implement a
.default()
method with another method that returns a serializable object foro
if possible, otherwise it should call the superclass implementation (to raiseTypeError
).We also support:
- datetime, date and time values, which are translated to strings using ISO format.
- Decimal values, which are represented as a string representation.
- Iterables, which are represented as lists.