<!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="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>json_util – Tools for using Python’s json module with BSON documents — PyMongo 3.7.2 documentation</title>
<link rel="stylesheet" href="../../_static/pydoctheme.css" type="text/css" />
<link rel="stylesheet" href="../../_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="../../" src="../../_static/documentation_options.js"></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>
<script type="text/javascript" src="../../_static/language_data.js"></script>
<script type="text/javascript" src="../../_static/sidebar.js"></script>
<link rel="index" title="Index" href="../../genindex.html" />
<link rel="search" title="Search" href="../../search.html" />
<link rel="next" title="max_key – Representation for the MongoDB internal MaxKey type" href="max_key.html" />
<link rel="prev" title="int64 – Tools for representing BSON int64" href="int64.html" />
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="max_key.html" title="max_key – Representation for the MongoDB internal MaxKey type"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="int64.html" title="int64 – Tools for representing BSON int64"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="../../index.html">PyMongo 3.7.2 documentation</a> »</li>
<li class="nav-item nav-item-1"><a href="../index.html" >API Documentation</a> »</li>
<li class="nav-item nav-item-2"><a href="index.html" accesskey="U"><code class="docutils literal notranslate"><span class="pre">bson</span></code> – BSON (Binary JSON) Encoding and Decoding</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="module-bson.json_util">
<span id="json-util-tools-for-using-python-s-json-module-with-bson-documents"></span><h1><code class="xref py py-mod docutils literal notranslate"><span class="pre">json_util</span></code> – Tools for using Python’s <code class="xref py py-mod docutils literal notranslate"><span class="pre">json</span></code> module with BSON documents<a class="headerlink" href="#module-bson.json_util" title="Permalink to this headline">¶</a></h1>
<p>Tools for using Python’s <code class="xref py py-mod docutils literal notranslate"><span class="pre">json</span></code> module with BSON documents.</p>
<p>This module provides two helper methods <cite>dumps</cite> and <cite>loads</cite> that wrap the
native <code class="xref py py-mod docutils literal notranslate"><span class="pre">json</span></code> methods and provide explicit BSON conversion to and from
JSON. <a class="reference internal" href="#bson.json_util.JSONOptions" title="bson.json_util.JSONOptions"><code class="xref py py-class docutils literal notranslate"><span class="pre">JSONOptions</span></code></a> provides a way to control how JSON
is emitted and parsed, with the default being the legacy PyMongo format.
<a class="reference internal" href="#module-bson.json_util" title="bson.json_util: Tools for using Python's json module with BSON documents"><code class="xref py py-mod docutils literal notranslate"><span class="pre">json_util</span></code></a> can also generate Canonical or Relaxed <a class="reference external" href="https://github.com/mongodb/specifications/blob/master/source/extended-json.rst">Extended JSON</a>
when <a class="reference internal" href="#bson.json_util.CANONICAL_JSON_OPTIONS" title="bson.json_util.CANONICAL_JSON_OPTIONS"><code class="xref py py-const docutils literal notranslate"><span class="pre">CANONICAL_JSON_OPTIONS</span></code></a> or <a class="reference internal" href="#bson.json_util.RELAXED_JSON_OPTIONS" title="bson.json_util.RELAXED_JSON_OPTIONS"><code class="xref py py-const docutils literal notranslate"><span class="pre">RELAXED_JSON_OPTIONS</span></code></a> is
provided, respectively.</p>
<p>Example usage (deserialization):</p>
<div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">bson.json_util</span> <span class="kn">import</span> <span class="n">loads</span>
<span class="gp">>>> </span><span class="n">loads</span><span class="p">(</span><span class="s1">'[{"foo": [1, 2]}, {"bar": {"hello": "world"}}, {"code": {"$scope": {}, "$code": "function x() { return 1; }"}}, {"bin": {"$type": "80", "$binary": "AQIDBA=="}}]'</span><span class="p">)</span>
<span class="go">[{u'foo': [1, 2]}, {u'bar': {u'hello': u'world'}}, {u'code': Code('function x() { return 1; }', {})}, {u'bin': Binary('...', 128)}]</span>
</pre></div>
</div>
<p>Example usage (serialization):</p>
<div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">bson</span> <span class="kn">import</span> <span class="n">Binary</span><span class="p">,</span> <span class="n">Code</span>
<span class="gp">>>> </span><span class="kn">from</span> <span class="nn">bson.json_util</span> <span class="kn">import</span> <span class="n">dumps</span>
<span class="gp">>>> </span><span class="n">dumps</span><span class="p">([{</span><span class="s1">'foo'</span><span class="p">:</span> <span class="p">[</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">]},</span>
<span class="gp">... </span> <span class="p">{</span><span class="s1">'bar'</span><span class="p">:</span> <span class="p">{</span><span class="s1">'hello'</span><span class="p">:</span> <span class="s1">'world'</span><span class="p">}},</span>
<span class="gp">... </span> <span class="p">{</span><span class="s1">'code'</span><span class="p">:</span> <span class="n">Code</span><span class="p">(</span><span class="s2">"function x() { return 1; }"</span><span class="p">,</span> <span class="p">{})},</span>
<span class="gp">... </span> <span class="p">{</span><span class="s1">'bin'</span><span class="p">:</span> <span class="n">Binary</span><span class="p">(</span><span class="sa">b</span><span class="s2">""</span><span class="p">)}])</span>
<span class="go">'[{"foo": [1, 2]}, {"bar": {"hello": "world"}}, {"code": {"$code": "function x() { return 1; }", "$scope": {}}}, {"bin": {"$binary": "AQIDBA==", "$type": "00"}}]'</span>
</pre></div>
</div>
<p>Example usage (with <a class="reference internal" href="#bson.json_util.CANONICAL_JSON_OPTIONS" title="bson.json_util.CANONICAL_JSON_OPTIONS"><code class="xref py py-const docutils literal notranslate"><span class="pre">CANONICAL_JSON_OPTIONS</span></code></a>):</p>
<div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">bson</span> <span class="kn">import</span> <span class="n">Binary</span><span class="p">,</span> <span class="n">Code</span>
<span class="gp">>>> </span><span class="kn">from</span> <span class="nn">bson.json_util</span> <span class="kn">import</span> <span class="n">dumps</span><span class="p">,</span> <span class="n">CANONICAL_JSON_OPTIONS</span>
<span class="gp">>>> </span><span class="n">dumps</span><span class="p">([{</span><span class="s1">'foo'</span><span class="p">:</span> <span class="p">[</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">]},</span>
<span class="gp">... </span> <span class="p">{</span><span class="s1">'bar'</span><span class="p">:</span> <span class="p">{</span><span class="s1">'hello'</span><span class="p">:</span> <span class="s1">'world'</span><span class="p">}},</span>
<span class="gp">... </span> <span class="p">{</span><span class="s1">'code'</span><span class="p">:</span> <span class="n">Code</span><span class="p">(</span><span class="s2">"function x() { return 1; }"</span><span class="p">)},</span>
<span class="gp">... </span> <span class="p">{</span><span class="s1">'bin'</span><span class="p">:</span> <span class="n">Binary</span><span class="p">(</span><span class="sa">b</span><span class="s2">""</span><span class="p">)}],</span>
<span class="gp">... </span> <span class="n">json_options</span><span class="o">=</span><span class="n">CANONICAL_JSON_OPTIONS</span><span class="p">)</span>
<span class="go">'[{"foo": [{"$numberInt": "1"}, {"$numberInt": "2"}]}, {"bar": {"hello": "world"}}, {"code": {"$code": "function x() { return 1; }"}}, {"bin": {"$binary": {"base64": "AQIDBA==", "subType": "00"}}}]'</span>
</pre></div>
</div>
<p>Example usage (with <a class="reference internal" href="#bson.json_util.RELAXED_JSON_OPTIONS" title="bson.json_util.RELAXED_JSON_OPTIONS"><code class="xref py py-const docutils literal notranslate"><span class="pre">RELAXED_JSON_OPTIONS</span></code></a>):</p>
<div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">bson</span> <span class="kn">import</span> <span class="n">Binary</span><span class="p">,</span> <span class="n">Code</span>
<span class="gp">>>> </span><span class="kn">from</span> <span class="nn">bson.json_util</span> <span class="kn">import</span> <span class="n">dumps</span><span class="p">,</span> <span class="n">RELAXED_JSON_OPTIONS</span>
<span class="gp">>>> </span><span class="n">dumps</span><span class="p">([{</span><span class="s1">'foo'</span><span class="p">:</span> <span class="p">[</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">]},</span>
<span class="gp">... </span> <span class="p">{</span><span class="s1">'bar'</span><span class="p">:</span> <span class="p">{</span><span class="s1">'hello'</span><span class="p">:</span> <span class="s1">'world'</span><span class="p">}},</span>
<span class="gp">... </span> <span class="p">{</span><span class="s1">'code'</span><span class="p">:</span> <span class="n">Code</span><span class="p">(</span><span class="s2">"function x() { return 1; }"</span><span class="p">)},</span>
<span class="gp">... </span> <span class="p">{</span><span class="s1">'bin'</span><span class="p">:</span> <span class="n">Binary</span><span class="p">(</span><span class="sa">b</span><span class="s2">""</span><span class="p">)}],</span>
<span class="gp">... </span> <span class="n">json_options</span><span class="o">=</span><span class="n">RELAXED_JSON_OPTIONS</span><span class="p">)</span>
<span class="go">'[{"foo": [1, 2]}, {"bar": {"hello": "world"}}, {"code": {"$code": "function x() { return 1; }"}}, {"bin": {"$binary": {"base64": "AQIDBA==", "subType": "00"}}}]'</span>
</pre></div>
</div>
<p>Alternatively, you can manually pass the <cite>default</cite> to <code class="xref py py-func docutils literal notranslate"><span class="pre">json.dumps()</span></code>.
It won’t handle <a class="reference internal" href="binary.html#bson.binary.Binary" title="bson.binary.Binary"><code class="xref py py-class docutils literal notranslate"><span class="pre">Binary</span></code></a> and <a class="reference internal" href="code.html#bson.code.Code" title="bson.code.Code"><code class="xref py py-class docutils literal notranslate"><span class="pre">Code</span></code></a>
instances (as they are extended strings you can’t provide custom defaults),
but it will be faster as there is less recursion.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">If your application does not need the flexibility offered by
<a class="reference internal" href="#bson.json_util.JSONOptions" title="bson.json_util.JSONOptions"><code class="xref py py-class docutils literal notranslate"><span class="pre">JSONOptions</span></code></a> and spends a large amount of time in the <cite>json_util</cite>
module, look to
<a class="reference external" href="https://pypi.python.org/pypi/python-bsonjs">python-bsonjs</a> for a nice
performance improvement. <cite>python-bsonjs</cite> is a fast BSON to MongoDB
Extended JSON converter for Python built on top of
<a class="reference external" href="https://github.com/mongodb/libbson">libbson</a>. <cite>python-bsonjs</cite> works best
with PyMongo when using <a class="reference internal" href="raw_bson.html#bson.raw_bson.RawBSONDocument" title="bson.raw_bson.RawBSONDocument"><code class="xref py py-class docutils literal notranslate"><span class="pre">RawBSONDocument</span></code></a>.</p>
</div>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.8: </span>The output format for <a class="reference internal" href="timestamp.html#bson.timestamp.Timestamp" title="bson.timestamp.Timestamp"><code class="xref py py-class docutils literal notranslate"><span class="pre">Timestamp</span></code></a> has changed from
‘{“t”: <int>, “i”: <int>}’ to ‘{“$timestamp”: {“t”: <int>, “i”: <int>}}’.
This new format will be decoded to an instance of
<a class="reference internal" href="timestamp.html#bson.timestamp.Timestamp" title="bson.timestamp.Timestamp"><code class="xref py py-class docutils literal notranslate"><span class="pre">Timestamp</span></code></a>. The old format will continue to be
decoded to a python dict as before. Encoding to the old format is no longer
supported as it was never correct and loses type information.
Added support for $numberLong and $undefined - new in MongoDB 2.6 - and
parsing $date in ISO-8601 format.</p>
</div>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.7: </span>Preserves order when rendering SON, Timestamp, Code, Binary, and DBRef
instances.</p>
</div>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.3: </span>Added dumps and loads helpers to automatically handle conversion to and
from json and supports <a class="reference internal" href="binary.html#bson.binary.Binary" title="bson.binary.Binary"><code class="xref py py-class docutils literal notranslate"><span class="pre">Binary</span></code></a> and
<a class="reference internal" href="code.html#bson.code.Code" title="bson.code.Code"><code class="xref py py-class docutils literal notranslate"><span class="pre">Code</span></code></a></p>
</div>
<dl class="class">
<dt id="bson.json_util.DatetimeRepresentation">
<em class="property">class </em><code class="descclassname">bson.json_util.</code><code class="descname">DatetimeRepresentation</code><a class="headerlink" href="#bson.json_util.DatetimeRepresentation" title="Permalink to this definition">¶</a></dt>
<dd><dl class="attribute">
<dt id="bson.json_util.DatetimeRepresentation.LEGACY">
<code class="descname">LEGACY</code><em class="property"> = 0</em><a class="headerlink" href="#bson.json_util.DatetimeRepresentation.LEGACY" title="Permalink to this definition">¶</a></dt>
<dd><p>Legacy MongoDB Extended JSON datetime representation.</p>
<p><code class="xref py py-class docutils literal notranslate"><span class="pre">datetime.datetime</span></code> instances will be encoded to JSON in the
format <cite>{“$date”: <dateAsMilliseconds>}</cite>, where <cite>dateAsMilliseconds</cite> is
a 64-bit signed integer giving the number of milliseconds since the Unix
epoch UTC. This was the default encoding before PyMongo version 3.4.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 3.4.</span></p>
</div>
</dd></dl>
<dl class="attribute">
<dt id="bson.json_util.DatetimeRepresentation.NUMBERLONG">
<code class="descname">NUMBERLONG</code><em class="property"> = 1</em><a class="headerlink" href="#bson.json_util.DatetimeRepresentation.NUMBERLONG" title="Permalink to this definition">¶</a></dt>
<dd><p>NumberLong datetime representation.</p>
<p><code class="xref py py-class docutils literal notranslate"><span class="pre">datetime.datetime</span></code> instances will be encoded to JSON in the
format <cite>{“$date”: {“$numberLong”: “<dateAsMilliseconds>”}}</cite>,
where <cite>dateAsMilliseconds</cite> is the string representation of a 64-bit signed
integer giving the number of milliseconds since the Unix epoch UTC.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 3.4.</span></p>
</div>
</dd></dl>
<dl class="attribute">
<dt id="bson.json_util.DatetimeRepresentation.ISO8601">
<code class="descname">ISO8601</code><em class="property"> = 2</em><a class="headerlink" href="#bson.json_util.DatetimeRepresentation.ISO8601" title="Permalink to this definition">¶</a></dt>
<dd><p>ISO-8601 datetime representation.</p>
<p><code class="xref py py-class docutils literal notranslate"><span class="pre">datetime.datetime</span></code> instances greater than or equal to the Unix
epoch UTC will be encoded to JSON in the format <cite>{“$date”: “<ISO-8601>”}</cite>.
<code class="xref py py-class docutils literal notranslate"><span class="pre">datetime.datetime</span></code> instances before the Unix epoch UTC will be
encoded as if the datetime representation is
<a class="reference internal" href="#bson.json_util.DatetimeRepresentation.NUMBERLONG" title="bson.json_util.DatetimeRepresentation.NUMBERLONG"><code class="xref py py-const docutils literal notranslate"><span class="pre">NUMBERLONG</span></code></a>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 3.4.</span></p>
</div>
</dd></dl>
</dd></dl>
<dl class="class">
<dt id="bson.json_util.JSONMode">
<em class="property">class </em><code class="descclassname">bson.json_util.</code><code class="descname">JSONMode</code><a class="headerlink" href="#bson.json_util.JSONMode" title="Permalink to this definition">¶</a></dt>
<dd><dl class="attribute">
<dt id="bson.json_util.JSONMode.LEGACY">
<code class="descname">LEGACY</code><em class="property"> = 0</em><a class="headerlink" href="#bson.json_util.JSONMode.LEGACY" title="Permalink to this definition">¶</a></dt>
<dd><p>Legacy Extended JSON representation.</p>
<p>In this mode, <a class="reference internal" href="#bson.json_util.dumps" title="bson.json_util.dumps"><code class="xref py py-func docutils literal notranslate"><span class="pre">dumps()</span></code></a> produces PyMongo’s legacy
non-standard JSON output. Consider using
<a class="reference internal" href="#bson.json_util.JSONMode.RELAXED" title="bson.json_util.JSONMode.RELAXED"><code class="xref py py-const docutils literal notranslate"><span class="pre">RELAXED</span></code></a> or
<a class="reference internal" href="#bson.json_util.JSONMode.CANONICAL" title="bson.json_util.JSONMode.CANONICAL"><code class="xref py py-const docutils literal notranslate"><span class="pre">CANONICAL</span></code></a> instead.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 3.5.</span></p>
</div>
</dd></dl>
<dl class="attribute">
<dt id="bson.json_util.JSONMode.RELAXED">
<code class="descname">RELAXED</code><em class="property"> = 1</em><a class="headerlink" href="#bson.json_util.JSONMode.RELAXED" title="Permalink to this definition">¶</a></dt>
<dd><p>Relaxed Extended JSON representation.</p>
<p>In this mode, <a class="reference internal" href="#bson.json_util.dumps" title="bson.json_util.dumps"><code class="xref py py-func docutils literal notranslate"><span class="pre">dumps()</span></code></a> produces Relaxed Extended JSON,
a mostly JSON-like format. Consider using this for things like a web API,
where one is sending a document (or a projection of a document) that only
uses ordinary JSON type primitives. In particular, the <code class="docutils literal notranslate"><span class="pre">int</span></code>,
<a class="reference internal" href="int64.html#bson.int64.Int64" title="bson.int64.Int64"><code class="xref py py-class docutils literal notranslate"><span class="pre">Int64</span></code></a>, and <code class="docutils literal notranslate"><span class="pre">float</span></code> numeric types are represented in
the native JSON number format. This output is also the most human readable
and is useful for debugging and documentation.</p>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last">The specification for Relaxed <a class="reference external" href="https://github.com/mongodb/specifications/blob/master/source/extended-json.rst">Extended JSON</a>.</p>
</div>
<div class="versionadded">
<p><span class="versionmodified">New in version 3.5.</span></p>
</div>
</dd></dl>
<dl class="attribute">
<dt id="bson.json_util.JSONMode.CANONICAL">
<code class="descname">CANONICAL</code><em class="property"> = 2</em><a class="headerlink" href="#bson.json_util.JSONMode.CANONICAL" title="Permalink to this definition">¶</a></dt>
<dd><p>Canonical Extended JSON representation.</p>
<p>In this mode, <a class="reference internal" href="#bson.json_util.dumps" title="bson.json_util.dumps"><code class="xref py py-func docutils literal notranslate"><span class="pre">dumps()</span></code></a> produces Canonical Extended
JSON, a type preserving format. Consider using this for things like
testing, where one has to precisely specify expected types in JSON. In
particular, the <code class="docutils literal notranslate"><span class="pre">int</span></code>, <a class="reference internal" href="int64.html#bson.int64.Int64" title="bson.int64.Int64"><code class="xref py py-class docutils literal notranslate"><span class="pre">Int64</span></code></a>, and <code class="docutils literal notranslate"><span class="pre">float</span></code> numeric
types are encoded with type wrappers.</p>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last">The specification for Canonical <a class="reference external" href="https://github.com/mongodb/specifications/blob/master/source/extended-json.rst">Extended JSON</a>.</p>
</div>
<div class="versionadded">
<p><span class="versionmodified">New in version 3.5.</span></p>
</div>
</dd></dl>
</dd></dl>
<dl class="class">
<dt id="bson.json_util.JSONOptions">
<em class="property">class </em><code class="descclassname">bson.json_util.</code><code class="descname">JSONOptions</code><a class="headerlink" href="#bson.json_util.JSONOptions" title="Permalink to this definition">¶</a></dt>
<dd><p>Encapsulates JSON options for <a class="reference internal" href="#bson.json_util.dumps" title="bson.json_util.dumps"><code class="xref py py-func docutils literal notranslate"><span class="pre">dumps()</span></code></a> and <a class="reference internal" href="#bson.json_util.loads" title="bson.json_util.loads"><code class="xref py py-func docutils literal notranslate"><span class="pre">loads()</span></code></a>.</p>
<p>Raises <a class="reference internal" href="../pymongo/errors.html#pymongo.errors.ConfigurationError" title="pymongo.errors.ConfigurationError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ConfigurationError</span></code></a> on Python 2.6 if
<a class="reference external" href="https://pypi.python.org/pypi/simplejson">simplejson >= 2.1.0</a> is not
installed and document_class is not the default (<code class="xref py py-class docutils literal notranslate"><span class="pre">dict</span></code>).</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><cite>strict_number_long</cite>: If <code class="docutils literal notranslate"><span class="pre">True</span></code>, <a class="reference internal" href="int64.html#bson.int64.Int64" title="bson.int64.Int64"><code class="xref py py-class docutils literal notranslate"><span class="pre">Int64</span></code></a> objects
are encoded to MongoDB Extended JSON’s <em>Strict mode</em> type
<cite>NumberLong</cite>, ie <code class="docutils literal notranslate"><span class="pre">'{"$numberLong":</span> <span class="pre">"<number>"</span> <span class="pre">}'</span></code>. Otherwise they
will be encoded as an <cite>int</cite>. Defaults to <code class="docutils literal notranslate"><span class="pre">False</span></code>.</li>
<li><cite>datetime_representation</cite>: The representation to use when encoding
instances of <code class="xref py py-class docutils literal notranslate"><span class="pre">datetime.datetime</span></code>. Defaults to
<a class="reference internal" href="#bson.json_util.DatetimeRepresentation.LEGACY" title="bson.json_util.DatetimeRepresentation.LEGACY"><code class="xref py py-const docutils literal notranslate"><span class="pre">LEGACY</span></code></a>.</li>
<li><cite>strict_uuid</cite>: If <code class="docutils literal notranslate"><span class="pre">True</span></code>, <code class="xref py py-class docutils literal notranslate"><span class="pre">uuid.UUID</span></code> object are encoded to
MongoDB Extended JSON’s <em>Strict mode</em> type <cite>Binary</cite>. Otherwise it
will be encoded as <code class="docutils literal notranslate"><span class="pre">'{"$uuid":</span> <span class="pre">"<hex>"</span> <span class="pre">}'</span></code>. Defaults to <code class="docutils literal notranslate"><span class="pre">False</span></code>.</li>
<li><cite>json_mode</cite>: The <a class="reference internal" href="#bson.json_util.JSONMode" title="bson.json_util.JSONMode"><code class="xref py py-class docutils literal notranslate"><span class="pre">JSONMode</span></code></a> to use when encoding BSON types to
Extended JSON. Defaults to <a class="reference internal" href="#bson.json_util.JSONMode.LEGACY" title="bson.json_util.JSONMode.LEGACY"><code class="xref py py-const docutils literal notranslate"><span class="pre">LEGACY</span></code></a>.</li>
<li><cite>document_class</cite>: BSON documents returned by <a class="reference internal" href="#bson.json_util.loads" title="bson.json_util.loads"><code class="xref py py-func docutils literal notranslate"><span class="pre">loads()</span></code></a> will be
decoded to an instance of this class. Must be a subclass of
<code class="xref py py-class docutils literal notranslate"><span class="pre">collections.MutableMapping</span></code>. Defaults to <code class="xref py py-class docutils literal notranslate"><span class="pre">dict</span></code>.</li>
<li><cite>uuid_representation</cite>: The BSON representation to use when encoding
and decoding instances of <code class="xref py py-class docutils literal notranslate"><span class="pre">uuid.UUID</span></code>. Defaults to
<a class="reference internal" href="binary.html#bson.binary.PYTHON_LEGACY" title="bson.binary.PYTHON_LEGACY"><code class="xref py py-const docutils literal notranslate"><span class="pre">PYTHON_LEGACY</span></code></a>.</li>
<li><cite>tz_aware</cite>: If <code class="docutils literal notranslate"><span class="pre">True</span></code>, MongoDB Extended JSON’s <em>Strict mode</em> type
<cite>Date</cite> will be decoded to timezone aware instances of
<code class="xref py py-class docutils literal notranslate"><span class="pre">datetime.datetime</span></code>. Otherwise they will be naive. Defaults
to <code class="docutils literal notranslate"><span class="pre">True</span></code>.</li>
<li><cite>tzinfo</cite>: A <code class="xref py py-class docutils literal notranslate"><span class="pre">datetime.tzinfo</span></code> subclass that specifies the
timezone from which <code class="xref py py-class docutils literal notranslate"><span class="pre">datetime</span></code> objects should be
decoded. Defaults to <a class="reference internal" href="tz_util.html#bson.tz_util.utc" title="bson.tz_util.utc"><code class="xref py py-const docutils literal notranslate"><span class="pre">utc</span></code></a>.</li>
<li><cite>args</cite>: arguments to <a class="reference internal" href="codec_options.html#bson.codec_options.CodecOptions" title="bson.codec_options.CodecOptions"><code class="xref py py-class docutils literal notranslate"><span class="pre">CodecOptions</span></code></a></li>
<li><cite>kwargs</cite>: arguments to <a class="reference internal" href="codec_options.html#bson.codec_options.CodecOptions" title="bson.codec_options.CodecOptions"><code class="xref py py-class docutils literal notranslate"><span class="pre">CodecOptions</span></code></a></li>
</ul>
</td>
</tr>
</tbody>
</table>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last">The specification for Relaxed and Canonical <a class="reference external" href="https://github.com/mongodb/specifications/blob/master/source/extended-json.rst">Extended JSON</a>.</p>
</div>
<div class="versionadded">
<p><span class="versionmodified">New in version 3.4.</span></p>
</div>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 3.5: </span>Accepts the optional parameter <cite>json_mode</cite>.</p>
</div>
</dd></dl>
<dl class="data">
<dt id="bson.json_util.LEGACY_JSON_OPTIONS">
<code class="descclassname">bson.json_util.</code><code class="descname">LEGACY_JSON_OPTIONS</code><em class="property"> = JSONOptions(strict_number_long=False, datetime_representation=0, strict_uuid=False, json_mode=0, document_class=dict, tz_aware=True, uuid_representation=PYTHON_LEGACY, unicode_decode_error_handler='strict', tzinfo=<bson.tz_util.FixedOffset object>)</em><a class="headerlink" href="#bson.json_util.LEGACY_JSON_OPTIONS" title="Permalink to this definition">¶</a></dt>
<dd><p><a class="reference internal" href="#bson.json_util.JSONOptions" title="bson.json_util.JSONOptions"><code class="xref py py-class docutils literal notranslate"><span class="pre">JSONOptions</span></code></a> for encoding to PyMongo’s legacy JSON format.</p>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last">The documentation for <a class="reference internal" href="#bson.json_util.JSONMode.LEGACY" title="bson.json_util.JSONMode.LEGACY"><code class="xref py py-const docutils literal notranslate"><span class="pre">bson.json_util.JSONMode.LEGACY</span></code></a>.</p>
</div>
<div class="versionadded">
<p><span class="versionmodified">New in version 3.5.</span></p>
</div>
</dd></dl>
<dl class="data">
<dt id="bson.json_util.DEFAULT_JSON_OPTIONS">
<code class="descclassname">bson.json_util.</code><code class="descname">DEFAULT_JSON_OPTIONS</code><em class="property"> = JSONOptions(strict_number_long=False, datetime_representation=0, strict_uuid=False, json_mode=0, document_class=dict, tz_aware=True, uuid_representation=PYTHON_LEGACY, unicode_decode_error_handler='strict', tzinfo=<bson.tz_util.FixedOffset object>)</em><a class="headerlink" href="#bson.json_util.DEFAULT_JSON_OPTIONS" title="Permalink to this definition">¶</a></dt>
<dd><p>The default <a class="reference internal" href="#bson.json_util.JSONOptions" title="bson.json_util.JSONOptions"><code class="xref py py-class docutils literal notranslate"><span class="pre">JSONOptions</span></code></a> for JSON encoding/decoding.</p>
<p>The same as <a class="reference internal" href="#bson.json_util.LEGACY_JSON_OPTIONS" title="bson.json_util.LEGACY_JSON_OPTIONS"><code class="xref py py-const docutils literal notranslate"><span class="pre">LEGACY_JSON_OPTIONS</span></code></a>. This will change to
<a class="reference internal" href="#bson.json_util.RELAXED_JSON_OPTIONS" title="bson.json_util.RELAXED_JSON_OPTIONS"><code class="xref py py-const docutils literal notranslate"><span class="pre">RELAXED_JSON_OPTIONS</span></code></a> in a future release.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 3.4.</span></p>
</div>
</dd></dl>
<dl class="data">
<dt id="bson.json_util.CANONICAL_JSON_OPTIONS">
<code class="descclassname">bson.json_util.</code><code class="descname">CANONICAL_JSON_OPTIONS</code><em class="property"> = JSONOptions(strict_number_long=True, datetime_representation=1, strict_uuid=True, json_mode=2, document_class=dict, tz_aware=True, uuid_representation=PYTHON_LEGACY, unicode_decode_error_handler='strict', tzinfo=<bson.tz_util.FixedOffset object>)</em><a class="headerlink" href="#bson.json_util.CANONICAL_JSON_OPTIONS" title="Permalink to this definition">¶</a></dt>
<dd><p><a class="reference internal" href="#bson.json_util.JSONOptions" title="bson.json_util.JSONOptions"><code class="xref py py-class docutils literal notranslate"><span class="pre">JSONOptions</span></code></a> for Canonical Extended JSON.</p>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last">The documentation for <a class="reference internal" href="#bson.json_util.JSONMode.CANONICAL" title="bson.json_util.JSONMode.CANONICAL"><code class="xref py py-const docutils literal notranslate"><span class="pre">bson.json_util.JSONMode.CANONICAL</span></code></a>.</p>
</div>
<div class="versionadded">
<p><span class="versionmodified">New in version 3.5.</span></p>
</div>
</dd></dl>
<dl class="data">
<dt id="bson.json_util.RELAXED_JSON_OPTIONS">
<code class="descclassname">bson.json_util.</code><code class="descname">RELAXED_JSON_OPTIONS</code><em class="property"> = JSONOptions(strict_number_long=False, datetime_representation=2, strict_uuid=True, json_mode=1, document_class=dict, tz_aware=True, uuid_representation=PYTHON_LEGACY, unicode_decode_error_handler='strict', tzinfo=<bson.tz_util.FixedOffset object>)</em><a class="headerlink" href="#bson.json_util.RELAXED_JSON_OPTIONS" title="Permalink to this definition">¶</a></dt>
<dd><p><a class="reference internal" href="#bson.json_util.JSONOptions" title="bson.json_util.JSONOptions"><code class="xref py py-class docutils literal notranslate"><span class="pre">JSONOptions</span></code></a> for Relaxed Extended JSON.</p>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last">The documentation for <a class="reference internal" href="#bson.json_util.JSONMode.RELAXED" title="bson.json_util.JSONMode.RELAXED"><code class="xref py py-const docutils literal notranslate"><span class="pre">bson.json_util.JSONMode.RELAXED</span></code></a>.</p>
</div>
<div class="versionadded">
<p><span class="versionmodified">New in version 3.5.</span></p>
</div>
</dd></dl>
<dl class="data">
<dt id="bson.json_util.STRICT_JSON_OPTIONS">
<code class="descclassname">bson.json_util.</code><code class="descname">STRICT_JSON_OPTIONS</code><em class="property"> = JSONOptions(strict_number_long=True, datetime_representation=2, strict_uuid=True, json_mode=0, document_class=dict, tz_aware=True, uuid_representation=PYTHON_LEGACY, unicode_decode_error_handler='strict', tzinfo=<bson.tz_util.FixedOffset object>)</em><a class="headerlink" href="#bson.json_util.STRICT_JSON_OPTIONS" title="Permalink to this definition">¶</a></dt>
<dd><p><strong>DEPRECATED</strong> - <a class="reference internal" href="#bson.json_util.JSONOptions" title="bson.json_util.JSONOptions"><code class="xref py py-class docutils literal notranslate"><span class="pre">JSONOptions</span></code></a> for MongoDB Extended JSON’s <em>Strict
mode</em> encoding.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 3.4.</span></p>
</div>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 3.5: </span>Deprecated. Use <a class="reference internal" href="#bson.json_util.RELAXED_JSON_OPTIONS" title="bson.json_util.RELAXED_JSON_OPTIONS"><code class="xref py py-const docutils literal notranslate"><span class="pre">RELAXED_JSON_OPTIONS</span></code></a> or
<a class="reference internal" href="#bson.json_util.CANONICAL_JSON_OPTIONS" title="bson.json_util.CANONICAL_JSON_OPTIONS"><code class="xref py py-const docutils literal notranslate"><span class="pre">CANONICAL_JSON_OPTIONS</span></code></a> instead.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="bson.json_util.dumps">
<code class="descclassname">bson.json_util.</code><code class="descname">dumps</code><span class="sig-paren">(</span><em>obj</em>, <em>*args</em>, <em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#bson.json_util.dumps" title="Permalink to this definition">¶</a></dt>
<dd><p>Helper function that wraps <code class="xref py py-func docutils literal notranslate"><span class="pre">json.dumps()</span></code>.</p>
<p>Recursive function that handles all BSON types including
<a class="reference internal" href="binary.html#bson.binary.Binary" title="bson.binary.Binary"><code class="xref py py-class docutils literal notranslate"><span class="pre">Binary</span></code></a> and <a class="reference internal" href="code.html#bson.code.Code" title="bson.code.Code"><code class="xref py py-class docutils literal notranslate"><span class="pre">Code</span></code></a>.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><cite>json_options</cite>: A <a class="reference internal" href="#bson.json_util.JSONOptions" title="bson.json_util.JSONOptions"><code class="xref py py-class docutils literal notranslate"><span class="pre">JSONOptions</span></code></a> instance used to modify the
encoding of MongoDB Extended JSON types. Defaults to
<a class="reference internal" href="#bson.json_util.DEFAULT_JSON_OPTIONS" title="bson.json_util.DEFAULT_JSON_OPTIONS"><code class="xref py py-const docutils literal notranslate"><span class="pre">DEFAULT_JSON_OPTIONS</span></code></a>.</li>
</ul>
</td>
</tr>
</tbody>
</table>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 3.4: </span>Accepts optional parameter <cite>json_options</cite>. See <a class="reference internal" href="#bson.json_util.JSONOptions" title="bson.json_util.JSONOptions"><code class="xref py py-class docutils literal notranslate"><span class="pre">JSONOptions</span></code></a>.</p>
</div>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.7: </span>Preserves order when rendering SON, Timestamp, Code, Binary, and DBRef
instances.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="bson.json_util.loads">
<code class="descclassname">bson.json_util.</code><code class="descname">loads</code><span class="sig-paren">(</span><em>s</em>, <em>*args</em>, <em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#bson.json_util.loads" title="Permalink to this definition">¶</a></dt>
<dd><p>Helper function that wraps <code class="xref py py-func docutils literal notranslate"><span class="pre">json.loads()</span></code>.</p>
<p>Automatically passes the object_hook for BSON type conversion.</p>
<p>Raises <code class="docutils literal notranslate"><span class="pre">TypeError</span></code>, <code class="docutils literal notranslate"><span class="pre">ValueError</span></code>, <code class="docutils literal notranslate"><span class="pre">KeyError</span></code>, or
<a class="reference internal" href="errors.html#bson.errors.InvalidId" title="bson.errors.InvalidId"><code class="xref py py-exc docutils literal notranslate"><span class="pre">InvalidId</span></code></a> on invalid MongoDB Extended JSON.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><cite>json_options</cite>: A <a class="reference internal" href="#bson.json_util.JSONOptions" title="bson.json_util.JSONOptions"><code class="xref py py-class docutils literal notranslate"><span class="pre">JSONOptions</span></code></a> instance used to modify the
decoding of MongoDB Extended JSON types. Defaults to
<a class="reference internal" href="#bson.json_util.DEFAULT_JSON_OPTIONS" title="bson.json_util.DEFAULT_JSON_OPTIONS"><code class="xref py py-const docutils literal notranslate"><span class="pre">DEFAULT_JSON_OPTIONS</span></code></a>.</li>
</ul>
</td>
</tr>
</tbody>
</table>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 3.5: </span>Parses Relaxed and Canonical Extended JSON as well as PyMongo’s legacy
format. Now raises <code class="docutils literal notranslate"><span class="pre">TypeError</span></code> or <code class="docutils literal notranslate"><span class="pre">ValueError</span></code> when parsing JSON
type wrappers with values of the wrong type or any extra keys.</p>
</div>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 3.4: </span>Accepts optional parameter <cite>json_options</cite>. See <a class="reference internal" href="#bson.json_util.JSONOptions" title="bson.json_util.JSONOptions"><code class="xref py py-class docutils literal notranslate"><span class="pre">JSONOptions</span></code></a>.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="bson.json_util.object_pairs_hook">
<code class="descclassname">bson.json_util.</code><code class="descname">object_pairs_hook</code><span class="sig-paren">(</span><em>pairs</em>, <em>json_options=JSONOptions(strict_number_long=False</em>, <em>datetime_representation=0</em>, <em>strict_uuid=False</em>, <em>json_mode=0</em>, <em>document_class=dict</em>, <em>tz_aware=True</em>, <em>uuid_representation=PYTHON_LEGACY</em>, <em>unicode_decode_error_handler='strict'</em>, <em>tzinfo=<bson.tz_util.FixedOffset object>)</em><span class="sig-paren">)</span><a class="headerlink" href="#bson.json_util.object_pairs_hook" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="function">
<dt id="bson.json_util.object_hook">
<code class="descclassname">bson.json_util.</code><code class="descname">object_hook</code><span class="sig-paren">(</span><em>dct</em>, <em>json_options=JSONOptions(strict_number_long=False</em>, <em>datetime_representation=0</em>, <em>strict_uuid=False</em>, <em>json_mode=0</em>, <em>document_class=dict</em>, <em>tz_aware=True</em>, <em>uuid_representation=PYTHON_LEGACY</em>, <em>unicode_decode_error_handler='strict'</em>, <em>tzinfo=<bson.tz_util.FixedOffset object>)</em><span class="sig-paren">)</span><a class="headerlink" href="#bson.json_util.object_hook" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="function">
<dt id="bson.json_util.default">
<code class="descclassname">bson.json_util.</code><code class="descname">default</code><span class="sig-paren">(</span><em>obj</em>, <em>json_options=JSONOptions(strict_number_long=False</em>, <em>datetime_representation=0</em>, <em>strict_uuid=False</em>, <em>json_mode=0</em>, <em>document_class=dict</em>, <em>tz_aware=True</em>, <em>uuid_representation=PYTHON_LEGACY</em>, <em>unicode_decode_error_handler='strict'</em>, <em>tzinfo=<bson.tz_util.FixedOffset object>)</em><span class="sig-paren">)</span><a class="headerlink" href="#bson.json_util.default" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h4>Previous topic</h4>
<p class="topless"><a href="int64.html"
title="previous chapter"><code class="docutils literal notranslate"><span class="pre">int64</span></code> – Tools for representing BSON int64</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="max_key.html"
title="next chapter"><code class="docutils literal notranslate"><span class="pre">max_key</span></code> – Representation for the MongoDB internal MaxKey type</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../../_sources/api/bson/json_util.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<div class="searchformwrapper">
<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>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="max_key.html" title="max_key – Representation for the MongoDB internal MaxKey type"
>next</a> |</li>
<li class="right" >
<a href="int64.html" title="int64 – Tools for representing BSON int64"
>previous</a> |</li>
<li class="nav-item nav-item-0"><a href="../../index.html">PyMongo 3.7.2 documentation</a> »</li>
<li class="nav-item nav-item-1"><a href="../index.html" >API Documentation</a> »</li>
<li class="nav-item nav-item-2"><a href="index.html" ><code class="docutils literal notranslate"><span class="pre">bson</span></code> – BSON (Binary JSON) Encoding and Decoding</a> »</li>
</ul>
</div>
<div class="footer" role="contentinfo">
© Copyright MongoDB, Inc. 2008-present. MongoDB, Mongo, and the leaf logo are registered trademarks of MongoDB, Inc.
</div>
</body>
</html>
distrib
>
Mageia
>
7
>
armv7hl
>
media
>
core-release
>
by-pkgid
>
bf9ddee8352dabf2ba1d26636a349741
>
files
>
370
