EVOLUTION-MANAGER

Edit File: index.html

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
 <head>
 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
 
 <title>simplejson — JSON encoder and decoder &mdash; simplejson 3.10.0 documentation</title>
 
 <link rel="stylesheet" href="_static/default.css" type="text/css" />
 <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
 
 <script type="text/javascript">
 var DOCUMENTATION_OPTIONS = {
 URL_ROOT: '',
 VERSION: '3.10.0',
 COLLAPSE_INDEX: false,
 FILE_SUFFIX: '.html',
 HAS_SOURCE: true
 };
 </script>
 <script type="text/javascript" src="_static/jquery.js"></script>
 <script type="text/javascript" src="_static/underscore.js"></script>
 <script type="text/javascript" src="_static/doctools.js"></script>
 <link rel="top" title="simplejson 3.10.0 documentation" href="#" /> 
 </head>
 <body>
 <div class="related">
 <h3>Navigation</h3>
 <ul>
 <li class="right" style="margin-right: 10px">
 <a href="genindex.html" title="General Index"
 accesskey="I">index</a></li>
 <li><a href="#">simplejson 3.10.0 documentation</a> &raquo;</li> 
 </ul>
 </div>

<div class="document">
 <div class="documentwrapper">
 <div class="bodywrapper">
 <div class="body">
 
 <div class="section" id="module-simplejson">
