<!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>PyMongo 3 Migration Guide — 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="Developer Guide" href="developer/index.html" />
<link rel="prev" title="Python 3 FAQ" href="python3.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="developer/index.html" title="Developer Guide"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="python3.html" title="Python 3 FAQ"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">PyMongo 3.7.2 documentation</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="pymongo-3-migration-guide">
<h1><a class="toc-backref" href="#id1">PyMongo 3 Migration Guide</a><a class="headerlink" href="#pymongo-3-migration-guide" title="Permalink to this headline">¶</a></h1>
<div class="contents topic" id="contents">
<p class="topic-title first">Contents</p>
<ul class="simple">
<li><a class="reference internal" href="#pymongo-3-migration-guide" id="id1">PyMongo 3 Migration Guide</a><ul>
<li><a class="reference internal" href="#pymongo-2-9" id="id2">PyMongo 2.9</a></li>
<li><a class="reference internal" href="#enable-deprecation-warnings" id="id3">Enable Deprecation Warnings</a></li>
<li><a class="reference internal" href="#crud-api" id="id4">CRUD API</a><ul>
<li><a class="reference internal" href="#changes-to-find-and-find-one" id="id5">Changes to find() and find_one()</a><ul>
<li><a class="reference internal" href="#spec-renamed-filter" id="id6">“spec” renamed “filter”</a></li>
<li><a class="reference internal" href="#fields-renamed-projection" id="id7">“fields” renamed “projection”</a></li>
<li><a class="reference internal" href="#partial-renamed-allow-partial-results" id="id8">“partial” renamed “allow_partial_results”</a></li>
<li><a class="reference internal" href="#timeout-replaced-by-no-cursor-timeout" id="id9">“timeout” replaced by “no_cursor_timeout”</a></li>
<li><a class="reference internal" href="#network-timeout-is-removed" id="id10">“network_timeout” is removed</a></li>
<li><a class="reference internal" href="#tailable-cursors" id="id11">Tailable cursors</a></li>
<li><a class="reference internal" href="#other-removed-options" id="id12">Other removed options</a></li>
</ul>
</li>
<li><a class="reference internal" href="#the-aggregate-method-always-returns-a-cursor" id="id13">The aggregate method always returns a cursor</a></li>
</ul>
</li>
<li><a class="reference internal" href="#read-preferences" id="id14">Read Preferences</a><ul>
<li><a class="reference internal" href="#the-slave-okay-option-is-removed" id="id15">The “slave_okay” option is removed</a></li>
<li><a class="reference internal" href="#the-read-preference-attribute-is-immutable" id="id16">The “read_preference” attribute is immutable</a></li>
<li><a class="reference internal" href="#the-tag-sets-option-and-attribute-are-removed" id="id17">The “tag_sets” option and attribute are removed</a></li>
<li><a class="reference internal" href="#the-secondary-acceptable-latency-ms-option-and-attribute-are-removed" id="id18">The “secondary_acceptable_latency_ms” option and attribute are removed</a></li>
</ul>
</li>
<li><a class="reference internal" href="#write-concern" id="id19">Write Concern</a><ul>
<li><a class="reference internal" href="#the-safe-option-is-removed" id="id20">The “safe” option is removed</a></li>
<li><a class="reference internal" href="#the-write-concern-attribute-is-immutable" id="id21">The “write_concern” attribute is immutable</a></li>
</ul>
</li>
<li><a class="reference internal" href="#codec-options" id="id22">Codec Options</a><ul>
<li><a class="reference internal" href="#the-document-class-attribute-is-removed" id="id23">The “document_class” attribute is removed</a></li>
<li><a class="reference internal" href="#the-uuid-subtype-option-and-attribute-are-removed" id="id24">The “uuid_subtype” option and attribute are removed</a></li>
</ul>
</li>
<li><a class="reference internal" href="#mongoclient" id="id25">MongoClient</a><ul>
<li><a class="reference internal" href="#mongoclient-connects-asynchronously" id="id26">MongoClient connects asynchronously</a></li>
<li><a class="reference internal" href="#the-max-pool-size-parameter-is-removed" id="id27">The max_pool_size parameter is removed</a></li>
<li><a class="reference internal" href="#the-disconnect-method-is-removed" id="id28">The “disconnect” method is removed</a></li>
<li><a class="reference internal" href="#the-host-and-port-attributes-are-removed" id="id29">The host and port attributes are removed</a></li>
</ul>
</li>
<li><a class="reference internal" href="#bson" id="id30">BSON</a><ul>
<li><a class="reference internal" href="#as-class-tz-aware-and-uuid-subtype-are-removed" id="id31">“as_class”, “tz_aware”, and “uuid_subtype” are removed</a></li>
</ul>
</li>
<li><a class="reference internal" href="#removed-features-with-no-migration-path" id="id32">Removed features with no migration path</a><ul>
<li><a class="reference internal" href="#masterslaveconnection-is-removed" id="id33">MasterSlaveConnection is removed</a></li>
<li><a class="reference internal" href="#requests-are-removed" id="id34">Requests are removed</a></li>
<li><a class="reference internal" href="#the-compile-re-option-is-removed" id="id35">The “compile_re” option is removed</a></li>
<li><a class="reference internal" href="#the-use-greenlets-option-is-removed" id="id36">The “use_greenlets” option is removed</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</div>
<p>PyMongo 3 is a partial rewrite bringing a large number of improvements. It
also brings a number of backward breaking changes. This guide provides a
roadmap for migrating an existing application from PyMongo 2.x to 3.x or
writing libraries that will work with both PyMongo 2.x and 3.x.</p>
<div class="section" id="pymongo-2-9">
<h2><a class="toc-backref" href="#id2">PyMongo 2.9</a><a class="headerlink" href="#pymongo-2-9" title="Permalink to this headline">¶</a></h2>
<p>The first step in any successful migration involves upgrading to, or
requiring, at least PyMongo 2.9. If your project has a
requirements.txt file, add the line “pymongo >= 2.9, < 3.0” until you have
completely migrated to PyMongo 3. Most of the key new
methods and options from PyMongo 3.0 are backported in PyMongo 2.9 making
migration much easier.</p>
</div>
<div class="section" id="enable-deprecation-warnings">
<h2><a class="toc-backref" href="#id3">Enable Deprecation Warnings</a><a class="headerlink" href="#enable-deprecation-warnings" title="Permalink to this headline">¶</a></h2>
<p>Starting with PyMongo 2.9, <code class="xref py py-exc docutils literal notranslate"><span class="pre">DeprecationWarning</span></code> is raised by most methods
removed in PyMongo 3.0. Make sure you enable runtime warnings to see
where deprecated functions and methods are being used in your application:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">python</span> <span class="o">-</span><span class="n">Wd</span> <span class="o"><</span><span class="n">your</span> <span class="n">application</span><span class="o">></span>
</pre></div>
</div>
<p>Warnings can also be changed to errors:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">python</span> <span class="o">-</span><span class="n">Wd</span> <span class="o">-</span><span class="n">Werror</span> <span class="o"><</span><span class="n">your</span> <span class="n">application</span><span class="o">></span>
</pre></div>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Not all deprecated features raise <code class="xref py py-exc docutils literal notranslate"><span class="pre">DeprecationWarning</span></code> when
used. For example, the <a class="reference internal" href="api/pymongo/collection.html#pymongo.collection.Collection.find" title="pymongo.collection.Collection.find"><code class="xref py py-meth docutils literal notranslate"><span class="pre">find()</span></code></a> options
renamed in PyMongo 3.0 do not raise <code class="xref py py-exc docutils literal notranslate"><span class="pre">DeprecationWarning</span></code> when used in
PyMongo 2.x. See also <a class="reference internal" href="#removed-features-with-no-migration-path">Removed features with no migration path</a>.</p>
</div>
</div>
<div class="section" id="crud-api">
<h2><a class="toc-backref" href="#id4">CRUD API</a><a class="headerlink" href="#crud-api" title="Permalink to this headline">¶</a></h2>
<div class="section" id="changes-to-find-and-find-one">
<h3><a class="toc-backref" href="#id5">Changes to find() and find_one()</a><a class="headerlink" href="#changes-to-find-and-find-one" title="Permalink to this headline">¶</a></h3>
<div class="section" id="spec-renamed-filter">
<h4><a class="toc-backref" href="#id6">“spec” renamed “filter”</a><a class="headerlink" href="#spec-renamed-filter" title="Permalink to this headline">¶</a></h4>
<p>The <cite>spec</cite> option has been renamed to <cite>filter</cite>. Code like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">cursor</span> <span class="o">=</span> <span class="n">collection</span><span class="o">.</span><span class="n">find</span><span class="p">(</span><span class="n">spec</span><span class="o">=</span><span class="p">{</span><span class="s2">"a"</span><span class="p">:</span> <span class="mi">1</span><span class="p">})</span>
</pre></div>
</div>
<p>can be changed to this with PyMongo 2.9 or later:</p>
<div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">cursor</span> <span class="o">=</span> <span class="n">collection</span><span class="o">.</span><span class="n">find</span><span class="p">(</span><span class="nb">filter</span><span class="o">=</span><span class="p">{</span><span class="s2">"a"</span><span class="p">:</span> <span class="mi">1</span><span class="p">})</span>
</pre></div>
</div>
<p>or this with any version of PyMongo:</p>
<div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">cursor</span> <span class="o">=</span> <span class="n">collection</span><span class="o">.</span><span class="n">find</span><span class="p">({</span><span class="s2">"a"</span><span class="p">:</span> <span class="mi">1</span><span class="p">})</span>
</pre></div>
</div>
</div>
<div class="section" id="fields-renamed-projection">
<h4><a class="toc-backref" href="#id7">“fields” renamed “projection”</a><a class="headerlink" href="#fields-renamed-projection" title="Permalink to this headline">¶</a></h4>
<p>The <cite>fields</cite> option has been renamed to <cite>projection</cite>. Code like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">cursor</span> <span class="o">=</span> <span class="n">collection</span><span class="o">.</span><span class="n">find</span><span class="p">({</span><span class="s2">"a"</span><span class="p">:</span> <span class="mi">1</span><span class="p">},</span> <span class="n">fields</span><span class="o">=</span><span class="p">{</span><span class="s2">"_id"</span><span class="p">:</span> <span class="kc">False</span><span class="p">})</span>
</pre></div>
</div>
<p>can be changed to this with PyMongo 2.9 or later:</p>
<div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">cursor</span> <span class="o">=</span> <span class="n">collection</span><span class="o">.</span><span class="n">find</span><span class="p">({</span><span class="s2">"a"</span><span class="p">:</span> <span class="mi">1</span><span class="p">},</span> <span class="n">projection</span><span class="o">=</span><span class="p">{</span><span class="s2">"_id"</span><span class="p">:</span> <span class="bp">False</span><span class="p">})</span>
</pre></div>
</div>
<p>or this with any version of PyMongo:</p>
<div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">cursor</span> <span class="o">=</span> <span class="n">collection</span><span class="o">.</span><span class="n">find</span><span class="p">({</span><span class="s2">"a"</span><span class="p">:</span> <span class="mi">1</span><span class="p">},</span> <span class="p">{</span><span class="s2">"_id"</span><span class="p">:</span> <span class="bp">False</span><span class="p">})</span>
</pre></div>
</div>
</div>
<div class="section" id="partial-renamed-allow-partial-results">
<h4><a class="toc-backref" href="#id8">“partial” renamed “allow_partial_results”</a><a class="headerlink" href="#partial-renamed-allow-partial-results" title="Permalink to this headline">¶</a></h4>
<p>The <cite>partial</cite> option has been renamed to <cite>allow_partial_results</cite>. Code like
this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">cursor</span> <span class="o">=</span> <span class="n">collection</span><span class="o">.</span><span class="n">find</span><span class="p">({</span><span class="s2">"a"</span><span class="p">:</span> <span class="mi">1</span><span class="p">},</span> <span class="n">partial</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
</pre></div>
</div>
<p>can be changed to this with PyMongo 2.9 or later:</p>
<div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">cursor</span> <span class="o">=</span> <span class="n">collection</span><span class="o">.</span><span class="n">find</span><span class="p">({</span><span class="s2">"a"</span><span class="p">:</span> <span class="mi">1</span><span class="p">},</span> <span class="n">allow_partial_results</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
</pre></div>
</div>
</div>
<div class="section" id="timeout-replaced-by-no-cursor-timeout">
<h4><a class="toc-backref" href="#id9">“timeout” replaced by “no_cursor_timeout”</a><a class="headerlink" href="#timeout-replaced-by-no-cursor-timeout" title="Permalink to this headline">¶</a></h4>
<p>The <cite>timeout</cite> option has been replaced by <cite>no_cursor_timeout</cite>. Code like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">cursor</span> <span class="o">=</span> <span class="n">collection</span><span class="o">.</span><span class="n">find</span><span class="p">({</span><span class="s2">"a"</span><span class="p">:</span> <span class="mi">1</span><span class="p">},</span> <span class="n">timeout</span><span class="o">=</span><span class="kc">False</span><span class="p">)</span>
</pre></div>
</div>
<p>can be changed to this with PyMongo 2.9 or later:</p>
<div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">cursor</span> <span class="o">=</span> <span class="n">collection</span><span class="o">.</span><span class="n">find</span><span class="p">({</span><span class="s2">"a"</span><span class="p">:</span> <span class="mi">1</span><span class="p">},</span> <span class="n">no_cursor_timeout</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
</pre></div>
</div>
</div>
<div class="section" id="network-timeout-is-removed">
<h4><a class="toc-backref" href="#id10">“network_timeout” is removed</a><a class="headerlink" href="#network-timeout-is-removed" title="Permalink to this headline">¶</a></h4>
<p>The <cite>network_timeout</cite> option has been removed. This option was always the
wrong solution for timing out long running queries and should never be used
in production. Starting with <strong>MongoDB 2.6</strong> you can use the $maxTimeMS query
modifier. Code like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># Set a 5 second select() timeout.</span>
<span class="o">>>></span> <span class="n">cursor</span> <span class="o">=</span> <span class="n">collection</span><span class="o">.</span><span class="n">find</span><span class="p">({</span><span class="s2">"a"</span><span class="p">:</span> <span class="mi">1</span><span class="p">},</span> <span class="n">network_timeout</span><span class="o">=</span><span class="mi">5</span><span class="p">)</span>
</pre></div>
</div>
<p>can be changed to this with PyMongo 2.9 or later:</p>
<div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="go"># Set a 5 second (5000 millisecond) server side query timeout.</span>
<span class="gp">>>> </span><span class="n">cursor</span> <span class="o">=</span> <span class="n">collection</span><span class="o">.</span><span class="n">find</span><span class="p">({</span><span class="s2">"a"</span><span class="p">:</span> <span class="mi">1</span><span class="p">},</span> <span class="n">modifiers</span><span class="o">=</span><span class="p">{</span><span class="s2">"$maxTimeMS"</span><span class="p">:</span> <span class="mi">5000</span><span class="p">})</span>
</pre></div>
</div>
<p>or with PyMongo 3.5 or later:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">cursor</span> <span class="o">=</span> <span class="n">collection</span><span class="o">.</span><span class="n">find</span><span class="p">({</span><span class="s2">"a"</span><span class="p">:</span> <span class="mi">1</span><span class="p">},</span> <span class="n">max_time_ms</span><span class="o">=</span><span class="mi">5000</span><span class="p">)</span>
</pre></div>
</div>
<p>or with any version of PyMongo:</p>
<div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">cursor</span> <span class="o">=</span> <span class="n">collection</span><span class="o">.</span><span class="n">find</span><span class="p">({</span><span class="s2">"$query"</span><span class="p">:</span> <span class="p">{</span><span class="s2">"a"</span><span class="p">:</span> <span class="mi">1</span><span class="p">},</span> <span class="s2">"$maxTimeMS"</span><span class="p">:</span> <span class="mi">5000</span><span class="p">})</span>
</pre></div>
</div>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last"><a class="reference external" href="http://docs.mongodb.org/manual/reference/operator/meta/maxTimeMS/">$maxTimeMS</a></p>
</div>
</div>
<div class="section" id="tailable-cursors">
<h4><a class="toc-backref" href="#id11">Tailable cursors</a><a class="headerlink" href="#tailable-cursors" title="Permalink to this headline">¶</a></h4>
<p>The <cite>tailable</cite> and <cite>await_data</cite> options have been replaced by <cite>cursor_type</cite>.
Code like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">cursor</span> <span class="o">=</span> <span class="n">collection</span><span class="o">.</span><span class="n">find</span><span class="p">({</span><span class="s2">"a"</span><span class="p">:</span> <span class="mi">1</span><span class="p">},</span> <span class="n">tailable</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">cursor</span> <span class="o">=</span> <span class="n">collection</span><span class="o">.</span><span class="n">find</span><span class="p">({</span><span class="s2">"a"</span><span class="p">:</span> <span class="mi">1</span><span class="p">},</span> <span class="n">tailable</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span> <span class="n">await_data</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
</pre></div>
</div>
<p>can be changed to this with PyMongo 2.9 or later:</p>
<div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">pymongo</span> <span class="kn">import</span> <span class="n">CursorType</span>
<span class="gp">>>> </span><span class="n">cursor</span> <span class="o">=</span> <span class="n">collection</span><span class="o">.</span><span class="n">find</span><span class="p">({</span><span class="s2">"a"</span><span class="p">:</span> <span class="mi">1</span><span class="p">},</span> <span class="n">cursor_type</span><span class="o">=</span><span class="n">CursorType</span><span class="o">.</span><span class="n">TAILABLE</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">cursor</span> <span class="o">=</span> <span class="n">collection</span><span class="o">.</span><span class="n">find</span><span class="p">({</span><span class="s2">"a"</span><span class="p">:</span> <span class="mi">1</span><span class="p">},</span> <span class="n">cursor_type</span><span class="o">=</span><span class="n">CursorType</span><span class="o">.</span><span class="n">TAILABLE_AWAIT</span><span class="p">)</span>
</pre></div>
</div>
</div>
<div class="section" id="other-removed-options">
<h4><a class="toc-backref" href="#id12">Other removed options</a><a class="headerlink" href="#other-removed-options" title="Permalink to this headline">¶</a></h4>
<p>The <cite>slave_okay</cite>, <cite>read_preference</cite>, <cite>tag_sets</cite>,
and <cite>secondary_acceptable_latency_ms</cite> options have been removed. See the <a class="reference internal" href="#read-preferences">Read
Preferences</a> section for solutions.</p>
</div>
</div>
<div class="section" id="the-aggregate-method-always-returns-a-cursor">
<h3><a class="toc-backref" href="#id13">The aggregate method always returns a cursor</a><a class="headerlink" href="#the-aggregate-method-always-returns-a-cursor" title="Permalink to this headline">¶</a></h3>
<p>PyMongo 2.6 added an option to return an iterable cursor from
<a class="reference internal" href="api/pymongo/collection.html#pymongo.collection.Collection.aggregate" title="pymongo.collection.Collection.aggregate"><code class="xref py py-meth docutils literal notranslate"><span class="pre">aggregate()</span></code></a>. In PyMongo 3
<a class="reference internal" href="api/pymongo/collection.html#pymongo.collection.Collection.aggregate" title="pymongo.collection.Collection.aggregate"><code class="xref py py-meth docutils literal notranslate"><span class="pre">aggregate()</span></code></a> always returns a cursor. Use
the <cite>cursor</cite> option for consistent behavior with PyMongo 2.9 and later:</p>
<div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="k">for</span> <span class="n">result</span> <span class="ow">in</span> <span class="n">collection</span><span class="o">.</span><span class="n">aggregate</span><span class="p">([],</span> <span class="n">cursor</span><span class="o">=</span><span class="p">{}):</span>
<span class="gp">... </span> <span class="k">pass</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="read-preferences">
<h2><a class="toc-backref" href="#id14">Read Preferences</a><a class="headerlink" href="#read-preferences" title="Permalink to this headline">¶</a></h2>
<div class="section" id="the-slave-okay-option-is-removed">
<h3><a class="toc-backref" href="#id15">The “slave_okay” option is removed</a><a class="headerlink" href="#the-slave-okay-option-is-removed" title="Permalink to this headline">¶</a></h3>
<p>The <cite>slave_okay</cite> option is removed from PyMongo’s API. The
secondaryPreferred read preference provides the same behavior.
Code like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">client</span> <span class="o">=</span> <span class="n">MongoClient</span><span class="p">(</span><span class="n">slave_okay</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
</pre></div>
</div>
<p>can be changed to this with PyMongo 2.9 or newer:</p>
<div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">client</span> <span class="o">=</span> <span class="n">MongoClient</span><span class="p">(</span><span class="n">readPreference</span><span class="o">=</span><span class="s2">"secondaryPreferred"</span><span class="p">)</span>
</pre></div>
</div>
</div>
<div class="section" id="the-read-preference-attribute-is-immutable">
<h3><a class="toc-backref" href="#id16">The “read_preference” attribute is immutable</a><a class="headerlink" href="#the-read-preference-attribute-is-immutable" title="Permalink to this headline">¶</a></h3>
<p>Code like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">pymongo</span> <span class="k">import</span> <span class="n">ReadPreference</span>
<span class="gp">>>> </span><span class="n">db</span> <span class="o">=</span> <span class="n">client</span><span class="o">.</span><span class="n">my_database</span>
<span class="gp">>>> </span><span class="n">db</span><span class="o">.</span><span class="n">read_preference</span> <span class="o">=</span> <span class="n">ReadPreference</span><span class="o">.</span><span class="n">SECONDARY</span>
</pre></div>
</div>
<p>can be changed to this with PyMongo 2.9 or later:</p>
<div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">db</span> <span class="o">=</span> <span class="n">client</span><span class="o">.</span><span class="n">get_database</span><span class="p">(</span><span class="s2">"my_database"</span><span class="p">,</span>
<span class="gp">... </span> <span class="n">read_preference</span><span class="o">=</span><span class="n">ReadPreference</span><span class="o">.</span><span class="n">SECONDARY</span><span class="p">)</span>
</pre></div>
</div>
<p>Code like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">cursor</span> <span class="o">=</span> <span class="n">collection</span><span class="o">.</span><span class="n">find</span><span class="p">({</span><span class="s2">"a"</span><span class="p">:</span> <span class="mi">1</span><span class="p">},</span>
<span class="gp">... </span> <span class="n">read_preference</span><span class="o">=</span><span class="n">ReadPreference</span><span class="o">.</span><span class="n">SECONDARY</span><span class="p">)</span>
</pre></div>
</div>
<p>can be changed to this with PyMongo 2.9 or later:</p>
<div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">coll2</span> <span class="o">=</span> <span class="n">collection</span><span class="o">.</span><span class="n">with_options</span><span class="p">(</span><span class="n">read_preference</span><span class="o">=</span><span class="n">ReadPreference</span><span class="o">.</span><span class="n">SECONDARY</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">cursor</span> <span class="o">=</span> <span class="n">coll2</span><span class="o">.</span><span class="n">find</span><span class="p">({</span><span class="s2">"a"</span><span class="p">:</span> <span class="mi">1</span><span class="p">})</span>
</pre></div>
</div>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last"><a class="reference internal" href="api/pymongo/database.html#pymongo.database.Database.get_collection" title="pymongo.database.Database.get_collection"><code class="xref py py-meth docutils literal notranslate"><span class="pre">get_collection()</span></code></a></p>
</div>
</div>
<div class="section" id="the-tag-sets-option-and-attribute-are-removed">
<h3><a class="toc-backref" href="#id17">The “tag_sets” option and attribute are removed</a><a class="headerlink" href="#the-tag-sets-option-and-attribute-are-removed" title="Permalink to this headline">¶</a></h3>
<p>The <cite>tag_sets</cite> MongoClient option is removed. The <cite>read_preference</cite>
option can be used instead. Code like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">client</span> <span class="o">=</span> <span class="n">MongoClient</span><span class="p">(</span>
<span class="gp">... </span> <span class="n">read_preference</span><span class="o">=</span><span class="n">ReadPreference</span><span class="o">.</span><span class="n">SECONDARY</span><span class="p">,</span>
<span class="gp">... </span> <span class="n">tag_sets</span><span class="o">=</span><span class="p">[{</span><span class="s2">"dc"</span><span class="p">:</span> <span class="s2">"ny"</span><span class="p">},</span> <span class="p">{</span><span class="s2">"dc"</span><span class="p">:</span> <span class="s2">"sf"</span><span class="p">}])</span>
</pre></div>
</div>
<p>can be changed to this with PyMongo 2.9 or later:</p>
<div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">pymongo.read_preferences</span> <span class="kn">import</span> <span class="n">Secondary</span>
<span class="gp">>>> </span><span class="n">client</span> <span class="o">=</span> <span class="n">MongoClient</span><span class="p">(</span><span class="n">read_preference</span><span class="o">=</span><span class="n">Secondary</span><span class="p">([{</span><span class="s2">"dc"</span><span class="p">:</span> <span class="s2">"ny"</span><span class="p">}]))</span>
</pre></div>
</div>
<p>To change the tags sets for a Database or Collection, code like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">db</span> <span class="o">=</span> <span class="n">client</span><span class="o">.</span><span class="n">my_database</span>
<span class="gp">>>> </span><span class="n">db</span><span class="o">.</span><span class="n">read_preference</span> <span class="o">=</span> <span class="n">ReadPreference</span><span class="o">.</span><span class="n">SECONDARY</span>
<span class="gp">>>> </span><span class="n">db</span><span class="o">.</span><span class="n">tag_sets</span> <span class="o">=</span> <span class="p">[{</span><span class="s2">"dc"</span><span class="p">:</span> <span class="s2">"ny"</span><span class="p">}]</span>
</pre></div>
</div>
<p>can be changed to this with PyMongo 2.9 or later:</p>
<div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">db</span> <span class="o">=</span> <span class="n">client</span><span class="o">.</span><span class="n">get_database</span><span class="p">(</span><span class="s2">"my_database"</span><span class="p">,</span>
<span class="gp">... </span> <span class="n">read_preference</span><span class="o">=</span><span class="n">Secondary</span><span class="p">([{</span><span class="s2">"dc"</span><span class="p">:</span> <span class="s2">"ny"</span><span class="p">}]))</span>
</pre></div>
</div>
<p>Code like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">cursor</span> <span class="o">=</span> <span class="n">collection</span><span class="o">.</span><span class="n">find</span><span class="p">(</span>
<span class="gp">... </span> <span class="p">{</span><span class="s2">"a"</span><span class="p">:</span> <span class="mi">1</span><span class="p">},</span>
<span class="gp">... </span> <span class="n">read_preference</span><span class="o">=</span><span class="n">ReadPreference</span><span class="o">.</span><span class="n">SECONDARY</span><span class="p">,</span>
<span class="gp">... </span> <span class="n">tag_sets</span><span class="o">=</span><span class="p">[{</span><span class="s2">"dc"</span><span class="p">:</span> <span class="s2">"ny"</span><span class="p">}])</span>
</pre></div>
</div>
<p>can be changed to this with PyMongo 2.9 or later:</p>
<div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">pymongo.read_preferences</span> <span class="kn">import</span> <span class="n">Secondary</span>
<span class="gp">>>> </span><span class="n">coll2</span> <span class="o">=</span> <span class="n">collection</span><span class="o">.</span><span class="n">with_options</span><span class="p">(</span>
<span class="gp">... </span> <span class="n">read_preference</span><span class="o">=</span><span class="n">Secondary</span><span class="p">([{</span><span class="s2">"dc"</span><span class="p">:</span> <span class="s2">"ny"</span><span class="p">}]))</span>
<span class="gp">>>> </span><span class="n">cursor</span> <span class="o">=</span> <span class="n">coll2</span><span class="o">.</span><span class="n">find</span><span class="p">({</span><span class="s2">"a"</span><span class="p">:</span> <span class="mi">1</span><span class="p">})</span>
</pre></div>
</div>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last"><a class="reference internal" href="api/pymongo/database.html#pymongo.database.Database.get_collection" title="pymongo.database.Database.get_collection"><code class="xref py py-meth docutils literal notranslate"><span class="pre">get_collection()</span></code></a></p>
</div>
</div>
<div class="section" id="the-secondary-acceptable-latency-ms-option-and-attribute-are-removed">
<h3><a class="toc-backref" href="#id18">The “secondary_acceptable_latency_ms” option and attribute are removed</a><a class="headerlink" href="#the-secondary-acceptable-latency-ms-option-and-attribute-are-removed" title="Permalink to this headline">¶</a></h3>
<p>PyMongo 2.x supports <cite>secondary_acceptable_latency_ms</cite> as an option to methods
throughout the driver, but mongos only supports a global latency option.
PyMongo 3.x has changed to match the behavior of mongos, allowing migration
from a single server, to a replica set, to a sharded cluster without a
surprising change in server selection behavior. A new option,
<cite>localThresholdMS</cite>, is available through MongoClient and should be used in
place of <cite>secondaryAcceptableLatencyMS</cite>. Code like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">client</span> <span class="o">=</span> <span class="n">MongoClient</span><span class="p">(</span><span class="n">readPreference</span><span class="o">=</span><span class="s2">"nearest"</span><span class="p">,</span>
<span class="gp">... </span> <span class="n">secondaryAcceptableLatencyMS</span><span class="o">=</span><span class="mi">100</span><span class="p">)</span>
</pre></div>
</div>
<p>can be changed to this with PyMongo 2.9 or later:</p>
<div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">client</span> <span class="o">=</span> <span class="n">MongoClient</span><span class="p">(</span><span class="n">readPreference</span><span class="o">=</span><span class="s2">"nearest"</span><span class="p">,</span>
<span class="gp">... </span> <span class="n">localThresholdMS</span><span class="o">=</span><span class="mi">100</span><span class="p">)</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="write-concern">
<h2><a class="toc-backref" href="#id19">Write Concern</a><a class="headerlink" href="#write-concern" title="Permalink to this headline">¶</a></h2>
<div class="section" id="the-safe-option-is-removed">
<h3><a class="toc-backref" href="#id20">The “safe” option is removed</a><a class="headerlink" href="#the-safe-option-is-removed" title="Permalink to this headline">¶</a></h3>
<p>In PyMongo 3 the <cite>safe</cite> option is removed from the entire API.
<a class="reference internal" href="api/pymongo/mongo_client.html#pymongo.mongo_client.MongoClient" title="pymongo.mongo_client.MongoClient"><code class="xref py py-class docutils literal notranslate"><span class="pre">MongoClient</span></code></a> has always defaulted to acknowledged
write operations and continues to do so in PyMongo 3.</p>
</div>
<div class="section" id="the-write-concern-attribute-is-immutable">
<h3><a class="toc-backref" href="#id21">The “write_concern” attribute is immutable</a><a class="headerlink" href="#the-write-concern-attribute-is-immutable" title="Permalink to this headline">¶</a></h3>
<p>The <cite>write_concern</cite> attribute is immutable in PyMongo 3. Code like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">client</span> <span class="o">=</span> <span class="n">MongoClient</span><span class="p">()</span>
<span class="gp">>>> </span><span class="n">client</span><span class="o">.</span><span class="n">write_concern</span> <span class="o">=</span> <span class="p">{</span><span class="s2">"w"</span><span class="p">:</span> <span class="s2">"majority"</span><span class="p">}</span>
</pre></div>
</div>
<p>can be changed to this with any version of PyMongo:</p>
<div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">client</span> <span class="o">=</span> <span class="n">MongoClient</span><span class="p">(</span><span class="n">w</span><span class="o">=</span><span class="s2">"majority"</span><span class="p">)</span>
</pre></div>
</div>
<p>Code like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">db</span> <span class="o">=</span> <span class="n">client</span><span class="o">.</span><span class="n">my_database</span>
<span class="gp">>>> </span><span class="n">db</span><span class="o">.</span><span class="n">write_concern</span> <span class="o">=</span> <span class="p">{</span><span class="s2">"w"</span><span class="p">:</span> <span class="s2">"majority"</span><span class="p">}</span>
</pre></div>
</div>
<p>can be changed to this with PyMongo 2.9 or later:</p>
<div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">pymongo</span> <span class="kn">import</span> <span class="n">WriteConcern</span>
<span class="gp">>>> </span><span class="n">db</span> <span class="o">=</span> <span class="n">client</span><span class="o">.</span><span class="n">get_database</span><span class="p">(</span><span class="s2">"my_database"</span><span class="p">,</span>
<span class="gp">... </span> <span class="n">write_concern</span><span class="o">=</span><span class="n">WriteConcern</span><span class="p">(</span><span class="n">w</span><span class="o">=</span><span class="s2">"majority"</span><span class="p">))</span>
</pre></div>
</div>
<p>The new CRUD API write methods do not accept write concern options. Code like
this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">oid</span> <span class="o">=</span> <span class="n">collection</span><span class="o">.</span><span class="n">insert</span><span class="p">({</span><span class="s2">"a"</span><span class="p">:</span> <span class="mi">2</span><span class="p">},</span> <span class="n">w</span><span class="o">=</span><span class="s2">"majority"</span><span class="p">)</span>
</pre></div>
</div>
<p>can be changed to this with PyMongo 2.9 or later:</p>
<div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">pymongo</span> <span class="kn">import</span> <span class="n">WriteConcern</span>
<span class="gp">>>> </span><span class="n">coll2</span> <span class="o">=</span> <span class="n">collection</span><span class="o">.</span><span class="n">with_options</span><span class="p">(</span>
<span class="gp">... </span> <span class="n">write_concern</span><span class="o">=</span><span class="n">WriteConcern</span><span class="p">(</span><span class="n">w</span><span class="o">=</span><span class="s2">"majority"</span><span class="p">))</span>
<span class="gp">>>> </span><span class="n">oid</span> <span class="o">=</span> <span class="n">coll2</span><span class="o">.</span><span class="n">insert</span><span class="p">({</span><span class="s2">"a"</span><span class="p">:</span> <span class="mi">2</span><span class="p">})</span>
</pre></div>
</div>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last"><a class="reference internal" href="api/pymongo/database.html#pymongo.database.Database.get_collection" title="pymongo.database.Database.get_collection"><code class="xref py py-meth docutils literal notranslate"><span class="pre">get_collection()</span></code></a></p>
</div>
</div>
</div>
<div class="section" id="codec-options">
<h2><a class="toc-backref" href="#id22">Codec Options</a><a class="headerlink" href="#codec-options" title="Permalink to this headline">¶</a></h2>
<div class="section" id="the-document-class-attribute-is-removed">
<h3><a class="toc-backref" href="#id23">The “document_class” attribute is removed</a><a class="headerlink" href="#the-document-class-attribute-is-removed" title="Permalink to this headline">¶</a></h3>
<p>Code like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">bson.son</span> <span class="k">import</span> <span class="n">SON</span>
<span class="gp">>>> </span><span class="n">client</span> <span class="o">=</span> <span class="n">MongoClient</span><span class="p">()</span>
<span class="gp">>>> </span><span class="n">client</span><span class="o">.</span><span class="n">document_class</span> <span class="o">=</span> <span class="n">SON</span>
</pre></div>
</div>
<p>can be replaced by this in any version of PyMongo:</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.son</span> <span class="kn">import</span> <span class="n">SON</span>
<span class="gp">>>> </span><span class="n">client</span> <span class="o">=</span> <span class="n">MongoClient</span><span class="p">(</span><span class="n">document_class</span><span class="o">=</span><span class="n">SON</span><span class="p">)</span>
</pre></div>
</div>
<p>or to change the <cite>document_class</cite> for a <a class="reference internal" href="api/pymongo/database.html#pymongo.database.Database" title="pymongo.database.Database"><code class="xref py py-class docutils literal notranslate"><span class="pre">Database</span></code></a>
with PyMongo 2.9 or later:</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.codec_options</span> <span class="kn">import</span> <span class="n">CodecOptions</span>
<span class="gp">>>> </span><span class="kn">from</span> <span class="nn">bson.son</span> <span class="kn">import</span> <span class="n">SON</span>
<span class="gp">>>> </span><span class="n">db</span> <span class="o">=</span> <span class="n">client</span><span class="o">.</span><span class="n">get_database</span><span class="p">(</span><span class="s2">"my_database"</span><span class="p">,</span> <span class="n">CodecOptions</span><span class="p">(</span><span class="n">SON</span><span class="p">))</span>
</pre></div>
</div>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last"><a class="reference internal" href="api/pymongo/database.html#pymongo.database.Database.get_collection" title="pymongo.database.Database.get_collection"><code class="xref py py-meth docutils literal notranslate"><span class="pre">get_collection()</span></code></a> and
<a class="reference internal" href="api/pymongo/collection.html#pymongo.collection.Collection.with_options" title="pymongo.collection.Collection.with_options"><code class="xref py py-meth docutils literal notranslate"><span class="pre">with_options()</span></code></a></p>
</div>
</div>
<div class="section" id="the-uuid-subtype-option-and-attribute-are-removed">
<h3><a class="toc-backref" href="#id24">The “uuid_subtype” option and attribute are removed</a><a class="headerlink" href="#the-uuid-subtype-option-and-attribute-are-removed" title="Permalink to this headline">¶</a></h3>
<p>Code like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">bson.binary</span> <span class="k">import</span> <span class="n">JAVA_LEGACY</span>
<span class="gp">>>> </span><span class="n">db</span> <span class="o">=</span> <span class="n">client</span><span class="o">.</span><span class="n">my_database</span>
<span class="gp">>>> </span><span class="n">db</span><span class="o">.</span><span class="n">uuid_subtype</span> <span class="o">=</span> <span class="n">JAVA_LEGACY</span>
</pre></div>
</div>
<p>can be replaced by this with PyMongo 2.9 or later:</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.binary</span> <span class="kn">import</span> <span class="n">JAVA_LEGACY</span>
<span class="gp">>>> </span><span class="kn">from</span> <span class="nn">bson.codec_options</span> <span class="kn">import</span> <span class="n">CodecOptions</span>
<span class="gp">>>> </span><span class="n">db</span> <span class="o">=</span> <span class="n">client</span><span class="o">.</span><span class="n">get_database</span><span class="p">(</span><span class="s2">"my_database"</span><span class="p">,</span>
<span class="gp">... </span> <span class="n">CodecOptions</span><span class="p">(</span><span class="n">uuid_representation</span><span class="o">=</span><span class="n">JAVA_LEGACY</span><span class="p">))</span>
</pre></div>
</div>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last"><a class="reference internal" href="api/pymongo/database.html#pymongo.database.Database.get_collection" title="pymongo.database.Database.get_collection"><code class="xref py py-meth docutils literal notranslate"><span class="pre">get_collection()</span></code></a> and
<a class="reference internal" href="api/pymongo/collection.html#pymongo.collection.Collection.with_options" title="pymongo.collection.Collection.with_options"><code class="xref py py-meth docutils literal notranslate"><span class="pre">with_options()</span></code></a></p>
</div>
</div>
</div>
<div class="section" id="mongoclient">
<h2><a class="toc-backref" href="#id25">MongoClient</a><a class="headerlink" href="#mongoclient" title="Permalink to this headline">¶</a></h2>
<div class="section" id="mongoclient-connects-asynchronously">
<h3><a class="toc-backref" href="#id26">MongoClient connects asynchronously</a><a class="headerlink" href="#mongoclient-connects-asynchronously" title="Permalink to this headline">¶</a></h3>
<p>In PyMongo 3, the <a class="reference internal" href="api/pymongo/mongo_client.html#pymongo.mongo_client.MongoClient" title="pymongo.mongo_client.MongoClient"><code class="xref py py-class docutils literal notranslate"><span class="pre">MongoClient</span></code></a> constructor no
longer blocks while connecting to the server or servers, and it no longer
raises <a class="reference internal" href="api/pymongo/errors.html#pymongo.errors.ConnectionFailure" title="pymongo.errors.ConnectionFailure"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ConnectionFailure</span></code></a> if they are unavailable, nor
<a class="reference internal" href="api/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> if the user’s credentials are wrong.
Instead, the constructor returns immediately and launches the connection
process on background threads. The <cite>connect</cite> option is added to control whether
these threads are started immediately, or when the client is first used.</p>
<p>For consistent behavior in PyMongo 2.x and PyMongo 3.x, code like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">pymongo.errors</span> <span class="k">import</span> <span class="n">ConnectionFailure</span>
<span class="gp">>>> </span><span class="k">try</span><span class="p">:</span>
<span class="gp">... </span> <span class="n">client</span> <span class="o">=</span> <span class="n">MongoClient</span><span class="p">()</span>
<span class="gp">... </span><span class="k">except</span> <span class="n">ConnectionFailure</span><span class="p">:</span>
<span class="gp">... </span> <span class="nb">print</span><span class="p">(</span><span class="s2">"Server not available"</span><span class="p">)</span>
<span class="go">>>></span>
</pre></div>
</div>
<p>can be changed to this with PyMongo 2.9 or later:</p>
<div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">pymongo.errors</span> <span class="kn">import</span> <span class="n">ConnectionFailure</span>
<span class="gp">>>> </span><span class="n">client</span> <span class="o">=</span> <span class="n">MongoClient</span><span class="p">(</span><span class="n">connect</span><span class="o">=</span><span class="bp">False</span><span class="p">)</span>
<span class="gp">>>> </span><span class="k">try</span><span class="p">:</span>
<span class="gp">... </span> <span class="n">result</span> <span class="o">=</span> <span class="n">client</span><span class="o">.</span><span class="n">admin</span><span class="o">.</span><span class="n">command</span><span class="p">(</span><span class="s2">"ismaster"</span><span class="p">)</span>
<span class="gp">... </span><span class="k">except</span> <span class="n">ConnectionFailure</span><span class="p">:</span>
<span class="gp">... </span> <span class="k">print</span><span class="p">(</span><span class="s2">"Server not available"</span><span class="p">)</span>
<span class="go">>>></span>
</pre></div>
</div>
<p>Any operation can be used to determine if the server is available. We choose
the “ismaster” command here because it is cheap and does not require auth, so
it is a simple way to check whether the server is available.</p>
</div>
<div class="section" id="the-max-pool-size-parameter-is-removed">
<h3><a class="toc-backref" href="#id27">The max_pool_size parameter is removed</a><a class="headerlink" href="#the-max-pool-size-parameter-is-removed" title="Permalink to this headline">¶</a></h3>
<p>PyMongo 3 replaced the max_pool_size parameter with support for the MongoDB URI
<cite>maxPoolSize</cite> option. Code like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">client</span> <span class="o">=</span> <span class="n">MongoClient</span><span class="p">(</span><span class="n">max_pool_size</span><span class="o">=</span><span class="mi">10</span><span class="p">)</span>
</pre></div>
</div>
<p>can be replaced by this with PyMongo 2.9 or later:</p>
<div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">client</span> <span class="o">=</span> <span class="n">MongoClient</span><span class="p">(</span><span class="n">maxPoolSize</span><span class="o">=</span><span class="mi">10</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">client</span> <span class="o">=</span> <span class="n">MongoClient</span><span class="p">(</span><span class="s2">"mongodb://localhost:27017/?maxPoolSize=10"</span><span class="p">)</span>
</pre></div>
</div>
</div>
<div class="section" id="the-disconnect-method-is-removed">
<h3><a class="toc-backref" href="#id28">The “disconnect” method is removed</a><a class="headerlink" href="#the-disconnect-method-is-removed" title="Permalink to this headline">¶</a></h3>
<p>Code like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">client</span><span class="o">.</span><span class="n">disconnect</span><span class="p">()</span>
</pre></div>
</div>
<p>can be replaced by this with PyMongo 2.9 or later:</p>
<div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">client</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>
</pre></div>
</div>
</div>
<div class="section" id="the-host-and-port-attributes-are-removed">
<h3><a class="toc-backref" href="#id29">The host and port attributes are removed</a><a class="headerlink" href="#the-host-and-port-attributes-are-removed" title="Permalink to this headline">¶</a></h3>
<p>Code like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">host</span> <span class="o">=</span> <span class="n">client</span><span class="o">.</span><span class="n">host</span>
<span class="gp">>>> </span><span class="n">port</span> <span class="o">=</span> <span class="n">client</span><span class="o">.</span><span class="n">port</span>
</pre></div>
</div>
<p>can be replaced by this with PyMongo 2.9 or later:</p>
<div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">address</span> <span class="o">=</span> <span class="n">client</span><span class="o">.</span><span class="n">address</span>
<span class="gp">>>> </span><span class="n">host</span><span class="p">,</span> <span class="n">port</span> <span class="o">=</span> <span class="n">address</span> <span class="ow">or</span> <span class="p">(</span><span class="bp">None</span><span class="p">,</span> <span class="bp">None</span><span class="p">)</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="bson">
<h2><a class="toc-backref" href="#id30">BSON</a><a class="headerlink" href="#bson" title="Permalink to this headline">¶</a></h2>
<div class="section" id="as-class-tz-aware-and-uuid-subtype-are-removed">
<h3><a class="toc-backref" href="#id31">“as_class”, “tz_aware”, and “uuid_subtype” are removed</a><a class="headerlink" href="#as-class-tz-aware-and-uuid-subtype-are-removed" title="Permalink to this headline">¶</a></h3>
<p>The <cite>as_class</cite>, <cite>tz_aware</cite>, and <cite>uuid_subtype</cite> parameters have been
removed from the functions provided in <a class="reference internal" href="api/bson/index.html#module-bson" title="bson: BSON (Binary JSON) Encoding and Decoding"><code class="xref py py-mod docutils literal notranslate"><span class="pre">bson</span></code></a>. Code like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">bson</span> <span class="k">import</span> <span class="n">BSON</span>
<span class="gp">>>> </span><span class="kn">from</span> <span class="nn">bson.son</span> <span class="k">import</span> <span class="n">SON</span>
<span class="gp">>>> </span><span class="n">encoded</span> <span class="o">=</span> <span class="n">BSON</span><span class="o">.</span><span class="n">encode</span><span class="p">({</span><span class="s2">"a"</span><span class="p">:</span> <span class="mi">1</span><span class="p">},</span> <span class="n">as_class</span><span class="o">=</span><span class="n">SON</span><span class="p">)</span>
</pre></div>
</div>
<p>can be replaced by this in PyMongo 2.9 or later:</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">BSON</span>
<span class="gp">>>> </span><span class="kn">from</span> <span class="nn">bson.codec_options</span> <span class="kn">import</span> <span class="n">CodecOptions</span>
<span class="gp">>>> </span><span class="kn">from</span> <span class="nn">bson.son</span> <span class="kn">import</span> <span class="n">SON</span>
<span class="gp">>>> </span><span class="n">encoded</span> <span class="o">=</span> <span class="n">BSON</span><span class="o">.</span><span class="n">encode</span><span class="p">({</span><span class="s2">"a"</span><span class="p">:</span> <span class="mi">1</span><span class="p">},</span> <span class="n">codec_options</span><span class="o">=</span><span class="n">CodecOptions</span><span class="p">(</span><span class="n">SON</span><span class="p">))</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="removed-features-with-no-migration-path">
<h2><a class="toc-backref" href="#id32">Removed features with no migration path</a><a class="headerlink" href="#removed-features-with-no-migration-path" title="Permalink to this headline">¶</a></h2>
<div class="section" id="masterslaveconnection-is-removed">
<h3><a class="toc-backref" href="#id33">MasterSlaveConnection is removed</a><a class="headerlink" href="#masterslaveconnection-is-removed" title="Permalink to this headline">¶</a></h3>
<p>Master slave deployments are deprecated in MongoDB. Starting with MongoDB 3.0
a replica set can have up to 50 members and that limit is likely to be
removed in later releases. We recommend migrating to replica sets instead.</p>
</div>
<div class="section" id="requests-are-removed">
<h3><a class="toc-backref" href="#id34">Requests are removed</a><a class="headerlink" href="#requests-are-removed" title="Permalink to this headline">¶</a></h3>
<p>The client methods <cite>start_request</cite>, <cite>in_request</cite>, and <cite>end_request</cite> are
removed. Requests were designed to make read-your-writes consistency more
likely with the w=0 write concern. Additionally, a thread in a request used the
same member for all secondary reads in a replica set. To ensure
read-your-writes consistency in PyMongo 3.0, do not override the default write
concern with w=0, and do not override the default read preference of PRIMARY.</p>
</div>
<div class="section" id="the-compile-re-option-is-removed">
<h3><a class="toc-backref" href="#id35">The “compile_re” option is removed</a><a class="headerlink" href="#the-compile-re-option-is-removed" title="Permalink to this headline">¶</a></h3>
<p>In PyMongo 3 regular expressions are never compiled to Python match objects.</p>
</div>
<div class="section" id="the-use-greenlets-option-is-removed">
<h3><a class="toc-backref" href="#id36">The “use_greenlets” option is removed</a><a class="headerlink" href="#the-use-greenlets-option-is-removed" title="Permalink to this headline">¶</a></h3>
<p>The <cite>use_greenlets</cite> option was meant to allow use of PyMongo with Gevent
without the use of gevent.monkey.patch_threads(). This option caused a lot
of confusion and made it difficult to support alternative asyncio libraries
like Eventlet. Users of Gevent should use gevent.monkey.patch_all() instead.</p>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last"><a class="reference internal" href="examples/gevent.html"><span class="doc">Gevent</span></a></p>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3><a href="index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">PyMongo 3 Migration Guide</a><ul>
<li><a class="reference internal" href="#pymongo-2-9">PyMongo 2.9</a></li>
<li><a class="reference internal" href="#enable-deprecation-warnings">Enable Deprecation Warnings</a></li>
<li><a class="reference internal" href="#crud-api">CRUD API</a><ul>
<li><a class="reference internal" href="#changes-to-find-and-find-one">Changes to find() and find_one()</a><ul>
<li><a class="reference internal" href="#spec-renamed-filter">“spec” renamed “filter”</a></li>
<li><a class="reference internal" href="#fields-renamed-projection">“fields” renamed “projection”</a></li>
<li><a class="reference internal" href="#partial-renamed-allow-partial-results">“partial” renamed “allow_partial_results”</a></li>
<li><a class="reference internal" href="#timeout-replaced-by-no-cursor-timeout">“timeout” replaced by “no_cursor_timeout”</a></li>
<li><a class="reference internal" href="#network-timeout-is-removed">“network_timeout” is removed</a></li>
<li><a class="reference internal" href="#tailable-cursors">Tailable cursors</a></li>
<li><a class="reference internal" href="#other-removed-options">Other removed options</a></li>
</ul>
</li>
<li><a class="reference internal" href="#the-aggregate-method-always-returns-a-cursor">The aggregate method always returns a cursor</a></li>
</ul>
</li>
<li><a class="reference internal" href="#read-preferences">Read Preferences</a><ul>
<li><a class="reference internal" href="#the-slave-okay-option-is-removed">The “slave_okay” option is removed</a></li>
<li><a class="reference internal" href="#the-read-preference-attribute-is-immutable">The “read_preference” attribute is immutable</a></li>
<li><a class="reference internal" href="#the-tag-sets-option-and-attribute-are-removed">The “tag_sets” option and attribute are removed</a></li>
<li><a class="reference internal" href="#the-secondary-acceptable-latency-ms-option-and-attribute-are-removed">The “secondary_acceptable_latency_ms” option and attribute are removed</a></li>
</ul>
</li>
<li><a class="reference internal" href="#write-concern">Write Concern</a><ul>
<li><a class="reference internal" href="#the-safe-option-is-removed">The “safe” option is removed</a></li>
<li><a class="reference internal" href="#the-write-concern-attribute-is-immutable">The “write_concern” attribute is immutable</a></li>
</ul>
</li>
<li><a class="reference internal" href="#codec-options">Codec Options</a><ul>
<li><a class="reference internal" href="#the-document-class-attribute-is-removed">The “document_class” attribute is removed</a></li>
<li><a class="reference internal" href="#the-uuid-subtype-option-and-attribute-are-removed">The “uuid_subtype” option and attribute are removed</a></li>
</ul>
</li>
<li><a class="reference internal" href="#mongoclient">MongoClient</a><ul>
<li><a class="reference internal" href="#mongoclient-connects-asynchronously">MongoClient connects asynchronously</a></li>
<li><a class="reference internal" href="#the-max-pool-size-parameter-is-removed">The max_pool_size parameter is removed</a></li>
<li><a class="reference internal" href="#the-disconnect-method-is-removed">The “disconnect” method is removed</a></li>
<li><a class="reference internal" href="#the-host-and-port-attributes-are-removed">The host and port attributes are removed</a></li>
</ul>
</li>
<li><a class="reference internal" href="#bson">BSON</a><ul>
<li><a class="reference internal" href="#as-class-tz-aware-and-uuid-subtype-are-removed">“as_class”, “tz_aware”, and “uuid_subtype” are removed</a></li>
</ul>
</li>
<li><a class="reference internal" href="#removed-features-with-no-migration-path">Removed features with no migration path</a><ul>
<li><a class="reference internal" href="#masterslaveconnection-is-removed">MasterSlaveConnection is removed</a></li>
<li><a class="reference internal" href="#requests-are-removed">Requests are removed</a></li>
<li><a class="reference internal" href="#the-compile-re-option-is-removed">The “compile_re” option is removed</a></li>
<li><a class="reference internal" href="#the-use-greenlets-option-is-removed">The “use_greenlets” option is removed</a></li>
</ul>
</li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="python3.html"
title="previous chapter">Python 3 FAQ</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="developer/index.html"
title="next chapter">Developer Guide</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/migrate-to-pymongo3.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="developer/index.html" title="Developer Guide"
>next</a> |</li>
<li class="right" >
<a href="python3.html" title="Python 3 FAQ"
>previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">PyMongo 3.7.2 documentation</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
>
438
