<!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>