<h1><a class="reference internal" href="#module-simplejson" title="simplejson: Encode and decode the JSON format."><tt class="xref py py-mod docutils literal">simplejson</tt></a> &#8212; JSON encoder and decoder<a class="headerlink" href="#module-simplejson" title="Permalink to this headline">¶</a></h1>
<a class="reference external" href="http://json.org">JSON (JavaScript Object Notation)</a>, specified by
<a class="rfc reference external" href="http://tools.ietf.org/html/rfc7159.html">RFC 7159</a> (which obsoletes <a class="rfc reference external" href="http://tools.ietf.org/html/rfc4627.html">RFC 4627</a>) and by
<a class="reference external" href="http://www.ecma-international.org/publications/standards/Ecma-404.htm">ECMA-404</a>,
is a lightweight data interchange format inspired by
<a class="reference external" href="http://en.wikipedia.org/wiki/JavaScript">JavaScript</a> object literal syntax
(although it is not a strict subset of JavaScript <a class="footnote-reference" href="#rfc-errata" id="id1">[1]</a> ).
<a class="reference internal" href="#module-simplejson" title="simplejson: Encode and decode the JSON format."><tt class="xref py py-mod docutils literal">simplejson</tt></a> exposes an API familiar to users of the standard library
<tt class="xref py py-mod docutils literal">marshal</tt> and <tt class="xref py py-mod docutils literal">pickle</tt> modules. It is the externally maintained
version of the <tt class="xref py py-mod docutils literal">json</tt> library contained in Python 2.6, but maintains
compatibility with Python 2.5 and (currently) has
significant performance advantages, even without using the optional C
extension for speedups. <a class="reference internal" href="#module-simplejson" title="simplejson: Encode and decode the JSON format."><tt class="xref py py-mod docutils literal">simplejson</tt></a> is also supported on Python 3.3+.
Development of simplejson happens on Github:
<a class="reference external" href="http://github.com/simplejson/simplejson">http://github.com/simplejson/simplejson</a>
Encoding basic Python object hierarchies:
<div class="highlight-python"><div class="highlight"><pre>&gt;&gt;&gt; import simplejson as json
&gt;&gt;&gt; json.dumps([&#39;foo&#39;, {&#39;bar&#39;: (&#39;baz&#39;, None, 1.0, 2)}])
&#39;[&quot;foo&quot;, {&quot;bar&quot;: [&quot;baz&quot;, null, 1.0, 2]}]&#39;
&gt;&gt;&gt; print(json.dumps(&quot;\&quot;foo\bar&quot;))
&quot;\&quot;foo\bar&quot;
&gt;&gt;&gt; print(json.dumps(u&#39;\u1234&#39;))
&quot;\u1234&quot;
&gt;&gt;&gt; print(json.dumps(&#39;\\&#39;))
&quot;\\&quot;
&gt;&gt;&gt; print(json.dumps({&quot;c&quot;: 0, &quot;b&quot;: 0, &quot;a&quot;: 0}, sort_keys=True))
{&quot;a&quot;: 0, &quot;b&quot;: 0, &quot;c&quot;: 0}
&gt;&gt;&gt; from simplejson.compat import StringIO
&gt;&gt;&gt; io = StringIO()
&gt;&gt;&gt; json.dump([&#39;streaming API&#39;], io)
&gt;&gt;&gt; io.getvalue()
&#39;[&quot;streaming API&quot;]&#39;
</pre></div>
</div>
Compact encoding:
<div class="highlight-python"><div class="highlight"><pre>&gt;&gt;&gt; import simplejson as json
&gt;&gt;&gt; obj = [1,2,3,{&#39;4&#39;: 5, &#39;6&#39;: 7}]
&gt;&gt;&gt; json.dumps(obj, separators=(&#39;,&#39;, &#39;:&#39;), sort_keys=True)
&#39;[1,2,3,{&quot;4&quot;:5,&quot;6&quot;:7}]&#39;
</pre></div>
</div>
Pretty printing:
<div class="highlight-python"><div class="highlight"><pre>&gt;&gt;&gt; import simplejson as json
&gt;&gt;&gt; print(json.dumps({&#39;4&#39;: 5, &#39;6&#39;: 7}, sort_keys=True, indent=4 * &#39; &#39;))
{
 &quot;4&quot;: 5,
 &quot;6&quot;: 7
}
</pre></div>
</div>
Decoding JSON:
<div class="highlight-python"><div class="highlight"><pre>&gt;&gt;&gt; import simplejson as json
&gt;&gt;&gt; obj = [u&#39;foo&#39;, {u&#39;bar&#39;: [u&#39;baz&#39;, None, 1.0, 2]}]
&gt;&gt;&gt; json.loads(&#39;[&quot;foo&quot;, {&quot;bar&quot;:[&quot;baz&quot;, null, 1.0, 2]}]&#39;) == obj
True
&gt;&gt;&gt; json.loads(&#39;&quot;\\&quot;foo\\bar&quot;&#39;) == u&#39;&quot;foo\x08ar&#39;
True
&gt;&gt;&gt; from simplejson.compat import StringIO
&gt;&gt;&gt; io = StringIO(&#39;[&quot;streaming API&quot;]&#39;)
&gt;&gt;&gt; json.load(io)[0] == &#39;streaming API&#39;
True
</pre></div>
</div>
Using Decimal instead of float:
<div class="highlight-python"><div class="highlight"><pre>&gt;&gt;&gt; import simplejson as json
&gt;&gt;&gt; from decimal import Decimal
&gt;&gt;&gt; json.loads(&#39;1.1&#39;, use_decimal=True) == Decimal(&#39;1.1&#39;)
True
&gt;&gt;&gt; json.dumps(Decimal(&#39;1.1&#39;), use_decimal=True) == &#39;1.1&#39;
True
</pre></div>
</div>
Specializing JSON object decoding:
<div class="highlight-python"><div class="highlight"><pre>&gt;&gt;&gt; import simplejson as json
&gt;&gt;&gt; def as_complex(dct):
... if &#39;__complex__&#39; in dct:
... return complex(dct[&#39;real&#39;], dct[&#39;imag&#39;])
... return dct
...
&gt;&gt;&gt; json.loads(&#39;{&quot;__complex__&quot;: true, &quot;real&quot;: 1, &quot;imag&quot;: 2}&#39;,
... object_hook=as_complex)
(1+2j)
&gt;&gt;&gt; import decimal
&gt;&gt;&gt; json.loads(&#39;1.1&#39;, parse_float=decimal.Decimal) == decimal.Decimal(&#39;1.1&#39;)
True
</pre></div>
</div>
Specializing JSON object encoding:
<div class="highlight-python"><div class="highlight"><pre>&gt;&gt;&gt; import simplejson as json
&gt;&gt;&gt; def encode_complex(obj):
... if isinstance(obj, complex):
... return [obj.real, obj.imag]
... raise TypeError(repr(obj) + &quot; is not JSON serializable&quot;)
...
&gt;&gt;&gt; json.dumps(2 + 1j, default=encode_complex)
&#39;[2.0, 1.0]&#39;
&gt;&gt;&gt; json.JSONEncoder(default=encode_complex).encode(2 + 1j)
&#39;[2.0, 1.0]&#39;
&gt;&gt;&gt; &#39;&#39;.join(json.JSONEncoder(default=encode_complex).iterencode(2 + 1j))
&#39;[2.0, 1.0]&#39;
</pre></div>
</div>
Using <tt class="xref py py-mod docutils literal">simplejson.tool</tt> from the shell to validate and pretty-print:
<div class="highlight-bash"><div class="highlight"><pre>$ echo &#39;{&quot;json&quot;:&quot;obj&quot;}&#39; | python -m simplejson.tool
{
 &quot;json&quot;: &quot;obj&quot;
}
$ echo &#39;{ 1.2:3.4}&#39; | python -m simplejson.tool
Expecting property name enclosed in double quotes: line 1 column 3 (char 2)
</pre></div>
</div>
<div class="admonition note">
Note
JSON is a subset of <a class="reference external" href="http://yaml.org/">YAML</a> 1.2. The JSON produced by
this module&#8217;s default settings (in particular, the default separators
value) is also a subset of YAML 1.0 and 1.1. This module can thus also be
used as a YAML serializer.
</div>
<div class="section" id="basic-usage">
<h2>Basic Usage<a class="headerlink" href="#basic-usage" title="Permalink to this headline">¶</a></h2>
<dl class="function">
<dt id="simplejson.dump">
<tt class="descclassname">simplejson.</tt><tt class="descname">dump</tt><big>(</big>obj, fp, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, cls=None, indent=None, separators=None, encoding='utf-8', default=None, use_decimal=True, namedtuple_as_object=True, tuple_as_array=True, bigint_as_string=False, sort_keys=False, item_sort_key=None, for_json=None, ignore_nan=False, int_as_string_bitcount=None, iterable_as_array=False, **kw<big>)</big><a class="headerlink" href="#simplejson.dump" title="Permalink to this definition">¶</a></dt>
<dd><blockquote>
<div>Serialize obj as a JSON formatted stream to fp (a <tt class="docutils literal">.write()</tt>-supporting
file-like object) using this <a class="reference internal" href="#py-to-json-table">conversion table</a>.
If skipkeys is true (default: <tt class="docutils literal">False</tt>), then dict keys that are not
of a basic type (<tt class="xref py py-class docutils literal">str</tt>, <tt class="xref py py-class docutils literal">unicode</tt>, <tt class="xref py py-class docutils literal">int</tt>, <tt class="xref py py-class docutils literal">long</tt>,
<tt class="xref py py-class docutils literal">float</tt>, <tt class="xref py py-class docutils literal">bool</tt>, <tt class="docutils literal">None</tt>) will be skipped instead of raising a
<tt class="xref py py-exc docutils literal">TypeError</tt>.
The <a class="reference internal" href="#module-simplejson" title="simplejson: Encode and decode the JSON format."><tt class="xref py py-mod docutils literal">simplejson</tt></a> module will produce <tt class="xref py py-class docutils literal">str</tt> objects in Python 3,
not <tt class="xref py py-class docutils literal">bytes</tt> objects. Therefore, <tt class="docutils literal">fp.write()</tt> must support
<tt class="xref py py-class docutils literal">str</tt> input.
If ensure_ascii is false (default: <tt class="docutils literal">True</tt>), then some chunks written
to fp may be <tt class="xref py py-class docutils literal">unicode</tt> instances, subject to normal Python
<tt class="xref py py-class docutils literal">str</tt> to <tt class="xref py py-class docutils literal">unicode</tt> coercion rules. Unless <tt class="docutils literal">fp.write()</tt>
explicitly understands <tt class="xref py py-class docutils literal">unicode</tt> (as in <tt class="xref py py-func docutils literal">codecs.getwriter()</tt>) this
is likely to cause an error. It&#8217;s best to leave the default settings, because
they are safe and it is highly optimized.
If check_circular is false (default: <tt class="docutils literal">True</tt>), then the circular
reference check for container types will be skipped and a circular reference
will result in an <tt class="xref py py-exc docutils literal">OverflowError</tt> (or worse).
If allow_nan is false (default: <tt class="docutils literal">True</tt>), then it will be a
<tt class="xref py py-exc docutils literal">ValueError</tt> to serialize out of range <tt class="xref py py-class docutils literal">float</tt> values (<tt class="docutils literal">nan</tt>,
<tt class="docutils literal">inf</tt>, <tt class="docutils literal">-inf</tt>) in strict compliance of the original JSON specification.
If allow_nan is true, their JavaScript equivalents will be used
(<tt class="docutils literal">NaN</tt>, <tt class="docutils literal">Infinity</tt>, <tt class="docutils literal">-Infinity</tt>). See also ignore_nan for ECMA-262
compliant behavior.
If indent is a string, then JSON array elements and object members
will be pretty-printed with a newline followed by that string repeated
for each level of nesting. <tt class="docutils literal">None</tt> (the default) selects the most compact
representation without any newlines. For backwards compatibility with
versions of simplejson earlier than 2.1.0, an integer is also accepted
and is converted to a string with that many spaces.

Changed in version 2.1.0: Changed indent from an integer number of spaces to a string.
If specified, separators should be an <tt class="docutils literal">(item_separator, key_separator)</tt>
tuple. The default is <tt class="docutils literal">(', ', ': ')</tt> if indent is <tt class="docutils literal">None</tt> and
<tt class="docutils literal">(',', ': ')</tt> otherwise. To get the most compact JSON representation,
you should specify <tt class="docutils literal">(',', ':')</tt> to eliminate whitespace.

Changed in version 2.1.4: Use <tt class="docutils literal">(',', ': ')</tt> as default if indent is not <tt class="docutils literal">None</tt>.
encoding is the character encoding for str instances, default is
<tt class="docutils literal">'utf-8'</tt>.
default(obj) is a function that should return a serializable version of
obj or raise <tt class="xref py py-exc docutils literal">TypeError</tt>. The default simply raises <tt class="xref py py-exc docutils literal">TypeError</tt>.
To use a custom <a class="reference internal" href="#simplejson.JSONEncoder" title="simplejson.JSONEncoder"><tt class="xref py py-class docutils literal">JSONEncoder</tt></a> subclass (e.g. one that overrides the
<tt class="xref py py-meth docutils literal">default()</tt> method to serialize additional types), specify it with the
cls kwarg.
<div class="admonition note">
Note
Subclassing is not recommended. Use the default kwarg
or for_json instead. This is faster and more portable.
</div>
If use_decimal is true (default: <tt class="docutils literal">True</tt>) then <tt class="xref py py-class docutils literal">decimal.Decimal</tt>
will be natively serialized to JSON with full precision.

Changed in version 2.1.0: use_decimal is new in 2.1.0.

Changed in version 2.2.0: The default of use_decimal changed to <tt class="docutils literal">True</tt> in 2.2.0.
If namedtuple_as_object is true (default: <tt class="docutils literal">True</tt>),
objects with <tt class="docutils literal">_asdict()</tt> methods will be encoded
as JSON objects.

Changed in version 2.2.0: namedtuple_as_object is new in 2.2.0.

Changed in version 2.3.0: namedtuple_as_object no longer requires that these objects be
subclasses of <tt class="xref py py-class docutils literal">tuple</tt>.
If tuple_as_array is true (default: <tt class="docutils literal">True</tt>),
<tt class="xref py py-class docutils literal">tuple</tt> (and subclasses) will be encoded as JSON arrays.
</div></blockquote>
If iterable_as_array is true (default: <tt class="docutils literal">False</tt>),
any object not in the above table that implements <tt class="docutils literal">__iter__()</tt>
will be encoded as a JSON array.

Changed in version 3.8.0: iterable_as_array is new in 3.8.0.
Changed in version 2.2.0: tuple_as_array is new in 2.2.0.
If bigint_as_string is true (default: <tt class="docutils literal">False</tt>), <tt class="xref py py-class docutils literal">int</tt> <tt class="docutils literal">2**53</tt>
and higher or lower than <tt class="docutils literal">-2**53</tt> will be encoded as strings. This is to
avoid the rounding that happens in Javascript otherwise. Note that this
option loses type information, so use with extreme caution.
See also int_as_string_bitcount.

Changed in version 2.4.0: bigint_as_string is new in 2.4.0.
If sort_keys is true (not the default), then the output of dictionaries
will be sorted by key; this is useful for regression tests to ensure that
JSON serializations can be compared on a day-to-day basis.

Changed in version 3.0.0: Sorting now happens after the keys have been coerced to
strings, to avoid comparison of heterogeneously typed objects
(since this does not work in Python 3.3+)
If item_sort_key is a callable (not the default), then the output of
dictionaries will be sorted with it. The callable will be used like this:
<tt class="docutils literal">sorted(dct.items(), key=item_sort_key)</tt>. This option takes precedence
over sort_keys.

Changed in version 2.5.0: item_sort_key is new in 2.5.0.

Changed in version 3.0.0: Sorting now happens after the keys have been coerced to
strings, to avoid comparison of heterogeneously typed objects
(since this does not work in Python 3.3+)
If for_json is true (not the default), objects with a <tt class="docutils literal">for_json()</tt>
method will use the return value of that method for encoding as JSON instead
of the object.

Changed in version 3.2.0: for_json is new in 3.2.0.
If ignore_nan is true (default: <tt class="docutils literal">False</tt>), then out of range
<tt class="xref py py-class docutils literal">float</tt> values (<tt class="docutils literal">nan</tt>, <tt class="docutils literal">inf</tt>, <tt class="docutils literal">-inf</tt>) will be serialized as
<tt class="docutils literal">null</tt> in compliance with the ECMA-262 specification. If true, this will
override allow_nan.

Changed in version 3.2.0: ignore_nan is new in 3.2.0.
If int_as_string_bitcount is a positive number <tt class="docutils literal">n</tt> (default: <tt class="docutils literal">None</tt>),
<tt class="xref py py-class docutils literal">int</tt> <tt class="docutils literal">2**n</tt> and higher or lower than <tt class="docutils literal">-2**n</tt> will be encoded as strings. This is to
avoid the rounding that happens in Javascript otherwise. Note that this
option loses type information, so use with extreme caution.
See also bigint_as_string (which is equivalent to <cite>int_as_string_bitcount=53</cite>).

Changed in version 3.5.0: int_as_string_bitcount is new in 3.5.0.
<div class="admonition note">
Note
JSON is not a framed protocol so unlike <tt class="xref py py-mod docutils literal">pickle</tt> or <tt class="xref py py-mod docutils literal">marshal</tt> it
does not make sense to serialize more than one JSON document without some
container protocol to delimit them.
</div>

</dd></dl>

<dl class="function">
<dt id="simplejson.dumps">
<tt class="descclassname">simplejson.</tt><tt class="descname">dumps</tt><big>(</big>obj, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, cls=None, indent=None, separators=None, encoding='utf-8', default=None, use_decimal=True, namedtuple_as_object=True, tuple_as_array=True, bigint_as_string=False, sort_keys=False, item_sort_key=None, for_json=None, ignore_nan=False, int_as_string_bitcount=None, iterable_as_array=False, **kw<big>)</big><a class="headerlink" href="#simplejson.dumps" title="Permalink to this definition">¶</a></dt>
<dd>Serialize obj to a JSON formatted <tt class="xref py py-class docutils literal">str</tt>.
If ensure_ascii is false, then the return value will be a
<tt class="xref py py-class docutils literal">unicode</tt> instance. The other arguments have the same meaning as in
<a class="reference internal" href="#simplejson.dump" title="simplejson.dump"><tt class="xref py py-func docutils literal">dump()</tt></a>. Note that the default ensure_ascii setting has much
better performance in Python 2.
The other options have the same meaning as in <a class="reference internal" href="#simplejson.dump" title="simplejson.dump"><tt class="xref py py-func docutils literal">dump()</tt></a>.
</dd></dl>

<dl class="function">
<dt id="simplejson.load">
<tt class="descclassname">simplejson.</tt><tt class="descname">load</tt><big>(</big>fp, encoding='utf-8', cls=None, object_hook=None, parse_float=None, parse_int=None, parse_constant=None, object_pairs_hook=None, use_decimal=None, **kw<big>)</big><a class="headerlink" href="#simplejson.load" title="Permalink to this definition">¶</a></dt>
<dd>Deserialize fp (a <tt class="docutils literal">.read()</tt>-supporting file-like object containing a JSON
document) to a Python object using this
<a class="reference internal" href="#json-to-py-table">conversion table</a>. <a class="reference internal" href="#simplejson.JSONDecodeError" title="simplejson.JSONDecodeError"><tt class="xref py py-exc docutils literal">JSONDecodeError</tt></a> will be
raised if the given JSON document is not valid.
If the contents of fp are encoded with an ASCII based encoding other than
UTF-8 (e.g. latin-1), then an appropriate encoding name must be specified.
Encodings that are not ASCII based (such as UCS-2) are not allowed, and
should be wrapped with <tt class="docutils literal">codecs.getreader(fp)(encoding)</tt>, or simply decoded
to a <tt class="xref py py-class docutils literal">unicode</tt> object and passed to <a class="reference internal" href="#simplejson.loads" title="simplejson.loads"><tt class="xref py py-func docutils literal">loads()</tt></a>. The default
setting of <tt class="docutils literal">'utf-8'</tt> is fastest and should be using whenever possible.
If fp.read() returns <tt class="xref py py-class docutils literal">str</tt> then decoded JSON strings that contain
only ASCII characters may be parsed as <tt class="xref py py-class docutils literal">str</tt> for performance and
memory reasons. If your code expects only <tt class="xref py py-class docutils literal">unicode</tt> the appropriate
solution is to wrap fp with a reader as demonstrated above.
object_hook is an optional function that will be called with the result of
any object literal decode (a <tt class="xref py py-class docutils literal">dict</tt>). The return value of
object_hook will be used instead of the <tt class="xref py py-class docutils literal">dict</tt>. This feature can be used
to implement custom decoders (e.g. <a class="reference external" href="http://www.jsonrpc.org">JSON-RPC</a>
class hinting).
object_pairs_hook is an optional function that will be called with the
result of any object literal decode with an ordered list of pairs. The
return value of object_pairs_hook will be used instead of the
<tt class="xref py py-class docutils literal">dict</tt>. This feature can be used to implement custom decoders that
rely on the order that the key and value pairs are decoded (for example,
<tt class="xref py py-class docutils literal">collections.OrderedDict</tt> will remember the order of insertion). If
object_hook is also defined, the object_pairs_hook takes priority.

Changed in version 2.1.0: Added support for object_pairs_hook.
parse_float, if specified, will be called with the string of every JSON
float to be decoded. By default, this is equivalent to <tt class="docutils literal">float(num_str)</tt>.
This can be used to use another datatype or parser for JSON floats
(e.g. <tt class="xref py py-class docutils literal">decimal.Decimal</tt>).
parse_int, if specified, will be called with the string of every JSON int
to be decoded. By default, this is equivalent to <tt class="docutils literal">int(num_str)</tt>. This can
be used to use another datatype or parser for JSON integers
(e.g. <tt class="xref py py-class docutils literal">float</tt>).
parse_constant, if specified, will be called with one of the following
strings: <tt class="docutils literal">'-Infinity'</tt>, <tt class="docutils literal">'Infinity'</tt>, <tt class="docutils literal">'NaN'</tt>. This can be used to
raise an exception if invalid JSON numbers are encountered.
If use_decimal is true (default: <tt class="docutils literal">False</tt>) then parse_float is set to
<tt class="xref py py-class docutils literal">decimal.Decimal</tt>. This is a convenience for parity with the
<a class="reference internal" href="#simplejson.dump" title="simplejson.dump"><tt class="xref py py-func docutils literal">dump()</tt></a> parameter.

Changed in version 2.1.0: use_decimal is new in 2.1.0.
If iterable_as_array is true (default: <tt class="docutils literal">False</tt>),
any object not in the above table that implements <tt class="docutils literal">__iter__()</tt>
will be encoded as a JSON array.

Changed in version 3.8.0: iterable_as_array is new in 3.8.0.
To use a custom <a class="reference internal" href="#simplejson.JSONDecoder" title="simplejson.JSONDecoder"><tt class="xref py py-class docutils literal">JSONDecoder</tt></a> subclass, specify it with the <tt class="docutils literal">cls</tt>
kwarg. Additional keyword arguments will be passed to the constructor of the
class. You probably shouldn&#8217;t do this.
<blockquote>
<div><div class="admonition note">
Note
Subclassing is not recommended. You should use object_hook or
object_pairs_hook. This is faster and more portable than subclassing.
</div>
<div class="admonition note">
Note
<a class="reference internal" href="#simplejson.load" title="simplejson.load"><tt class="xref py py-func docutils literal">load()</tt></a> will read the rest of the file-like object as a string and
then call <a class="reference internal" href="#simplejson.loads" title="simplejson.loads"><tt class="xref py py-func docutils literal">loads()</tt></a>. It does not stop at the end of the first valid
JSON document it finds and it will raise an error if there is anything
other than whitespace after the document. Except for files containing
only one JSON document, it is recommended to use <a class="reference internal" href="#simplejson.loads" title="simplejson.loads"><tt class="xref py py-func docutils literal">loads()</tt></a>.
</div>
</div></blockquote>
</dd></dl>

<dl class="function">
<dt id="simplejson.loads">
<tt class="descclassname">simplejson.</tt><tt class="descname">loads</tt><big>(</big>fp, encoding='utf-8', cls=None, object_hook=None, parse_float=None, parse_int=None, parse_constant=None, object_pairs_hook=None, use_decimal=None, **kw<big>)</big><a class="headerlink" href="#simplejson.loads" title="Permalink to this definition">¶</a></dt>
<dd>Deserialize s (a <tt class="xref py py-class docutils literal">str</tt> or <tt class="xref py py-class docutils literal">unicode</tt> instance containing a JSON
document) to a Python object. <a class="reference internal" href="#simplejson.JSONDecodeError" title="simplejson.JSONDecodeError"><tt class="xref py py-exc docutils literal">JSONDecodeError</tt></a> will be
raised if the given JSON document is not valid.
If s is a <tt class="xref py py-class docutils literal">str</tt> instance and is encoded with an ASCII based encoding
other than UTF-8 (e.g. latin-1), then an appropriate encoding name must be
specified. Encodings that are not ASCII based (such as UCS-2) are not
allowed and should be decoded to <tt class="xref py py-class docutils literal">unicode</tt> first.
If s is a <tt class="xref py py-class docutils literal">str</tt> then decoded JSON strings that contain
only ASCII characters may be parsed as <tt class="xref py py-class docutils literal">str</tt> for performance and
memory reasons. If your code expects only <tt class="xref py py-class docutils literal">unicode</tt> the appropriate
solution is decode s to <tt class="xref py py-class docutils literal">unicode</tt> prior to calling loads.
The other arguments have the same meaning as in <a class="reference internal" href="#simplejson.load" title="simplejson.load"><tt class="xref py py-func docutils literal">load()</tt></a>.
</dd></dl>

</div>
<div class="section" id="encoders-and-decoders">
<h2>Encoders and decoders<a class="headerlink" href="#encoders-and-decoders" title="Permalink to this headline">¶</a></h2>
<dl class="class">
<dt id="simplejson.JSONDecoder">
class <tt class="descclassname">simplejson.</tt><tt class="descname">JSONDecoder</tt><big>(</big>encoding='utf-8', object_hook=None, parse_float=None, parse_int=None, parse_constant=None, object_pairs_hook=None, strict=True<big>)</big><a class="headerlink" href="#simplejson.JSONDecoder" title="Permalink to this definition">¶</a></dt>
<dd>Simple JSON decoder.
Performs the following translations in decoding by default:
<table border="1" class="docutils" id="json-to-py-table">
<colgroup>
<col width="41%" />
<col width="30%" />
<col width="30%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">JSON</th>
<th class="head">Python 2</th>
<th class="head">Python 3</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td>object</td>
<td>dict</td>
<td>dict</td>
</tr>
<tr class="row-odd"><td>array</td>
<td>list</td>
<td>list</td>
</tr>
<tr class="row-even"><td>string</td>
<td>unicode</td>
<td>str</td>
</tr>
<tr class="row-odd"><td>number (int)</td>
<td>int, long</td>
<td>int</td>
</tr>
<tr class="row-even"><td>number (real)</td>
<td>float</td>
<td>float</td>
</tr>
<tr class="row-odd"><td>true</td>
<td>True</td>
<td>True</td>
</tr>
<tr class="row-even"><td>false</td>
<td>False</td>
<td>False</td>
</tr>
<tr class="row-odd"><td>null</td>
<td>None</td>
<td>None</td>
</tr>
</tbody>
</table>
It also understands <tt class="docutils literal">NaN</tt>, <tt class="docutils literal">Infinity</tt>, and <tt class="docutils literal">-Infinity</tt> as their
corresponding <tt class="docutils literal">float</tt> values, which is outside the JSON spec.
encoding determines the encoding used to interpret any <tt class="xref py py-class docutils literal">str</tt> objects
decoded by this instance (<tt class="docutils literal">'utf-8'</tt> by default). It has no effect when decoding
<tt class="xref py py-class docutils literal">unicode</tt> objects.
Note that currently only encodings that are a superset of ASCII work, strings
of other encodings should be passed in as <tt class="xref py py-class docutils literal">unicode</tt>.
object_hook is an optional function that will be called with the result of
every JSON object decoded and its return value will be used in place of the
given <tt class="xref py py-class docutils literal">dict</tt>. This can be used to provide custom deserializations
(e.g. to support JSON-RPC class hinting).
object_pairs_hook is an optional function that will be called with the
result of any object literal decode with an ordered list of pairs. The
return value of object_pairs_hook will be used instead of the
<tt class="xref py py-class docutils literal">dict</tt>. This feature can be used to implement custom decoders that
rely on the order that the key and value pairs are decoded (for example,
<tt class="xref py py-class docutils literal">collections.OrderedDict</tt> will remember the order of insertion). If
object_hook is also defined, the object_pairs_hook takes priority.

Changed in version 2.1.0: Added support for object_pairs_hook.
parse_float, if specified, will be called with the string of every JSON
float to be decoded. By default, this is equivalent to <tt class="docutils literal">float(num_str)</tt>.
This can be used to use another datatype or parser for JSON floats
(e.g. <tt class="xref py py-class docutils literal">decimal.Decimal</tt>).
parse_int, if specified, will be called with the string of every JSON int
to be decoded. By default, this is equivalent to <tt class="docutils literal">int(num_str)</tt>. This can
be used to use another datatype or parser for JSON integers
(e.g. <tt class="xref py py-class docutils literal">float</tt>).
parse_constant, if specified, will be called with one of the following
strings: <tt class="docutils literal">'-Infinity'</tt>, <tt class="docutils literal">'Infinity'</tt>, <tt class="docutils literal">'NaN'</tt>. This can be used to
raise an exception if invalid JSON numbers are encountered.
strict controls the parser&#8217;s behavior when it encounters an invalid
control character in a string. The default setting of <tt class="docutils literal">True</tt> means that
unescaped control characters are parse errors, if <tt class="docutils literal">False</tt> then control
characters will be allowed in strings.
<dl class="method">
<dt id="simplejson.JSONDecoder.decode">
<tt class="descname">decode</tt><big>(</big>s<big>)</big><a class="headerlink" href="#simplejson.JSONDecoder.decode" title="Permalink to this definition">¶</a></dt>
<dd>Return the Python representation of s (a <tt class="xref py py-class docutils literal">str</tt> or
<tt class="xref py py-class docutils literal">unicode</tt> instance containing a JSON document)
If s is a <tt class="xref py py-class docutils literal">str</tt> then decoded JSON strings that contain
only ASCII characters may be parsed as <tt class="xref py py-class docutils literal">str</tt> for performance and
memory reasons. If your code expects only <tt class="xref py py-class docutils literal">unicode</tt> the
appropriate solution is decode s to <tt class="xref py py-class docutils literal">unicode</tt> prior to calling
decode.
<a class="reference internal" href="#simplejson.JSONDecodeError" title="simplejson.JSONDecodeError"><tt class="xref py py-exc docutils literal">JSONDecodeError</tt></a> will be raised if the given JSON
document is not valid.
</dd></dl>

<dl class="method">
<dt id="simplejson.JSONDecoder.raw_decode">
<tt class="descname">raw_decode</tt><big>(</big>s[, idx=0]<big>)</big><a class="headerlink" href="#simplejson.JSONDecoder.raw_decode" title="Permalink to this definition">¶</a></dt>
<dd>Decode a JSON document from s (a <tt class="xref py py-class docutils literal">str</tt> or <tt class="xref py py-class docutils literal">unicode</tt>
beginning with a JSON document) starting from the index idx and return
a 2-tuple of the Python representation and the index in s where the
document ended.
This can be used to decode a JSON document from a string that may have
extraneous data at the end, or to decode a string that has a series of
JSON objects.
<a class="reference internal" href="#simplejson.JSONDecodeError" title="simplejson.JSONDecodeError"><tt class="xref py py-exc docutils literal">JSONDecodeError</tt></a> will be raised if the given JSON
document is not valid.
</dd></dl>

</dd></dl>

<dl class="class">
<dt id="simplejson.JSONEncoder">
class <tt class="descclassname">simplejson.</tt><tt class="descname">JSONEncoder</tt><big>(</big>skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, encoding='utf-8', default=None, use_decimal=True, namedtuple_as_object=True, tuple_as_array=True, bigint_as_string=False, item_sort_key=None, for_json=True, ignore_nan=False, int_as_string_bitcount=None, iterable_as_array=False<big>)</big><a class="headerlink" href="#simplejson.JSONEncoder" title="Permalink to this definition">¶</a></dt>
<dd>Extensible JSON encoder for Python data structures.
Supports the following objects and types by default:
<table border="1" class="docutils" id="py-to-json-table">
<colgroup>
<col width="56%" />
<col width="44%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Python</th>
<th class="head">JSON</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td>dict, namedtuple</td>
<td>object</td>
</tr>
<tr class="row-odd"><td>list, tuple</td>
<td>array</td>
</tr>
<tr class="row-even"><td>str, unicode</td>
<td>string</td>
</tr>
<tr class="row-odd"><td>int, long, float</td>
<td>number</td>
</tr>
<tr class="row-even"><td>True</td>
<td>true</td>
</tr>
<tr class="row-odd"><td>False</td>
<td>false</td>
</tr>
<tr class="row-even"><td>None</td>
<td>null</td>
</tr>
</tbody>
</table>
<div class="admonition note">
Note
The JSON format only permits strings to be used as object
keys, thus any Python dicts to be encoded should only have string keys.
For backwards compatibility, several other types are automatically
coerced to strings: int, long, float, Decimal, bool, and None.
It is error-prone to rely on this behavior, so avoid it when possible.
Dictionaries with other types used as keys should be pre-processed or
wrapped in another type with an appropriate <cite>for_json</cite> method to
transform the keys during encoding.
</div>
It also understands <tt class="docutils literal">NaN</tt>, <tt class="docutils literal">Infinity</tt>, and <tt class="docutils literal">-Infinity</tt> as their
corresponding <tt class="docutils literal">float</tt> values, which is outside the JSON spec.

Changed in version 2.2.0: Changed namedtuple encoding from JSON array to object.
To extend this to recognize other objects, subclass and implement a
<a class="reference internal" href="#simplejson.JSONEncoder.default" title="simplejson.JSONEncoder.default"><tt class="xref py py-meth docutils literal">default()</tt></a> method with another method that returns a serializable object
for <tt class="docutils literal">o</tt> if possible, otherwise it should call the superclass implementation
(to raise <tt class="xref py py-exc docutils literal">TypeError</tt>).
<blockquote>
<div><div class="admonition note">
Note
Subclassing is not recommended. You should use the default
or for_json kwarg. This is faster and more portable than subclassing.
</div>
</div></blockquote>
If skipkeys is false (the default), then it is a <tt class="xref py py-exc docutils literal">TypeError</tt> to
attempt encoding of keys that are not str, int, long, float, Decimal, bool,
or None. If skipkeys is true, such items are simply skipped.
If ensure_ascii is true (the default), the output is guaranteed to be
<tt class="xref py py-class docutils literal">str</tt> objects with all incoming unicode characters escaped. If
ensure_ascii is false, the output will be a unicode object.
If check_circular is true (the default), then lists, dicts, and custom
encoded objects will be checked for circular references during encoding to
prevent an infinite recursion (which would cause an <tt class="xref py py-exc docutils literal">OverflowError</tt>).
Otherwise, no such check takes place.
If allow_nan is true (the default), then <tt class="docutils literal">NaN</tt>, <tt class="docutils literal">Infinity</tt>, and
<tt class="docutils literal">-Infinity</tt> will be encoded as such. This behavior is not JSON
specification compliant, but is consistent with most JavaScript based
encoders and decoders. Otherwise, it will be a <tt class="xref py py-exc docutils literal">ValueError</tt> to encode
such floats. See also ignore_nan for ECMA-262 compliant behavior.
If sort_keys is true (not the default), then the output of dictionaries
will be sorted by key; this is useful for regression tests to ensure that
JSON serializations can be compared on a day-to-day basis.

Changed in version 3.0.0: Sorting now happens after the keys have been coerced to
strings, to avoid comparison of heterogeneously typed objects
(since this does not work in Python 3.3+)
If item_sort_key is a callable (not the default), then the output of
dictionaries will be sorted with it. The callable will be used like this:
<tt class="docutils literal">sorted(dct.items(), key=item_sort_key)</tt>. This option takes precedence
over sort_keys.

Changed in version 2.5.0: item_sort_key is new in 2.5.0.

Changed in version 3.0.0: Sorting now happens after the keys have been coerced to
strings, to avoid comparison of heterogeneously typed objects
(since this does not work in Python 3.3+)
If indent is a string, then JSON array elements and object members
will be pretty-printed with a newline followed by that string repeated
for each level of nesting. <tt class="docutils literal">None</tt> (the default) selects the most compact
representation without any newlines. For backwards compatibility with
versions of simplejson earlier than 2.1.0, an integer is also accepted
and is converted to a string with that many spaces.

Changed in version 2.1.0: Changed indent from an integer number of spaces to a string.
If specified, separators should be an <tt class="docutils literal">(item_separator, key_separator)</tt>
tuple. The default is <tt class="docutils literal">(', ', ': ')</tt> if indent is <tt class="docutils literal">None</tt> and
<tt class="docutils literal">(',', ': ')</tt> otherwise. To get the most compact JSON representation,
you should specify <tt class="docutils literal">(',', ':')</tt> to eliminate whitespace.

Changed in version 2.1.4: Use <tt class="docutils literal">(',', ': ')</tt> as default if indent is not <tt class="docutils literal">None</tt>.
If specified, default should be a function that gets called for objects
that can&#8217;t otherwise be serialized. It should return a JSON encodable
version of the object or raise a <tt class="xref py py-exc docutils literal">TypeError</tt>.
If encoding is not <tt class="docutils literal">None</tt>, then all input strings will be transformed
into unicode using that encoding prior to JSON-encoding. The default is
<tt class="docutils literal">'utf-8'</tt>.
If namedtuple_as_object is true (default: <tt class="docutils literal">True</tt>),
objects with <tt class="docutils literal">_asdict()</tt> methods will be encoded
as JSON objects.

Changed in version 2.2.0: namedtuple_as_object is new in 2.2.0.

Changed in version 2.3.0: namedtuple_as_object no longer requires that these objects be
subclasses of <tt class="xref py py-class docutils literal">tuple</tt>.
If tuple_as_array is true (default: <tt class="docutils literal">True</tt>),
<tt class="xref py py-class docutils literal">tuple</tt> (and subclasses) will be encoded as JSON arrays.

Changed in version 2.2.0: tuple_as_array is new in 2.2.0.
If iterable_as_array is true (default: <tt class="docutils literal">False</tt>),
any object not in the above table that implements <tt class="docutils literal">__iter__()</tt>
will be encoded as a JSON array.

Changed in version 3.8.0: iterable_as_array is new in 3.8.0.
If bigint_as_string is true (default: <tt class="docutils literal">False</tt>), <tt class="xref py py-class docutils literal">int`</tt> <tt class="docutils literal">2**53</tt>
and higher or lower than <tt class="docutils literal">-2**53</tt> will be encoded as strings. This is to
avoid the rounding that happens in Javascript otherwise. Note that this
option loses type information, so use with extreme caution.

Changed in version 2.4.0: bigint_as_string is new in 2.4.0.
If for_json is true (default: <tt class="docutils literal">False</tt>), objects with a <tt class="docutils literal">for_json()</tt>
method will use the return value of that method for encoding as JSON instead
of the object.

Changed in version 3.2.0: for_json is new in 3.2.0.
If ignore_nan is true (default: <tt class="docutils literal">False</tt>), then out of range
<tt class="xref py py-class docutils literal">float</tt> values (<tt class="docutils literal">nan</tt>, <tt class="docutils literal">inf</tt>, <tt class="docutils literal">-inf</tt>) will be serialized as
<tt class="docutils literal">null</tt> in compliance with the ECMA-262 specification. If true, this will
override allow_nan.

Changed in version 3.2.0: ignore_nan is new in 3.2.0.
<dl class="method">
<dt id="simplejson.JSONEncoder.default">
<tt class="descname">default</tt><big>(</big>o<big>)</big><a class="headerlink" href="#simplejson.JSONEncoder.default" title="Permalink to this definition">¶</a></dt>
<dd><blockquote>
<div>Implement this method in a subclass such that it returns a serializable
object for o, or calls the base implementation (to raise a
<tt class="xref py py-exc docutils literal">TypeError</tt>).
For example, to support arbitrary iterators, you could implement default
like this:
<div class="highlight-python"><div class="highlight"><pre>def default(self, o):
 try:
 iterable = iter(o)
 except TypeError:
 pass
 else:
 return list(iterable)
 return JSONEncoder.default(self, o)
</pre></div>
</div>
</div></blockquote>
<div class="admonition note">
Note
Subclassing is not recommended. You should implement this
as a function and pass it to the default kwarg of <a class="reference internal" href="#simplejson.dumps" title="simplejson.dumps"><tt class="xref py py-func docutils literal">dumps()</tt></a>.
This is faster and more portable than subclassing. The
semantics are the same, but without the self argument or the
call to the super implementation.
</div>
</dd></dl>

<dl class="method">
<dt id="simplejson.JSONEncoder.encode">
<tt class="descname">encode</tt><big>(</big>o<big>)</big><a class="headerlink" href="#simplejson.JSONEncoder.encode" title="Permalink to this definition">¶</a></dt>
<dd>Return a JSON string representation of a Python data structure, o. For
example:
<div class="highlight-python"><div class="highlight"><pre>&gt;&gt;&gt; import simplejson as json
&gt;&gt;&gt; json.JSONEncoder().encode({&quot;foo&quot;: [&quot;bar&quot;, &quot;baz&quot;]})
&#39;{&quot;foo&quot;: [&quot;bar&quot;, &quot;baz&quot;]}&#39;
</pre></div>
</div>
</dd></dl>

<dl class="method">
<dt id="simplejson.JSONEncoder.iterencode">
<tt class="descname">iterencode</tt><big>(</big>o<big>)</big><a class="headerlink" href="#simplejson.JSONEncoder.iterencode" title="Permalink to this definition">¶</a></dt>
<dd>Encode the given object, o, and yield each string representation as
available. For example:
<div class="highlight-python"><div class="highlight"><pre>for chunk in JSONEncoder().iterencode(bigobject):
 mysocket.write(chunk)
</pre></div>
</div>
Note that <a class="reference internal" href="#simplejson.JSONEncoder.encode" title="simplejson.JSONEncoder.encode"><tt class="xref py py-meth docutils literal">encode()</tt></a> has much better performance than
<a class="reference internal" href="#simplejson.JSONEncoder.iterencode" title="simplejson.JSONEncoder.iterencode"><tt class="xref py py-meth docutils literal">iterencode()</tt></a>.
</dd></dl>

</dd></dl>

<dl class="class">
<dt id="simplejson.JSONEncoderForHTML">
class <tt class="descclassname">simplejson.</tt><tt class="descname">JSONEncoderForHTML</tt><big>(</big>skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, encoding='utf-8', default=None, use_decimal=True, namedtuple_as_object=True, tuple_as_array=True, bigint_as_string=False, item_sort_key=None, for_json=True, ignore_nan=False, int_as_string_bitcount=None<big>)</big><a class="headerlink" href="#simplejson.JSONEncoderForHTML" title="Permalink to this definition">¶</a></dt>
<dd>Subclass of <a class="reference internal" href="#simplejson.JSONEncoder" title="simplejson.JSONEncoder"><tt class="xref py py-class docutils literal">JSONEncoder</tt></a> that escapes &amp;, &lt;, and &gt; for embedding in HTML.

Changed in version 2.1.0: New in 2.1.0
</dd></dl>

</div>
<div class="section" id="exceptions">
<h2>Exceptions<a class="headerlink" href="#exceptions" title="Permalink to this headline">¶</a></h2>
<dl class="exception">
<dt id="simplejson.JSONDecodeError">
exception <tt class="descclassname">simplejson.</tt><tt class="descname">JSONDecodeError</tt><big>(</big>msg, doc, pos, end=None<big>)</big><a class="headerlink" href="#simplejson.JSONDecodeError" title="Permalink to this definition">¶</a></dt>
<dd>Subclass of <tt class="xref py py-exc docutils literal">ValueError</tt> with the following additional attributes:
<dl class="attribute">
<dt id="simplejson.JSONDecodeError.msg">
<tt class="descname">msg</tt><a class="headerlink" href="#simplejson.JSONDecodeError.msg" title="Permalink to this definition">¶</a></dt>
<dd>The unformatted error message
</dd></dl>

<dl class="attribute">
<dt id="simplejson.JSONDecodeError.doc">
<tt class="descname">doc</tt><a class="headerlink" href="#simplejson.JSONDecodeError.doc" title="Permalink to this definition">¶</a></dt>
<dd>The JSON document being parsed
</dd></dl>

<dl class="attribute">
<dt id="simplejson.JSONDecodeError.pos">
<tt class="descname">pos</tt><a class="headerlink" href="#simplejson.JSONDecodeError.pos" title="Permalink to this definition">¶</a></dt>
<dd>The start index of doc where parsing failed
</dd></dl>

<dl class="attribute">
<dt id="simplejson.JSONDecodeError.end">
<tt class="descname">end</tt><a class="headerlink" href="#simplejson.JSONDecodeError.end" title="Permalink to this definition">¶</a></dt>
<dd>The end index of doc where parsing failed (may be <tt class="docutils literal">None</tt>)
</dd></dl>

<dl class="attribute">
<dt id="simplejson.JSONDecodeError.lineno">
<tt class="descname">lineno</tt><a class="headerlink" href="#simplejson.JSONDecodeError.lineno" title="Permalink to this definition">¶</a></dt>
<dd>The line corresponding to pos
</dd></dl>

<dl class="attribute">
<dt id="simplejson.JSONDecodeError.colno">
<tt class="descname">colno</tt><a class="headerlink" href="#simplejson.JSONDecodeError.colno" title="Permalink to this definition">¶</a></dt>
<dd>The column corresponding to pos
</dd></dl>

<dl class="attribute">
<dt id="simplejson.JSONDecodeError.endlineno">
<tt class="descname">endlineno</tt><a class="headerlink" href="#simplejson.JSONDecodeError.endlineno" title="Permalink to this definition">¶</a></dt>
<dd>The line corresponding to end (may be <tt class="docutils literal">None</tt>)
</dd></dl>

<dl class="attribute">
<dt id="simplejson.JSONDecodeError.endcolno">
<tt class="descname">endcolno</tt><a class="headerlink" href="#simplejson.JSONDecodeError.endcolno" title="Permalink to this definition">¶</a></dt>
<dd>The column corresponding to end (may be <tt class="docutils literal">None</tt>)
</dd></dl>

</dd></dl>

</div>
<div class="section" id="standard-compliance-and-interoperability">
<h2>Standard Compliance and Interoperability<a class="headerlink" href="#standard-compliance-and-interoperability" title="Permalink to this headline">¶</a></h2>
The JSON format is specified by <a class="rfc reference external" href="http://tools.ietf.org/html/rfc7159.html">RFC 7159</a> and by
<a class="reference external" href="http://www.ecma-international.org/publications/standards/Ecma-404.htm">ECMA-404</a>.
This section details this module&#8217;s level of compliance with the RFC.
For simplicity, <a class="reference internal" href="#simplejson.JSONEncoder" title="simplejson.JSONEncoder"><tt class="xref py py-class docutils literal">JSONEncoder</tt></a> and <a class="reference internal" href="#simplejson.JSONDecoder" title="simplejson.JSONDecoder"><tt class="xref py py-class docutils literal">JSONDecoder</tt></a> subclasses, and
parameters other than those explicitly mentioned, are not considered.
This module does not comply with the RFC in a strict fashion, implementing some
extensions that are valid JavaScript but not valid JSON. In particular:
<ul class="simple">
<li>Infinite and NaN number values are accepted and output;</li>
<li>Repeated names within an object are accepted, and only the value of the last
name-value pair is used.</li>
</ul>
Since the RFC permits RFC-compliant parsers to accept input texts that are not
RFC-compliant, this module&#8217;s deserializer is technically RFC-compliant under
default settings.
<div class="section" id="character-encodings">
<h3>Character Encodings<a class="headerlink" href="#character-encodings" title="Permalink to this headline">¶</a></h3>
The RFC recommends that JSON be represented using either UTF-8, UTF-16, or
UTF-32, with UTF-8 being the recommended default for maximum interoperability.
As permitted, though not required, by the RFC, this module&#8217;s serializer sets
ensure_ascii=True by default, thus escaping the output so that the resulting
strings only contain ASCII characters.
Other than the ensure_ascii parameter, this module is defined strictly in
terms of conversion between Python objects and
<tt class="xref py py-class docutils literal">Unicode strings</tt>, and thus does not otherwise directly address
the issue of character encodings.
The RFC prohibits adding a byte order mark (BOM) to the start of a JSON text,
and this module&#8217;s serializer does not add a BOM to its output.
The RFC permits, but does not require, JSON deserializers to ignore an initial
BOM in their input. This module&#8217;s deserializer will ignore an initial BOM, if
present.

Changed in version 3.6.0: Older versions would raise <tt class="xref py py-exc docutils literal">ValueError</tt> when an initial BOM is present
The RFC does not explicitly forbid JSON strings which contain byte sequences
that don&#8217;t correspond to valid Unicode characters (e.g. unpaired UTF-16
surrogates), but it does note that they may cause interoperability problems.
By default, this module accepts and outputs (when present in the original
<tt class="xref py py-class docutils literal">str</tt>) codepoints for such sequences.
</div>
<div class="section" id="infinite-and-nan-number-values">
<h3>Infinite and NaN Number Values<a class="headerlink" href="#infinite-and-nan-number-values" title="Permalink to this headline">¶</a></h3>
The RFC does not permit the representation of infinite or NaN number values.
Despite that, by default, this module accepts and outputs <tt class="docutils literal">Infinity</tt>,
<tt class="docutils literal">-Infinity</tt>, and <tt class="docutils literal">NaN</tt> as if they were valid JSON number literal values:
<div class="highlight-python"><div class="highlight"><pre>&gt;&gt;&gt; # Neither of these calls raises an exception, but the results are not valid JSON
&gt;&gt;&gt; json.dumps(float(&#39;-inf&#39;))
&#39;-Infinity&#39;
&gt;&gt;&gt; json.dumps(float(&#39;nan&#39;))
&#39;NaN&#39;
&gt;&gt;&gt; # Same when deserializing
&gt;&gt;&gt; json.loads(&#39;-Infinity&#39;)
-inf
&gt;&gt;&gt; json.loads(&#39;NaN&#39;)
nan
</pre></div>
</div>
In the serializer, the allow_nan parameter can be used to alter this
behavior. In the deserializer, the parse_constant parameter can be used to
alter this behavior.
</div>
<div class="section" id="repeated-names-within-an-object">
<h3>Repeated Names Within an Object<a class="headerlink" href="#repeated-names-within-an-object" title="Permalink to this headline">¶</a></h3>
The RFC specifies that the names within a JSON object should be unique, but
does not mandate how repeated names in JSON objects should be handled. By
default, this module does not raise an exception; instead, it ignores all but
the last name-value pair for a given name:
<div class="highlight-python"><div class="highlight"><pre>&gt;&gt;&gt; weird_json = &#39;{&quot;x&quot;: 1, &quot;x&quot;: 2, &quot;x&quot;: 3}&#39;
&gt;&gt;&gt; json.loads(weird_json) == {&#39;x&#39;: 3}
True
</pre></div>
</div>
The object_pairs_hook parameter can be used to alter this behavior.
</div>
<div class="section" id="top-level-non-object-non-array-values">
<h3>Top-level Non-Object, Non-Array Values<a class="headerlink" href="#top-level-non-object-non-array-values" title="Permalink to this headline">¶</a></h3>
The old version of JSON specified by the obsolete <a class="rfc reference external" href="http://tools.ietf.org/html/rfc4627.html">RFC 4627</a> required that
the top-level value of a JSON text must be either a JSON object or array
(Python <tt class="xref py py-class docutils literal">dict</tt> or <tt class="xref py py-class docutils literal">list</tt>), and could not be a JSON null,
boolean, number, or string value. <a class="rfc reference external" href="http://tools.ietf.org/html/rfc7159.html">RFC 7159</a> removed that restriction, and
this module does not and has never implemented that restriction in either its
serializer or its deserializer.
Regardless, for maximum interoperability, you may wish to voluntarily adhere
to the restriction yourself.
</div>
<div class="section" id="implementation-limitations">
<h3>Implementation Limitations<a class="headerlink" href="#implementation-limitations" title="Permalink to this headline">¶</a></h3>
Some JSON deserializer implementations may set limits on:
<ul class="simple">
<li>the size of accepted JSON texts</li>
<li>the maximum level of nesting of JSON objects and arrays</li>
<li>the range and precision of JSON numbers</li>
<li>the content and maximum length of JSON strings</li>
</ul>
This module does not impose any such limits beyond those of the relevant
Python datatypes themselves or the Python interpreter itself.
When serializing to JSON, beware any such limitations in applications that may
consume your JSON. In particular, it is common for JSON numbers to be
deserialized into IEEE 754 double precision numbers and thus subject to that
representation&#8217;s range and precision limitations. This is especially relevant
when serializing Python <tt class="xref py py-class docutils literal">int</tt> values of extremely large magnitude, or
when serializing instances of &#8220;exotic&#8221; numerical types such as
<tt class="xref py py-class docutils literal">decimal.Decimal</tt>.
</div>
</div>
<div class="section" id="command-line-interface">
<h2>Command Line Interface<a class="headerlink" href="#command-line-interface" title="Permalink to this headline">¶</a></h2>
The <tt class="xref py py-mod docutils literal">simplejson.tool</tt> module provides a simple command line interface to
validate and pretty-print JSON.
If the optional infile and outfile arguments are not
specified, <tt class="xref py py-attr docutils literal">sys.stdin</tt> and <tt class="xref py py-attr docutils literal">sys.stdout</tt> will be used respectively:
<div class="highlight-bash"><div class="highlight"><pre>$ echo &#39;{&quot;json&quot;: &quot;obj&quot;}&#39; | python -m simplejson.tool
{
 &quot;json&quot;: &quot;obj&quot;
}
$ echo &#39;{1.2:3.4}&#39; | python -m simplejson.tool
Expecting property name enclosed in double quotes: line 1 column 2 (char 1)
</pre></div>
</div>
<div class="section" id="command-line-options">
<h3>Command line options<a class="headerlink" href="#command-line-options" title="Permalink to this headline">¶</a></h3>
<dl class="cmdoption">
<dt>
<tt class="descname">infile</tt></dt>
<dd>The JSON file to be validated or pretty-printed:
<div class="highlight-bash"><div class="highlight"><pre>$ python -m simplejson.tool mp_films.json
[
 {
 &quot;title&quot;: &quot;And Now for Something Completely Different&quot;,
 &quot;year&quot;: 1971
 },
 {
 &quot;title&quot;: &quot;Monty Python and the Holy Grail&quot;,
 &quot;year&quot;: 1975
 }
]
</pre></div>
</div>
If infile is not specified, read from <tt class="xref py py-attr docutils literal">sys.stdin</tt>.
</dd></dl>

<dl class="cmdoption">
<dt>
<tt class="descname">outfile</tt></dt>
<dd>Write the output of the infile to the given outfile. Otherwise, write it
to <tt class="xref py py-attr docutils literal">sys.stdout</tt>.
</dd></dl>

Footnotes
<table class="docutils footnote" frame="void" id="rfc-errata" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id1">[1]</a></td><td>As noted in <a class="reference external" href="http://www.rfc-editor.org/errata_search.php?rfc=7159">the errata for RFC 7159</a>,
JSON permits literal U+2028 (LINE SEPARATOR) and
U+2029 (PARAGRAPH SEPARATOR) characters in strings, whereas JavaScript
(as of ECMAScript Edition 5.1) does not.</td></tr>
</tbody>
</table>
</div>
</div>
</div>

</div>
 </div>
 </div>
 <div class="sphinxsidebar">
 <div class="sphinxsidebarwrapper">
 <h3><a href="#">Table Of Contents</a></h3>
 <ul>
<li><a class="reference internal" href="#"><tt class="docutils literal">simplejson</tt> &#8212; JSON encoder and decoder</a><ul>
<li><a class="reference internal" href="#basic-usage">Basic Usage</a></li>
<li><a class="reference internal" href="#encoders-and-decoders">Encoders and decoders</a></li>
<li><a class="reference internal" href="#exceptions">Exceptions</a></li>
<li><a class="reference internal" href="#standard-compliance-and-interoperability">Standard Compliance and Interoperability</a><ul>
<li><a class="reference internal" href="#character-encodings">Character Encodings</a></li>
<li><a class="reference internal" href="#infinite-and-nan-number-values">Infinite and NaN Number Values</a></li>
<li><a class="reference internal" href="#repeated-names-within-an-object">Repeated Names Within an Object</a></li>
<li><a class="reference internal" href="#top-level-non-object-non-array-values">Top-level Non-Object, Non-Array Values</a></li>
<li><a class="reference internal" href="#implementation-limitations">Implementation Limitations</a></li>
</ul>
</li>
<li><a class="reference internal" href="#command-line-interface">Command Line Interface</a><ul>
<li><a class="reference internal" href="#command-line-options">Command line options</a></li>
</ul>
</li>
</ul>
</li>
</ul>

<h3>This Page</h3>
 <ul class="this-page-menu">
 <li><a href="_sources/index.txt"
 rel="nofollow">Show Source</a></li>
 </ul>
<div id="searchbox" style="display: none">
 <h3>Quick search</h3>
 <form class="search" action="search.html" method="get">
 <input type="text" name="q" />
 <input type="submit" value="Go" />
 <input type="hidden" name="check_keywords" value="yes" />
 <input type="hidden" name="area" value="default" />
 </form>
 
 Enter search terms or a module, class or function name.
 
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
 </div>
 </div>
 <div class="clearer"></div>
 </div>
 <div class="related">
 <h3>Navigation</h3>
 <ul>
 <li class="right" style="margin-right: 10px">
 <a href="genindex.html" title="General Index"
 >index</a></li>
 <li><a href="#">simplejson 3.10.0 documentation</a> &raquo;</li> 
 </ul>
 </div>
 <div class="footer">
 &copy; Copyright 2016, Bob Ippolito.
 Last updated on Mar 08, 2019.
 Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
 </div>
 </body>
</html>