<!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>mongo_client – Tools for connecting to MongoDB — 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="mongo_replica_set_client – Tools for connecting to a MongoDB replica set" href="mongo_replica_set_client.html" />
<link rel="prev" title="message – Tools for creating messages to be sent to MongoDB" href="message.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="mongo_replica_set_client.html" title="mongo_replica_set_client – Tools for connecting to a MongoDB replica set"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="message.html" title="message – Tools for creating messages to be sent to MongoDB"
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">pymongo</span></code> – Python driver for MongoDB</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="module-pymongo.mongo_client">
<span id="mongo-client-tools-for-connecting-to-mongodb"></span><h1><code class="xref py py-mod docutils literal notranslate"><span class="pre">mongo_client</span></code> – Tools for connecting to MongoDB<a class="headerlink" href="#module-pymongo.mongo_client" title="Permalink to this headline">¶</a></h1>
<p>Tools for connecting to MongoDB.</p>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last"><a class="reference internal" href="../../examples/high_availability.html"><span class="doc">High Availability and PyMongo</span></a> for examples of connecting
to replica sets or sets of mongos servers.</p>
</div>
<p>To get a <a class="reference internal" href="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> instance from a
<a class="reference internal" href="#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> use either dictionary-style or attribute-style
access:</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">MongoClient</span>
<span class="gp">>>> </span><span class="n">c</span> <span class="o">=</span> <span class="n">MongoClient</span><span class="p">()</span>
<span class="gp">>>> </span><span class="n">c</span><span class="o">.</span><span class="n">test_database</span>
<span class="go">Database(MongoClient(host=['localhost:27017'], document_class=dict, tz_aware=False, connect=True), u'test_database')</span>
<span class="gp">>>> </span><span class="n">c</span><span class="p">[</span><span class="s1">'test-database'</span><span class="p">]</span>
<span class="go">Database(MongoClient(host=['localhost:27017'], document_class=dict, tz_aware=False, connect=True), u'test-database')</span>
</pre></div>
</div>
<dl class="class">
<dt id="pymongo.mongo_client.MongoClient">
<em class="property">class </em><code class="descclassname">pymongo.mongo_client.</code><code class="descname">MongoClient</code><span class="sig-paren">(</span><em>host='localhost'</em>, <em>port=27017</em>, <em>document_class=dict</em>, <em>tz_aware=False</em>, <em>connect=True</em>, <em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#pymongo.mongo_client.MongoClient" title="Permalink to this definition">¶</a></dt>
<dd><p>Client for a MongoDB instance, a replica set, or a set of mongoses.</p>
<p>The client object is thread-safe and has connection-pooling built in.
If an operation fails because of a network error,
<a class="reference internal" href="errors.html#pymongo.errors.ConnectionFailure" title="pymongo.errors.ConnectionFailure"><code class="xref py py-class docutils literal notranslate"><span class="pre">ConnectionFailure</span></code></a> is raised and the client
reconnects in the background. Application code should handle this
exception (recognizing that the operation failed) and then continue to
execute.</p>
<p>The <cite>host</cite> parameter can be a full <a class="reference external" href="http://dochub.mongodb.org/core/connections">mongodb URI</a>, in addition to
a simple hostname. It can also be a list of hostnames or
URIs. Any port specified in the host string(s) will override
the <cite>port</cite> parameter. If multiple mongodb URIs containing
database or auth information are passed, the last database,
username, and password present will be used. For username and
passwords reserved characters like ‘:’, ‘/’, ‘+’ and ‘@’ must be
percent encoded following RFC 2396:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">try</span><span class="p">:</span>
<span class="c1"># Python 3.x</span>
<span class="kn">from</span> <span class="nn">urllib.parse</span> <span class="k">import</span> <span class="n">quote_plus</span>
<span class="k">except</span> <span class="ne">ImportError</span><span class="p">:</span>
<span class="c1"># Python 2.x</span>
<span class="kn">from</span> <span class="nn">urllib</span> <span class="k">import</span> <span class="n">quote_plus</span>
<span class="n">uri</span> <span class="o">=</span> <span class="s2">"mongodb://</span><span class="si">%s</span><span class="s2">:</span><span class="si">%s</span><span class="s2">@</span><span class="si">%s</span><span class="s2">"</span> <span class="o">%</span> <span class="p">(</span>
<span class="n">quote_plus</span><span class="p">(</span><span class="n">user</span><span class="p">),</span> <span class="n">quote_plus</span><span class="p">(</span><span class="n">password</span><span class="p">),</span> <span class="n">host</span><span class="p">)</span>
<span class="n">client</span> <span class="o">=</span> <span class="n">MongoClient</span><span class="p">(</span><span class="n">uri</span><span class="p">)</span>
</pre></div>
</div>
<p>Unix domain sockets are also supported. The socket path must be percent
encoded in the URI:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">uri</span> <span class="o">=</span> <span class="s2">"mongodb://</span><span class="si">%s</span><span class="s2">:</span><span class="si">%s</span><span class="s2">@</span><span class="si">%s</span><span class="s2">"</span> <span class="o">%</span> <span class="p">(</span>
<span class="n">quote_plus</span><span class="p">(</span><span class="n">user</span><span class="p">),</span> <span class="n">quote_plus</span><span class="p">(</span><span class="n">password</span><span class="p">),</span> <span class="n">quote_plus</span><span class="p">(</span><span class="n">socket_path</span><span class="p">))</span>
<span class="n">client</span> <span class="o">=</span> <span class="n">MongoClient</span><span class="p">(</span><span class="n">uri</span><span class="p">)</span>
</pre></div>
</div>
<p>But not when passed as a simple hostname:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">client</span> <span class="o">=</span> <span class="n">MongoClient</span><span class="p">(</span><span class="s1">'/tmp/mongodb-27017.sock'</span><span class="p">)</span>
</pre></div>
</div>
<p>Starting with version 3.6, PyMongo supports mongodb+srv:// URIs. The
URI must include one, and only one, hostname. The hostname will be
resolved to one or more DNS <a class="reference external" href="https://en.wikipedia.org/wiki/SRV_record">SRV records</a> which will be used
as the seed list for connecting to the MongoDB deployment. When using
SRV URIs, the <cite>authSource</cite> and <cite>replicaSet</cite> configuration options can
be specified using <a class="reference external" href="https://en.wikipedia.org/wiki/TXT_record">TXT records</a>. See the
<a class="reference external" href="https://github.com/mongodb/specifications/blob/master/source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.rst">Initial DNS Seedlist Discovery spec</a>
for more details. Note that the use of SRV URIs implicitly enables
TLS support. Pass ssl=false in the URI to override.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">MongoClient creation will block waiting for answers from
DNS when mongodb+srv:// URIs are used.</p>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p>Starting with version 3.0 the <a class="reference internal" href="#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="errors.html#pymongo.errors.ConnectionFailure" title="pymongo.errors.ConnectionFailure"><code class="xref py py-class docutils literal notranslate"><span class="pre">ConnectionFailure</span></code></a> if they are
unavailable, nor <a class="reference internal" href="errors.html#pymongo.errors.ConfigurationError" title="pymongo.errors.ConfigurationError"><code class="xref py py-class 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. You can check if the server is available
like this:</p>
<div class="last highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">pymongo.errors</span> <span class="k">import</span> <span class="n">ConnectionFailure</span>
<span class="n">client</span> <span class="o">=</span> <span class="n">MongoClient</span><span class="p">()</span>
<span class="k">try</span><span class="p">:</span>
<span class="c1"># The ismaster command is cheap and does not require auth.</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="s1">'ismaster'</span><span class="p">)</span>
<span class="k">except</span> <span class="n">ConnectionFailure</span><span class="p">:</span>
<span class="nb">print</span><span class="p">(</span><span class="s2">"Server not available"</span><span class="p">)</span>
</pre></div>
</div>
</div>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">When using PyMongo in a multiprocessing context, please
read <a class="reference internal" href="../../faq.html#multiprocessing"><span class="std std-ref">Using PyMongo with Multiprocessing</span></a> first.</p>
</div>
<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 simple">
<li><cite>host</cite> (optional): hostname or IP address or Unix domain socket
path of a single mongod or mongos instance to connect to, or a
mongodb URI, or a list of hostnames / mongodb URIs. If <cite>host</cite> is
an IPv6 literal it must be enclosed in ‘[‘ and ‘]’ characters
following the RFC2732 URL syntax (e.g. ‘[::1]’ for localhost).
Multihomed and round robin DNS addresses are <strong>not</strong> supported.</li>
<li><cite>port</cite> (optional): port number on which to connect</li>
<li><cite>document_class</cite> (optional): default class to use for
documents returned from queries on this client</li>
<li><cite>tz_aware</cite> (optional): if <code class="docutils literal notranslate"><span class="pre">True</span></code>,
<code class="xref py py-class docutils literal notranslate"><span class="pre">datetime</span></code> instances returned as values
in a document by this <a class="reference internal" href="#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> will be timezone
aware (otherwise they will be naive)</li>
<li><cite>connect</cite> (optional): if <code class="docutils literal notranslate"><span class="pre">True</span></code> (the default), immediately
begin connecting to MongoDB in the background. Otherwise connect
on the first operation.</li>
</ul>
<div class="line-block">
<div class="line"><strong>Other optional parameters can be passed as keyword arguments:</strong></div>
</div>
<ul>
<li><p class="first"><cite>maxPoolSize</cite> (optional): The maximum allowable number of
concurrent connections to each connected server. Requests to a
server will block if there are <cite>maxPoolSize</cite> outstanding
connections to the requested server. Defaults to 100. Cannot be 0.</p>
</li>
<li><p class="first"><cite>minPoolSize</cite> (optional): The minimum required number of concurrent
connections that the pool will maintain to each connected server.
Default is 0.</p>
</li>
<li><p class="first"><cite>maxIdleTimeMS</cite> (optional): The maximum number of milliseconds that
a connection can remain idle in the pool before being removed and
replaced. Defaults to <cite>None</cite> (no limit).</p>
</li>
<li><p class="first"><cite>socketTimeoutMS</cite>: (integer or None) Controls how long (in
milliseconds) the driver will wait for a response after sending an
ordinary (non-monitoring) database operation before concluding that
a network error has occurred. Defaults to <code class="docutils literal notranslate"><span class="pre">None</span></code> (no timeout).</p>
</li>
<li><p class="first"><cite>connectTimeoutMS</cite>: (integer or None) Controls how long (in
milliseconds) the driver will wait during server monitoring when
connecting a new socket to a server before concluding the server
is unavailable. Defaults to <code class="docutils literal notranslate"><span class="pre">20000</span></code> (20 seconds).</p>
</li>
<li><p class="first"><cite>serverSelectionTimeoutMS</cite>: (integer) Controls how long (in
milliseconds) the driver will wait to find an available,
appropriate server to carry out a database operation; while it is
waiting, multiple server monitoring operations may be carried out,
each controlled by <cite>connectTimeoutMS</cite>. Defaults to <code class="docutils literal notranslate"><span class="pre">30000</span></code> (30
seconds).</p>
</li>
<li><p class="first"><cite>waitQueueTimeoutMS</cite>: (integer or None) How long (in milliseconds)
a thread will wait for a socket from the pool if the pool has no
free sockets. Defaults to <code class="docutils literal notranslate"><span class="pre">None</span></code> (no timeout).</p>
</li>
<li><p class="first"><cite>waitQueueMultiple</cite>: (integer or None) Multiplied by maxPoolSize
to give the number of threads allowed to wait for a socket at one
time. Defaults to <code class="docutils literal notranslate"><span class="pre">None</span></code> (no limit).</p>
</li>
<li><p class="first"><cite>heartbeatFrequencyMS</cite>: (optional) The number of milliseconds
between periodic server checks, or None to accept the default
frequency of 10 seconds.</p>
</li>
<li><p class="first"><cite>appname</cite>: (string or None) The name of the application that
created this MongoClient instance. MongoDB 3.4 and newer will
print this value in the server log upon establishing each
connection. It is also recorded in the slow query log and
profile collections.</p>
</li>
<li><p class="first"><cite>driver</cite>: (pair or None) A driver implemented on top of PyMongo can
pass a <a class="reference internal" href="driver_info.html#pymongo.driver_info.DriverInfo" title="pymongo.driver_info.DriverInfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">DriverInfo</span></code></a> to add its name,
version, and platform to the message printed in the server log when
establishing a connection.</p>
</li>
<li><p class="first"><cite>event_listeners</cite>: a list or tuple of event listeners. See
<a class="reference internal" href="monitoring.html#module-pymongo.monitoring" title="pymongo.monitoring: Tools for monitoring driver events."><code class="xref py py-mod docutils literal notranslate"><span class="pre">monitoring</span></code></a> for details.</p>
</li>
<li><p class="first"><cite>retryWrites</cite>: (boolean) Whether supported write operations
executed within this MongoClient will be retried once after a
network error on MongoDB 3.6+. Defaults to <code class="docutils literal notranslate"><span class="pre">False</span></code>.
The supported write operations are:</p>
<blockquote>
<div><ul class="simple">
<li><a class="reference internal" href="collection.html#pymongo.collection.Collection.bulk_write" title="pymongo.collection.Collection.bulk_write"><code class="xref py py-meth docutils literal notranslate"><span class="pre">bulk_write()</span></code></a>, as long as
<a class="reference internal" href="operations.html#pymongo.operations.UpdateMany" title="pymongo.operations.UpdateMany"><code class="xref py py-class docutils literal notranslate"><span class="pre">UpdateMany</span></code></a> or
<a class="reference internal" href="operations.html#pymongo.operations.DeleteMany" title="pymongo.operations.DeleteMany"><code class="xref py py-class docutils literal notranslate"><span class="pre">DeleteMany</span></code></a> are not included.</li>
<li><a class="reference internal" href="collection.html#pymongo.collection.Collection.delete_one" title="pymongo.collection.Collection.delete_one"><code class="xref py py-meth docutils literal notranslate"><span class="pre">delete_one()</span></code></a></li>
<li><a class="reference internal" href="collection.html#pymongo.collection.Collection.insert_one" title="pymongo.collection.Collection.insert_one"><code class="xref py py-meth docutils literal notranslate"><span class="pre">insert_one()</span></code></a></li>
<li><a class="reference internal" href="collection.html#pymongo.collection.Collection.insert_many" title="pymongo.collection.Collection.insert_many"><code class="xref py py-meth docutils literal notranslate"><span class="pre">insert_many()</span></code></a></li>
<li><a class="reference internal" href="collection.html#pymongo.collection.Collection.replace_one" title="pymongo.collection.Collection.replace_one"><code class="xref py py-meth docutils literal notranslate"><span class="pre">replace_one()</span></code></a></li>
<li><a class="reference internal" href="collection.html#pymongo.collection.Collection.update_one" title="pymongo.collection.Collection.update_one"><code class="xref py py-meth docutils literal notranslate"><span class="pre">update_one()</span></code></a></li>
<li><a class="reference internal" href="collection.html#pymongo.collection.Collection.find_one_and_delete" title="pymongo.collection.Collection.find_one_and_delete"><code class="xref py py-meth docutils literal notranslate"><span class="pre">find_one_and_delete()</span></code></a></li>
<li><a class="reference internal" href="collection.html#pymongo.collection.Collection.find_one_and_replace" title="pymongo.collection.Collection.find_one_and_replace"><code class="xref py py-meth docutils literal notranslate"><span class="pre">find_one_and_replace()</span></code></a></li>
<li><a class="reference internal" href="collection.html#pymongo.collection.Collection.find_one_and_update" title="pymongo.collection.Collection.find_one_and_update"><code class="xref py py-meth docutils literal notranslate"><span class="pre">find_one_and_update()</span></code></a></li>
</ul>
</div></blockquote>
<p>Unsupported write operations include, but are not limited to,
<a class="reference internal" href="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> using the <code class="docutils literal notranslate"><span class="pre">$out</span></code>
pipeline operator and any operation with an unacknowledged write
concern (e.g. {w: 0})). See
<a class="reference external" href="https://github.com/mongodb/specifications/blob/master/source/retryable-writes/retryable-writes.rst">https://github.com/mongodb/specifications/blob/master/source/retryable-writes/retryable-writes.rst</a></p>
</li>
<li><p class="first"><cite>socketKeepAlive</cite>: (boolean) <strong>DEPRECATED</strong> Whether to send
periodic keep-alive packets on connected sockets. Defaults to
<code class="docutils literal notranslate"><span class="pre">True</span></code>. Disabling it is not recommended, see
<a class="reference external" href="https://docs.mongodb.com/manual/faq/diagnostics/#does-tcp-keepalive-time-affect-mongodb-deployments">https://docs.mongodb.com/manual/faq/diagnostics/#does-tcp-keepalive-time-affect-mongodb-deployments</a>”,</p>
</li>
<li><p class="first"><cite>compressors</cite>: Comma separated list of compressors for wire
protocol compression. The list is used to negotiate a compressor
with the server. Currently supported options are “snappy” and
“zlib”. Support for snappy requires the
<a class="reference external" href="https://pypi.org/project/python-snappy/">python-snappy</a> package.
zlib support requires the Python standard library zlib module.
By default no compression is used. Compression support must also be
enabled on the server. MongoDB 3.4+ supports snappy compression.
MongoDB 3.6+ supports snappy and zlib.</p>
</li>
<li><p class="first"><cite>zlibCompressionLevel</cite>: (int) The zlib compression level to use
when zlib is used as the wire protocol compressor. Supported values
are -1 through 9. -1 tells the zlib library to use its default
compression level (usually 6). 0 means no compression. 1 is best
speed. 9 is best compression. Defaults to -1.</p>
</li>
</ul>
<div class="line-block">
<div class="line"><strong>Write Concern options:</strong></div>
<div class="line">(Only set if passed. No default values.)</div>
</div>
<ul class="simple">
<li><cite>w</cite>: (integer or string) If this is a replica set, write operations
will block until they have been replicated to the specified number
or tagged set of servers. <cite>w=<int></cite> always includes the replica set
primary (e.g. w=3 means write to the primary and wait until
replicated to <strong>two</strong> secondaries). Passing w=0 <strong>disables write
acknowledgement</strong> and all other write concern options.</li>
<li><cite>wtimeout</cite>: (integer) Used in conjunction with <cite>w</cite>. Specify a value
in milliseconds to control how long to wait for write propagation
to complete. If replication does not complete in the given
timeframe, a timeout exception is raised.</li>
<li><cite>j</cite>: If <code class="docutils literal notranslate"><span class="pre">True</span></code> block until write operations have been committed
to the journal. Cannot be used in combination with <cite>fsync</cite>. Prior
to MongoDB 2.6 this option was ignored if the server was running
without journaling. Starting with MongoDB 2.6 write operations will
fail with an exception if this option is used when the server is
running without journaling.</li>
<li><cite>fsync</cite>: If <code class="docutils literal notranslate"><span class="pre">True</span></code> and the server is running without journaling,
blocks until the server has synced all data files to disk. If the
server is running with journaling, this acts the same as the <cite>j</cite>
option, blocking until write operations have been committed to the
journal. Cannot be used in combination with <cite>j</cite>.</li>
</ul>
<div class="line-block">
<div class="line"><strong>Replica set keyword arguments for connecting with a replica set
- either directly or via a mongos:</strong></div>
</div>
<ul class="simple">
<li><cite>replicaSet</cite>: (string or None) The name of the replica set to
connect to. The driver will verify that all servers it connects to
match this name. Implies that the hosts specified are a seed list
and the driver should attempt to find all members of the set.
Defaults to <code class="docutils literal notranslate"><span class="pre">None</span></code>.</li>
</ul>
<div class="line-block">
<div class="line"><strong>Read Preference:</strong></div>
</div>
<ul class="simple">
<li><cite>readPreference</cite>: The replica set read preference for this client.
One of <code class="docutils literal notranslate"><span class="pre">primary</span></code>, <code class="docutils literal notranslate"><span class="pre">primaryPreferred</span></code>, <code class="docutils literal notranslate"><span class="pre">secondary</span></code>,
<code class="docutils literal notranslate"><span class="pre">secondaryPreferred</span></code>, or <code class="docutils literal notranslate"><span class="pre">nearest</span></code>. Defaults to <code class="docutils literal notranslate"><span class="pre">primary</span></code>.</li>
<li><cite>readPreferenceTags</cite>: Specifies a tag set as a comma-separated list
of colon-separated key-value pairs. For example <code class="docutils literal notranslate"><span class="pre">dc:ny,rack:1</span></code>.
Defaults to <code class="docutils literal notranslate"><span class="pre">None</span></code>.</li>
<li><cite>maxStalenessSeconds</cite>: (integer) The maximum estimated
length of time a replica set secondary can fall behind the primary
in replication before it will no longer be selected for operations.
Defaults to <code class="docutils literal notranslate"><span class="pre">-1</span></code>, meaning no maximum. If maxStalenessSeconds
is set, it must be a positive integer greater than or equal to
90 seconds.</li>
</ul>
<div class="line-block">
<div class="line"><strong>Authentication:</strong></div>
</div>
<ul>
<li><p class="first"><cite>username</cite>: A string.</p>
</li>
<li><p class="first"><cite>password</cite>: A string.</p>
<p>Although username and password must be percent-escaped in a MongoDB
URI, they must not be percent-escaped when passed as parameters. In
this example, both the space and slash special characters are passed
as-is:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">MongoClient</span><span class="p">(</span><span class="n">username</span><span class="o">=</span><span class="s2">"user name"</span><span class="p">,</span> <span class="n">password</span><span class="o">=</span><span class="s2">"pass/word"</span><span class="p">)</span>
</pre></div>
</div>
</li>
<li><p class="first"><cite>authSource</cite>: The database to authenticate on. Defaults to the
database specified in the URI, if provided, or to “admin”.</p>
</li>
<li><p class="first"><cite>authMechanism</cite>: See <a class="reference internal" href="database.html#pymongo.auth.MECHANISMS" title="pymongo.auth.MECHANISMS"><code class="xref py py-data docutils literal notranslate"><span class="pre">MECHANISMS</span></code></a> for options.
If no mechanism is specified, PyMongo automatically uses MONGODB-CR
when connected to a pre-3.0 version of MongoDB, SCRAM-SHA-1 when
connected to MongoDB 3.0 through 3.6, and negotiates the mechanism
to use (SCRAM-SHA-1 or SCRAM-SHA-256) when connected to MongoDB
4.0+.</p>
</li>
<li><p class="first"><cite>authMechanismProperties</cite>: Used to specify authentication mechanism
specific options. To specify the service name for GSSAPI
authentication pass authMechanismProperties=’SERVICE_NAME:<service
name>’</p>
</li>
</ul>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last"><a class="reference internal" href="../../examples/authentication.html"><span class="doc">Authentication Examples</span></a></p>
</div>
<div class="line-block">
<div class="line"><strong>SSL configuration:</strong></div>
</div>
<ul class="simple">
<li><cite>ssl</cite>: If <code class="docutils literal notranslate"><span class="pre">True</span></code>, create the connection to the server using SSL.
Defaults to <code class="docutils literal notranslate"><span class="pre">False</span></code>.</li>
<li><cite>ssl_certfile</cite>: The certificate file used to identify the local
connection against mongod. Implies <code class="docutils literal notranslate"><span class="pre">ssl=True</span></code>. Defaults to
<code class="docutils literal notranslate"><span class="pre">None</span></code>.</li>
<li><cite>ssl_keyfile</cite>: The private keyfile used to identify the local
connection against mongod. If included with the <code class="docutils literal notranslate"><span class="pre">certfile</span></code> then
only the <code class="docutils literal notranslate"><span class="pre">ssl_certfile</span></code> is needed. Implies <code class="docutils literal notranslate"><span class="pre">ssl=True</span></code>.
Defaults to <code class="docutils literal notranslate"><span class="pre">None</span></code>.</li>
<li><cite>ssl_pem_passphrase</cite>: The password or passphrase for decrypting
the private key in <code class="docutils literal notranslate"><span class="pre">ssl_certfile</span></code> or <code class="docutils literal notranslate"><span class="pre">ssl_keyfile</span></code>. Only
necessary if the private key is encrypted. Only supported by python
2.7.9+ (pypy 2.5.1+) and 3.3+. Defaults to <code class="docutils literal notranslate"><span class="pre">None</span></code>.</li>
<li><cite>ssl_cert_reqs</cite>: Specifies whether a certificate is required from
the other side of the connection, and whether it will be validated
if provided. It must be one of the three values <code class="docutils literal notranslate"><span class="pre">ssl.CERT_NONE</span></code>
(certificates ignored), <code class="docutils literal notranslate"><span class="pre">ssl.CERT_REQUIRED</span></code> (certificates
required and validated), or <code class="docutils literal notranslate"><span class="pre">ssl.CERT_OPTIONAL</span></code> (the same as
CERT_REQUIRED, unless the server was configured to use anonymous
ciphers). If the value of this parameter is not <code class="docutils literal notranslate"><span class="pre">ssl.CERT_NONE</span></code>
and a value is not provided for <code class="docutils literal notranslate"><span class="pre">ssl_ca_certs</span></code> PyMongo will
attempt to load system provided CA certificates. If the python
version in use does not support loading system CA certificates
then the <code class="docutils literal notranslate"><span class="pre">ssl_ca_certs</span></code> parameter must point to a file of CA
certificates. Implies <code class="docutils literal notranslate"><span class="pre">ssl=True</span></code>. Defaults to
<code class="docutils literal notranslate"><span class="pre">ssl.CERT_REQUIRED</span></code> if not provided and <code class="docutils literal notranslate"><span class="pre">ssl=True</span></code>.</li>
<li><cite>ssl_ca_certs</cite>: The ca_certs file contains a set of concatenated
“certification authority” certificates, which are used to validate
certificates passed from the other end of the connection.
Implies <code class="docutils literal notranslate"><span class="pre">ssl=True</span></code>. Defaults to <code class="docutils literal notranslate"><span class="pre">None</span></code>.</li>
<li><cite>ssl_crlfile</cite>: The path to a PEM or DER formatted certificate
revocation list. Only supported by python 2.7.9+ (pypy 2.5.1+)
and 3.4+. Defaults to <code class="docutils literal notranslate"><span class="pre">None</span></code>.</li>
<li><cite>ssl_match_hostname</cite>: If <code class="docutils literal notranslate"><span class="pre">True</span></code> (the default), and
<cite>ssl_cert_reqs</cite> is not <code class="docutils literal notranslate"><span class="pre">ssl.CERT_NONE</span></code>, enables hostname
verification using the <code class="xref py py-func docutils literal notranslate"><span class="pre">match_hostname()</span></code> function from
python’s <code class="xref py py-mod docutils literal notranslate"><span class="pre">ssl</span></code> module. Think very carefully before setting
this to <code class="docutils literal notranslate"><span class="pre">False</span></code> as that could make your application vulnerable to
man-in-the-middle attacks.</li>
</ul>
<div class="line-block">
<div class="line"><strong>Read Concern options:</strong></div>
<div class="line">(If not set explicitly, this will use the server default)</div>
</div>
<ul class="last simple">
<li><cite>readConcernLevel</cite>: (string) The read concern level specifies the
level of isolation for read operations. For example, a read
operation using a read concern level of <code class="docutils literal notranslate"><span class="pre">majority</span></code> will only
return data that has been written to a majority of nodes. If the
level is left unspecified, the server default will be used.</li>
</ul>
</td>
</tr>
</tbody>
</table>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p class="admonition-title">The MongoDB documentation on</p>
<p class="last"><a class="reference external" href="http://dochub.mongodb.org/core/connections" name="pymongo.mongo_client.MongoClient"><em>connections</em></a></p>
</div>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 3.6: </span>Added support for mongodb+srv:// URIs.
Added the <code class="docutils literal notranslate"><span class="pre">retryWrites</span></code> keyword argument and URI option.</p>
</div>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 3.7: </span>Added the <code class="docutils literal notranslate"><span class="pre">driver</span></code> keyword argument.</p>
</div>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 3.5: </span>Add <code class="docutils literal notranslate"><span class="pre">username</span></code> and <code class="docutils literal notranslate"><span class="pre">password</span></code> options. Document the
<code class="docutils literal notranslate"><span class="pre">authSource</span></code>, <code class="docutils literal notranslate"><span class="pre">authMechanism</span></code>, and <code class="docutils literal notranslate"><span class="pre">authMechanismProperties</span> <span class="pre">``</span>
<span class="pre">options.</span>
<span class="pre">Deprecated</span> <span class="pre">the</span> <span class="pre">`socketKeepAlive`</span> <span class="pre">keyword</span> <span class="pre">argument</span> <span class="pre">and</span> <span class="pre">URI</span> <span class="pre">option.</span>
<span class="pre">`socketKeepAlive`</span> <span class="pre">now</span> <span class="pre">defaults</span> <span class="pre">to</span> <span class="pre">``True</span></code>.</p>
</div>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 3.0: </span><a class="reference internal" href="#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> is now the one and only
client class for a standalone server, mongos, or replica set.
It includes the functionality that had been split into
<code class="xref py py-class docutils literal notranslate"><span class="pre">MongoReplicaSetClient</span></code>: it can connect
to a replica set, discover all its members, and monitor the set for
stepdowns, elections, and reconfigs.</p>
<p>The <a class="reference internal" href="#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="errors.html#pymongo.errors.ConnectionFailure" title="pymongo.errors.ConnectionFailure"><code class="xref py py-class docutils literal notranslate"><span class="pre">ConnectionFailure</span></code></a> if they
are unavailable, nor <a class="reference internal" href="errors.html#pymongo.errors.ConfigurationError" title="pymongo.errors.ConfigurationError"><code class="xref py py-class 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.</p>
<p>Therefore the <code class="docutils literal notranslate"><span class="pre">alive</span></code> method is removed since it no longer
provides meaningful information; even if the client is disconnected,
it may discover a server in time to fulfill the next operation.</p>
<p>In PyMongo 2.x, <a class="reference internal" href="index.html#pymongo.MongoClient" title="pymongo.MongoClient"><code class="xref py py-class docutils literal notranslate"><span class="pre">MongoClient</span></code></a> accepted a list of
standalone MongoDB servers and used the first it could connect to:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">MongoClient</span><span class="p">([</span><span class="s1">'host1.com:27017'</span><span class="p">,</span> <span class="s1">'host2.com:27017'</span><span class="p">])</span>
</pre></div>
</div>
<p>A list of multiple standalones is no longer supported; if multiple
servers are listed they must be members of the same replica set, or
mongoses in the same sharded cluster.</p>
<p>The behavior for a list of mongoses is changed from “high
availability” to “load balancing”. Before, the client connected to
the lowest-latency mongos in the list, and used it until a network
error prompted it to re-evaluate all mongoses’ latencies and
reconnect to one of them. In PyMongo 3, the client monitors its
network latency to all the mongoses continuously, and distributes
operations evenly among those with the lowest latency. See
<a class="reference internal" href="../../examples/high_availability.html#mongos-load-balancing"><span class="std std-ref">mongos Load Balancing</span></a> for more information.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">connect</span></code> option is added.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">start_request</span></code>, <code class="docutils literal notranslate"><span class="pre">in_request</span></code>, and <code class="docutils literal notranslate"><span class="pre">end_request</span></code> methods
are removed, as well as the <code class="docutils literal notranslate"><span class="pre">auto_start_request</span></code> option.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">copy_database</span></code> method is removed, see the
<a class="reference internal" href="../../examples/copydb.html"><span class="doc">copy_database examples</span></a> for alternatives.</p>
<p>The <code class="xref py py-meth docutils literal notranslate"><span class="pre">MongoClient.disconnect()</span></code> method is removed; it was a
synonym for <code class="xref py py-meth docutils literal notranslate"><span class="pre">close()</span></code>.</p>
<p><a class="reference internal" href="#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> no longer returns an
instance of <a class="reference internal" href="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> for attribute names
with leading underscores. You must use dict-style lookups instead:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">client</span><span class="p">[</span><span class="s1">'__my_database__'</span><span class="p">]</span>
</pre></div>
</div>
<p>Not:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">client</span><span class="o">.</span><span class="n">__my_database__</span>
</pre></div>
</div>
</div>
<dl class="method">
<dt id="pymongo.mongo_client.MongoClient.close">
<code class="descname">close</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pymongo.mongo_client.MongoClient.close" title="Permalink to this definition">¶</a></dt>
<dd><p>Cleanup client resources and disconnect from MongoDB.</p>
<p>On MongoDB >= 3.6, end all server sessions created by this client by
sending one or more endSessions commands.</p>
<p>Close all sockets in the connection pools and stop the monitor threads.
If this instance is used again it will be automatically re-opened and
the threads restarted.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 3.6: </span>End all server sessions created by this client.</p>
</div>
</dd></dl>
<dl class="describe">
<dt>
<code class="descname">c[db_name] || c.db_name</code></dt>
<dd><p>Get the <cite>db_name</cite> <a class="reference internal" href="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> on <a class="reference internal" href="#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> <cite>c</cite>.</p>
<p>Raises <a class="reference internal" href="errors.html#pymongo.errors.InvalidName" title="pymongo.errors.InvalidName"><code class="xref py py-class docutils literal notranslate"><span class="pre">InvalidName</span></code></a> if an invalid database name is used.</p>
</dd></dl>
<dl class="attribute">
<dt id="pymongo.mongo_client.MongoClient.event_listeners">
<code class="descname">event_listeners</code><a class="headerlink" href="#pymongo.mongo_client.MongoClient.event_listeners" title="Permalink to this definition">¶</a></dt>
<dd><p>The event listeners registered for this client.</p>
<p>See <a class="reference internal" href="monitoring.html#module-pymongo.monitoring" title="pymongo.monitoring: Tools for monitoring driver events."><code class="xref py py-mod docutils literal notranslate"><span class="pre">monitoring</span></code></a> for details.</p>
</dd></dl>
<dl class="attribute">
<dt id="pymongo.mongo_client.MongoClient.address">
<code class="descname">address</code><a class="headerlink" href="#pymongo.mongo_client.MongoClient.address" title="Permalink to this definition">¶</a></dt>
<dd><p>(host, port) of the current standalone, primary, or mongos, or None.</p>
<p>Accessing <a class="reference internal" href="#pymongo.mongo_client.MongoClient.address" title="pymongo.mongo_client.MongoClient.address"><code class="xref py py-attr docutils literal notranslate"><span class="pre">address</span></code></a> raises <a class="reference internal" href="errors.html#pymongo.errors.InvalidOperation" title="pymongo.errors.InvalidOperation"><code class="xref py py-exc docutils literal notranslate"><span class="pre">InvalidOperation</span></code></a> if
the client is load-balancing among mongoses, since there is no single
address. Use <a class="reference internal" href="#pymongo.mongo_client.MongoClient.nodes" title="pymongo.mongo_client.MongoClient.nodes"><code class="xref py py-attr docutils literal notranslate"><span class="pre">nodes</span></code></a> instead.</p>
<p>If the client is not connected, this will block until a connection is
established or raise ServerSelectionTimeoutError if no server is
available.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 3.0.</span></p>
</div>
</dd></dl>
<dl class="attribute">
<dt id="pymongo.mongo_client.MongoClient.primary">
<code class="descname">primary</code><a class="headerlink" href="#pymongo.mongo_client.MongoClient.primary" title="Permalink to this definition">¶</a></dt>
<dd><p>The (host, port) of the current primary of the replica set.</p>
<p>Returns <code class="docutils literal notranslate"><span class="pre">None</span></code> if this client is not connected to a replica set,
there is no primary, or this client was created without the
<cite>replicaSet</cite> option.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 3.0: </span>MongoClient gained this property in version 3.0 when
MongoReplicaSetClient’s functionality was merged in.</p>
</div>
</dd></dl>
<dl class="attribute">
<dt id="pymongo.mongo_client.MongoClient.secondaries">
<code class="descname">secondaries</code><a class="headerlink" href="#pymongo.mongo_client.MongoClient.secondaries" title="Permalink to this definition">¶</a></dt>
<dd><p>The secondary members known to this client.</p>
<p>A sequence of (host, port) pairs. Empty if this client is not
connected to a replica set, there are no visible secondaries, or this
client was created without the <cite>replicaSet</cite> option.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 3.0: </span>MongoClient gained this property in version 3.0 when
MongoReplicaSetClient’s functionality was merged in.</p>
</div>
</dd></dl>
<dl class="attribute">
<dt id="pymongo.mongo_client.MongoClient.arbiters">
<code class="descname">arbiters</code><a class="headerlink" href="#pymongo.mongo_client.MongoClient.arbiters" title="Permalink to this definition">¶</a></dt>
<dd><p>Arbiters in the replica set.</p>
<p>A sequence of (host, port) pairs. Empty if this client is not
connected to a replica set, there are no arbiters, or this client was
created without the <cite>replicaSet</cite> option.</p>
</dd></dl>
<dl class="attribute">
<dt id="pymongo.mongo_client.MongoClient.is_primary">
<code class="descname">is_primary</code><a class="headerlink" href="#pymongo.mongo_client.MongoClient.is_primary" title="Permalink to this definition">¶</a></dt>
<dd><p>If this client is connected to a server that can accept writes.</p>
<p>True if the current server is a standalone, mongos, or the primary of
a replica set. If the client is not connected, this will block until a
connection is established or raise ServerSelectionTimeoutError if no
server is available.</p>
</dd></dl>
<dl class="attribute">
<dt id="pymongo.mongo_client.MongoClient.is_mongos">
<code class="descname">is_mongos</code><a class="headerlink" href="#pymongo.mongo_client.MongoClient.is_mongos" title="Permalink to this definition">¶</a></dt>
<dd><p>If this client is connected to mongos. If the client is not
connected, this will block until a connection is established or raise
ServerSelectionTimeoutError if no server is available..</p>
</dd></dl>
<dl class="attribute">
<dt id="pymongo.mongo_client.MongoClient.max_pool_size">
<code class="descname">max_pool_size</code><a class="headerlink" href="#pymongo.mongo_client.MongoClient.max_pool_size" title="Permalink to this definition">¶</a></dt>
<dd><p>The maximum allowable number of concurrent connections to each
connected server. Requests to a server will block if there are
<cite>maxPoolSize</cite> outstanding connections to the requested server.
Defaults to 100. Cannot be 0.</p>
<p>When a server’s pool has reached <cite>max_pool_size</cite>, operations for that
server block waiting for a socket to be returned to the pool. If
<code class="docutils literal notranslate"><span class="pre">waitQueueTimeoutMS</span></code> is set, a blocked operation will raise
<a class="reference internal" href="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> after a timeout.
By default <code class="docutils literal notranslate"><span class="pre">waitQueueTimeoutMS</span></code> is not set.</p>
</dd></dl>
<dl class="attribute">
<dt id="pymongo.mongo_client.MongoClient.min_pool_size">
<code class="descname">min_pool_size</code><a class="headerlink" href="#pymongo.mongo_client.MongoClient.min_pool_size" title="Permalink to this definition">¶</a></dt>
<dd><p>The minimum required number of concurrent connections that the pool
will maintain to each connected server. Default is 0.</p>
</dd></dl>
<dl class="attribute">
<dt id="pymongo.mongo_client.MongoClient.max_idle_time_ms">
<code class="descname">max_idle_time_ms</code><a class="headerlink" href="#pymongo.mongo_client.MongoClient.max_idle_time_ms" title="Permalink to this definition">¶</a></dt>
<dd><p>The maximum number of milliseconds that a connection can remain
idle in the pool before being removed and replaced. Defaults to
<cite>None</cite> (no limit).</p>
</dd></dl>
<dl class="attribute">
<dt id="pymongo.mongo_client.MongoClient.nodes">
<code class="descname">nodes</code><a class="headerlink" href="#pymongo.mongo_client.MongoClient.nodes" title="Permalink to this definition">¶</a></dt>
<dd><p>Set of all currently connected servers.</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">When connected to a replica set the value of <a class="reference internal" href="#pymongo.mongo_client.MongoClient.nodes" title="pymongo.mongo_client.MongoClient.nodes"><code class="xref py py-attr docutils literal notranslate"><span class="pre">nodes</span></code></a>
can change over time as <a class="reference internal" href="#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>’s view of the replica
set changes. <a class="reference internal" href="#pymongo.mongo_client.MongoClient.nodes" title="pymongo.mongo_client.MongoClient.nodes"><code class="xref py py-attr docutils literal notranslate"><span class="pre">nodes</span></code></a> can also be an empty set when
<a class="reference internal" href="#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> is first instantiated and hasn’t yet connected
to any servers, or a network partition causes it to lose connection
to all servers.</p>
</div>
</dd></dl>
<dl class="attribute">
<dt id="pymongo.mongo_client.MongoClient.max_bson_size">
<code class="descname">max_bson_size</code><a class="headerlink" href="#pymongo.mongo_client.MongoClient.max_bson_size" title="Permalink to this definition">¶</a></dt>
<dd><p>The largest BSON object the connected server accepts in bytes.</p>
<p>If the client is not connected, this will block until a connection is
established or raise ServerSelectionTimeoutError if no server is
available.</p>
</dd></dl>
<dl class="attribute">
<dt id="pymongo.mongo_client.MongoClient.max_message_size">
<code class="descname">max_message_size</code><a class="headerlink" href="#pymongo.mongo_client.MongoClient.max_message_size" title="Permalink to this definition">¶</a></dt>
<dd><p>The largest message the connected server accepts in bytes.</p>
<p>If the client is not connected, this will block until a connection is
established or raise ServerSelectionTimeoutError if no server is
available.</p>
</dd></dl>
<dl class="attribute">
<dt id="pymongo.mongo_client.MongoClient.max_write_batch_size">
<code class="descname">max_write_batch_size</code><a class="headerlink" href="#pymongo.mongo_client.MongoClient.max_write_batch_size" title="Permalink to this definition">¶</a></dt>
<dd><p>The maxWriteBatchSize reported by the server.</p>
<p>If the client is not connected, this will block until a connection is
established or raise ServerSelectionTimeoutError if no server is
available.</p>
<p>Returns a default value when connected to server versions prior to
MongoDB 2.6.</p>
</dd></dl>
<dl class="attribute">
<dt id="pymongo.mongo_client.MongoClient.local_threshold_ms">
<code class="descname">local_threshold_ms</code><a class="headerlink" href="#pymongo.mongo_client.MongoClient.local_threshold_ms" title="Permalink to this definition">¶</a></dt>
<dd><p>The local threshold for this instance.</p>
</dd></dl>
<dl class="attribute">
<dt id="pymongo.mongo_client.MongoClient.server_selection_timeout">
<code class="descname">server_selection_timeout</code><a class="headerlink" href="#pymongo.mongo_client.MongoClient.server_selection_timeout" title="Permalink to this definition">¶</a></dt>
<dd><p>The server selection timeout for this instance in seconds.</p>
</dd></dl>
<dl class="attribute">
<dt id="pymongo.mongo_client.MongoClient.codec_options">
<code class="descname">codec_options</code><a class="headerlink" href="#pymongo.mongo_client.MongoClient.codec_options" title="Permalink to this definition">¶</a></dt>
<dd><p>Read only access to the <a class="reference internal" href="../bson/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>
of this instance.</p>
</dd></dl>
<dl class="attribute">
<dt id="pymongo.mongo_client.MongoClient.read_preference">
<code class="descname">read_preference</code><a class="headerlink" href="#pymongo.mongo_client.MongoClient.read_preference" title="Permalink to this definition">¶</a></dt>
<dd><p>Read only access to the read preference of this instance.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 3.0: </span>The <a class="reference internal" href="#pymongo.mongo_client.MongoClient.read_preference" title="pymongo.mongo_client.MongoClient.read_preference"><code class="xref py py-attr docutils literal notranslate"><span class="pre">read_preference</span></code></a> attribute is now read only.</p>
</div>
</dd></dl>
<dl class="attribute">
<dt id="pymongo.mongo_client.MongoClient.write_concern">
<code class="descname">write_concern</code><a class="headerlink" href="#pymongo.mongo_client.MongoClient.write_concern" title="Permalink to this definition">¶</a></dt>
<dd><p>Read only access to the <a class="reference internal" href="write_concern.html#pymongo.write_concern.WriteConcern" title="pymongo.write_concern.WriteConcern"><code class="xref py py-class docutils literal notranslate"><span class="pre">WriteConcern</span></code></a>
of this instance.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 3.0: </span>The <a class="reference internal" href="#pymongo.mongo_client.MongoClient.write_concern" title="pymongo.mongo_client.MongoClient.write_concern"><code class="xref py py-attr docutils literal notranslate"><span class="pre">write_concern</span></code></a> attribute is now read only.</p>
</div>
</dd></dl>
<dl class="attribute">
<dt id="pymongo.mongo_client.MongoClient.read_concern">
<code class="descname">read_concern</code><a class="headerlink" href="#pymongo.mongo_client.MongoClient.read_concern" title="Permalink to this definition">¶</a></dt>
<dd><p>Read only access to the <a class="reference internal" href="read_concern.html#pymongo.read_concern.ReadConcern" title="pymongo.read_concern.ReadConcern"><code class="xref py py-class docutils literal notranslate"><span class="pre">ReadConcern</span></code></a>
of this instance.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 3.2.</span></p>
</div>
</dd></dl>
<dl class="attribute">
<dt id="pymongo.mongo_client.MongoClient.is_locked">
<code class="descname">is_locked</code><a class="headerlink" href="#pymongo.mongo_client.MongoClient.is_locked" title="Permalink to this definition">¶</a></dt>
<dd><p>Is this server locked? While locked, all write operations
are blocked, although read operations may still be allowed.
Use <a class="reference internal" href="#pymongo.mongo_client.MongoClient.unlock" title="pymongo.mongo_client.MongoClient.unlock"><code class="xref py py-meth docutils literal notranslate"><span class="pre">unlock()</span></code></a> to unlock.</p>
</dd></dl>
<dl class="method">
<dt id="pymongo.mongo_client.MongoClient.start_session">
<code class="descname">start_session</code><span class="sig-paren">(</span><em>causal_consistency=True</em>, <em>default_transaction_options=None</em><span class="sig-paren">)</span><a class="headerlink" href="#pymongo.mongo_client.MongoClient.start_session" title="Permalink to this definition">¶</a></dt>
<dd><p>Start a logical session.</p>
<p>This method takes the same parameters as
<a class="reference internal" href="client_session.html#pymongo.client_session.SessionOptions" title="pymongo.client_session.SessionOptions"><code class="xref py py-class docutils literal notranslate"><span class="pre">SessionOptions</span></code></a>. See the
<a class="reference internal" href="client_session.html#module-pymongo.client_session" title="pymongo.client_session"><code class="xref py py-mod docutils literal notranslate"><span class="pre">client_session</span></code></a> module for details and examples.</p>
<p>Requires MongoDB 3.6. It is an error to call <a class="reference internal" href="#pymongo.mongo_client.MongoClient.start_session" title="pymongo.mongo_client.MongoClient.start_session"><code class="xref py py-meth docutils literal notranslate"><span class="pre">start_session()</span></code></a>
if this client has been authenticated to multiple databases using the
deprecated method <a class="reference internal" href="database.html#pymongo.database.Database.authenticate" title="pymongo.database.Database.authenticate"><code class="xref py py-meth docutils literal notranslate"><span class="pre">authenticate()</span></code></a>.</p>
<p>A <a class="reference internal" href="client_session.html#pymongo.client_session.ClientSession" title="pymongo.client_session.ClientSession"><code class="xref py py-class docutils literal notranslate"><span class="pre">ClientSession</span></code></a> may only be used with
the MongoClient that started it.</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">Returns:</th><td class="field-body">An instance of <a class="reference internal" href="client_session.html#pymongo.client_session.ClientSession" title="pymongo.client_session.ClientSession"><code class="xref py py-class docutils literal notranslate"><span class="pre">ClientSession</span></code></a>.</td>
</tr>
</tbody>
</table>
<div class="versionadded">
<p><span class="versionmodified">New in version 3.6.</span></p>
</div>
</dd></dl>
<dl class="method">
<dt id="pymongo.mongo_client.MongoClient.list_databases">
<code class="descname">list_databases</code><span class="sig-paren">(</span><em>session=None</em>, <em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#pymongo.mongo_client.MongoClient.list_databases" title="Permalink to this definition">¶</a></dt>
<dd><p>Get a cursor over the databases of the connected server.</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 simple">
<li><cite>session</cite> (optional): a
<a class="reference internal" href="client_session.html#pymongo.client_session.ClientSession" title="pymongo.client_session.ClientSession"><code class="xref py py-class docutils literal notranslate"><span class="pre">ClientSession</span></code></a>.</li>
<li><cite>**kwargs</cite> (optional): Optional parameters of the
<a class="reference external" href="https://docs.mongodb.com/manual/reference/command/listDatabases/">listDatabases command</a>
can be passed as keyword arguments to this method. The supported
options differ by server version.</li>
</ul>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">An instance of <a class="reference internal" href="command_cursor.html#pymongo.command_cursor.CommandCursor" title="pymongo.command_cursor.CommandCursor"><code class="xref py py-class docutils literal notranslate"><span class="pre">CommandCursor</span></code></a>.</p>
</td>
</tr>
</tbody>
</table>
<div class="versionadded">
<p><span class="versionmodified">New in version 3.6.</span></p>
</div>
</dd></dl>
<dl class="method">
<dt id="pymongo.mongo_client.MongoClient.list_database_names">
<code class="descname">list_database_names</code><span class="sig-paren">(</span><em>session=None</em><span class="sig-paren">)</span><a class="headerlink" href="#pymongo.mongo_client.MongoClient.list_database_names" title="Permalink to this definition">¶</a></dt>
<dd><p>Get a list of the names of all databases on the connected server.</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>session</cite> (optional): a
<a class="reference internal" href="client_session.html#pymongo.client_session.ClientSession" title="pymongo.client_session.ClientSession"><code class="xref py py-class docutils literal notranslate"><span class="pre">ClientSession</span></code></a>.</li>
</ul>
</td>
</tr>
</tbody>
</table>
<div class="versionadded">
<p><span class="versionmodified">New in version 3.6.</span></p>
</div>
</dd></dl>
<dl class="method">
<dt id="pymongo.mongo_client.MongoClient.database_names">
<code class="descname">database_names</code><span class="sig-paren">(</span><em>session=None</em><span class="sig-paren">)</span><a class="headerlink" href="#pymongo.mongo_client.MongoClient.database_names" title="Permalink to this definition">¶</a></dt>
<dd><p><strong>DEPRECATED</strong>: Get a list of the names of all databases on the
connected server.</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>session</cite> (optional): a
<a class="reference internal" href="client_session.html#pymongo.client_session.ClientSession" title="pymongo.client_session.ClientSession"><code class="xref py py-class docutils literal notranslate"><span class="pre">ClientSession</span></code></a>.</li>
</ul>
</td>
</tr>
</tbody>
</table>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 3.7: </span>Deprecated. Use <a class="reference internal" href="#pymongo.mongo_client.MongoClient.list_database_names" title="pymongo.mongo_client.MongoClient.list_database_names"><code class="xref py py-meth docutils literal notranslate"><span class="pre">list_database_names()</span></code></a> instead.</p>
</div>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 3.6: </span>Added <code class="docutils literal notranslate"><span class="pre">session</span></code> parameter.</p>
</div>
</dd></dl>
<dl class="method">
<dt id="pymongo.mongo_client.MongoClient.drop_database">
<code class="descname">drop_database</code><span class="sig-paren">(</span><em>name_or_database</em>, <em>session=None</em><span class="sig-paren">)</span><a class="headerlink" href="#pymongo.mongo_client.MongoClient.drop_database" title="Permalink to this definition">¶</a></dt>
<dd><p>Drop a database.</p>
<p>Raises <code class="xref py py-class docutils literal notranslate"><span class="pre">TypeError</span></code> if <cite>name_or_database</cite> is not an instance of
<code class="xref py py-class docutils literal notranslate"><span class="pre">basestring</span></code> (<code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code> in python 3) or
<a class="reference internal" href="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>.</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>name_or_database</cite>: the name of a database to drop, or a
<a class="reference internal" href="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> instance representing the
database to drop</li>
<li><cite>session</cite> (optional): a
<a class="reference internal" href="client_session.html#pymongo.client_session.ClientSession" title="pymongo.client_session.ClientSession"><code class="xref py py-class docutils literal notranslate"><span class="pre">ClientSession</span></code></a>.</li>
</ul>
</td>
</tr>
</tbody>
</table>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 3.6: </span>Added <code class="docutils literal notranslate"><span class="pre">session</span></code> parameter.</p>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The <a class="reference internal" href="#pymongo.mongo_client.MongoClient.write_concern" title="pymongo.mongo_client.MongoClient.write_concern"><code class="xref py py-attr docutils literal notranslate"><span class="pre">write_concern</span></code></a> of
this client is automatically applied to this operation when using
MongoDB >= 3.4.</p>
</div>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 3.4: </span>Apply this client’s write concern automatically to this operation
when connected to MongoDB >= 3.4.</p>
</div>
</dd></dl>
<dl class="method">
<dt id="pymongo.mongo_client.MongoClient.get_database">
<code class="descname">get_database</code><span class="sig-paren">(</span><em>name=None</em>, <em>codec_options=None</em>, <em>read_preference=None</em>, <em>write_concern=None</em>, <em>read_concern=None</em><span class="sig-paren">)</span><a class="headerlink" href="#pymongo.mongo_client.MongoClient.get_database" title="Permalink to this definition">¶</a></dt>
<dd><p>Get a <a class="reference internal" href="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 the given name and
options.</p>
<p>Useful for creating a <a class="reference internal" href="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
different codec options, read preference, and/or write concern from
this <a class="reference internal" href="#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>.</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">read_preference</span>
<span class="go">Primary()</span>
<span class="gp">>>> </span><span class="n">db1</span> <span class="o">=</span> <span class="n">client</span><span class="o">.</span><span class="n">test</span>
<span class="gp">>>> </span><span class="n">db1</span><span class="o">.</span><span class="n">read_preference</span>
<span class="go">Primary()</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">db2</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="gp">... </span> <span class="s1">'test'</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">db2</span><span class="o">.</span><span class="n">read_preference</span>
<span class="go">Secondary(tag_sets=None)</span>
</pre></div>
</div>
<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>name</cite> (optional): The name of the database - a string. If <code class="docutils literal notranslate"><span class="pre">None</span></code>
(the default) the database named in the MongoDB connection URI is
returned.</li>
<li><cite>codec_options</cite> (optional): An instance of
<a class="reference internal" href="../bson/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>. If <code class="docutils literal notranslate"><span class="pre">None</span></code> (the
default) the <a class="reference internal" href="#pymongo.mongo_client.MongoClient.codec_options" title="pymongo.mongo_client.MongoClient.codec_options"><code class="xref py py-attr docutils literal notranslate"><span class="pre">codec_options</span></code></a> of this <a class="reference internal" href="#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> is
used.</li>
<li><cite>read_preference</cite> (optional): The read preference to use. If
<code class="docutils literal notranslate"><span class="pre">None</span></code> (the default) the <a class="reference internal" href="#pymongo.mongo_client.MongoClient.read_preference" title="pymongo.mongo_client.MongoClient.read_preference"><code class="xref py py-attr docutils literal notranslate"><span class="pre">read_preference</span></code></a> of this
<a class="reference internal" href="#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> is used. See <a class="reference internal" href="read_preferences.html#module-pymongo.read_preferences" title="pymongo.read_preferences: Utilities for choosing which member of a replica set to read from."><code class="xref py py-mod docutils literal notranslate"><span class="pre">read_preferences</span></code></a>
for options.</li>
<li><cite>write_concern</cite> (optional): An instance of
<a class="reference internal" href="write_concern.html#pymongo.write_concern.WriteConcern" title="pymongo.write_concern.WriteConcern"><code class="xref py py-class docutils literal notranslate"><span class="pre">WriteConcern</span></code></a>. If <code class="docutils literal notranslate"><span class="pre">None</span></code> (the
default) the <a class="reference internal" href="#pymongo.mongo_client.MongoClient.write_concern" title="pymongo.mongo_client.MongoClient.write_concern"><code class="xref py py-attr docutils literal notranslate"><span class="pre">write_concern</span></code></a> of this <a class="reference internal" href="#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> is
used.</li>
<li><cite>read_concern</cite> (optional): An instance of
<a class="reference internal" href="read_concern.html#pymongo.read_concern.ReadConcern" title="pymongo.read_concern.ReadConcern"><code class="xref py py-class docutils literal notranslate"><span class="pre">ReadConcern</span></code></a>. If <code class="docutils literal notranslate"><span class="pre">None</span></code> (the
default) the <a class="reference internal" href="#pymongo.mongo_client.MongoClient.read_concern" title="pymongo.mongo_client.MongoClient.read_concern"><code class="xref py py-attr docutils literal notranslate"><span class="pre">read_concern</span></code></a> of this <a class="reference internal" href="#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> is
used.</li>
</ul>
</td>
</tr>
</tbody>
</table>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 3.5: </span>The <cite>name</cite> parameter is now optional, defaulting to the database
named in the MongoDB connection URI.</p>
</div>
</dd></dl>
<dl class="method">
<dt id="pymongo.mongo_client.MongoClient.server_info">
<code class="descname">server_info</code><span class="sig-paren">(</span><em>session=None</em><span class="sig-paren">)</span><a class="headerlink" href="#pymongo.mongo_client.MongoClient.server_info" title="Permalink to this definition">¶</a></dt>
<dd><p>Get information about the MongoDB server we’re connected to.</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>session</cite> (optional): a
<a class="reference internal" href="client_session.html#pymongo.client_session.ClientSession" title="pymongo.client_session.ClientSession"><code class="xref py py-class docutils literal notranslate"><span class="pre">ClientSession</span></code></a>.</li>
</ul>
</td>
</tr>
</tbody>
</table>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 3.6: </span>Added <code class="docutils literal notranslate"><span class="pre">session</span></code> parameter.</p>
</div>
</dd></dl>
<dl class="method">
<dt id="pymongo.mongo_client.MongoClient.close_cursor">
<code class="descname">close_cursor</code><span class="sig-paren">(</span><em>cursor_id</em>, <em>address=None</em><span class="sig-paren">)</span><a class="headerlink" href="#pymongo.mongo_client.MongoClient.close_cursor" title="Permalink to this definition">¶</a></dt>
<dd><p>DEPRECATED - Send a kill cursors message soon with the given id.</p>
<p>Raises <code class="xref py py-class docutils literal notranslate"><span class="pre">TypeError</span></code> if <cite>cursor_id</cite> is not an instance of
<code class="docutils literal notranslate"><span class="pre">(int,</span> <span class="pre">long)</span></code>. What closing the cursor actually means
depends on this client’s cursor manager.</p>
<p>This method may be called from a <a class="reference internal" href="cursor.html#pymongo.cursor.Cursor" title="pymongo.cursor.Cursor"><code class="xref py py-class docutils literal notranslate"><span class="pre">Cursor</span></code></a>
destructor during garbage collection, so it isn’t safe to take a
lock or do network I/O. Instead, we schedule the cursor to be closed
soon on a background thread.</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>cursor_id</cite>: id of cursor to close</li>
<li><cite>address</cite> (optional): (host, port) pair of the cursor’s server.
If it is not provided, the client attempts to close the cursor on
the primary or standalone, or a mongos server.</li>
</ul>
</td>
</tr>
</tbody>
</table>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 3.7: </span>Deprecated.</p>
</div>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 3.0: </span>Added <code class="docutils literal notranslate"><span class="pre">address</span></code> parameter.</p>
</div>
</dd></dl>
<dl class="method">
<dt id="pymongo.mongo_client.MongoClient.kill_cursors">
<code class="descname">kill_cursors</code><span class="sig-paren">(</span><em>cursor_ids</em>, <em>address=None</em><span class="sig-paren">)</span><a class="headerlink" href="#pymongo.mongo_client.MongoClient.kill_cursors" title="Permalink to this definition">¶</a></dt>
<dd><p>DEPRECATED - Send a kill cursors message soon with the given ids.</p>
<p>Raises <code class="xref py py-class docutils literal notranslate"><span class="pre">TypeError</span></code> if <cite>cursor_ids</cite> is not an instance of
<code class="docutils literal notranslate"><span class="pre">list</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>cursor_ids</cite>: list of cursor ids to kill</li>
<li><cite>address</cite> (optional): (host, port) pair of the cursor’s server.
If it is not provided, the client attempts to close the cursor on
the primary or standalone, or a mongos server.</li>
</ul>
</td>
</tr>
</tbody>
</table>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 3.3: </span>Deprecated.</p>
</div>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 3.0: </span>Now accepts an <cite>address</cite> argument. Schedules the cursors to be
closed on a background thread instead of sending the message
immediately.</p>
</div>
</dd></dl>
<dl class="method">
<dt id="pymongo.mongo_client.MongoClient.set_cursor_manager">
<code class="descname">set_cursor_manager</code><span class="sig-paren">(</span><em>manager_class</em><span class="sig-paren">)</span><a class="headerlink" href="#pymongo.mongo_client.MongoClient.set_cursor_manager" title="Permalink to this definition">¶</a></dt>
<dd><p>DEPRECATED - Set this client’s cursor manager.</p>
<p>Raises <code class="xref py py-class docutils literal notranslate"><span class="pre">TypeError</span></code> if <cite>manager_class</cite> is not a subclass of
<a class="reference internal" href="cursor_manager.html#pymongo.cursor_manager.CursorManager" title="pymongo.cursor_manager.CursorManager"><code class="xref py py-class docutils literal notranslate"><span class="pre">CursorManager</span></code></a>. A cursor manager
handles closing cursors. Different managers can implement different
policies in terms of when to actually kill a cursor that has
been closed.</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>manager_class</cite>: cursor manager to use</li>
</ul>
</td>
</tr>
</tbody>
</table>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 3.3: </span>Deprecated, for real this time.</p>
</div>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 3.0: </span>Undeprecated.</p>
</div>
</dd></dl>
<dl class="method">
<dt id="pymongo.mongo_client.MongoClient.watch">
<code class="descname">watch</code><span class="sig-paren">(</span><em>pipeline=None</em>, <em>full_document='default'</em>, <em>resume_after=None</em>, <em>max_await_time_ms=None</em>, <em>batch_size=None</em>, <em>collation=None</em>, <em>start_at_operation_time=None</em>, <em>session=None</em><span class="sig-paren">)</span><a class="headerlink" href="#pymongo.mongo_client.MongoClient.watch" title="Permalink to this definition">¶</a></dt>
<dd><p>Watch changes on this cluster.</p>
<p>Performs an aggregation with an implicit initial <code class="docutils literal notranslate"><span class="pre">$changeStream</span></code>
stage and returns a
<a class="reference internal" href="change_stream.html#pymongo.change_stream.ClusterChangeStream" title="pymongo.change_stream.ClusterChangeStream"><code class="xref py py-class docutils literal notranslate"><span class="pre">ClusterChangeStream</span></code></a> cursor which
iterates over changes on all databases on this cluster.</p>
<p>Introduced in MongoDB 4.0.</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">with</span> <span class="n">client</span><span class="o">.</span><span class="n">watch</span><span class="p">()</span> <span class="k">as</span> <span class="n">stream</span><span class="p">:</span>
<span class="k">for</span> <span class="n">change</span> <span class="ow">in</span> <span class="n">stream</span><span class="p">:</span>
<span class="k">print</span><span class="p">(</span><span class="n">change</span><span class="p">)</span>
</pre></div>
</div>
<p>The <a class="reference internal" href="change_stream.html#pymongo.change_stream.ClusterChangeStream" title="pymongo.change_stream.ClusterChangeStream"><code class="xref py py-class docutils literal notranslate"><span class="pre">ClusterChangeStream</span></code></a> iterable
blocks until the next change document is returned or an error is
raised. If the
<code class="xref py py-meth docutils literal notranslate"><span class="pre">next()</span></code> method
encounters a network error when retrieving a batch from the server,
it will automatically attempt to recreate the cursor such that no
change events are missed. Any error encountered during the resume
attempt indicates there may be an outage and will be raised.</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">try</span><span class="p">:</span>
<span class="k">with</span> <span class="n">client</span><span class="o">.</span><span class="n">watch</span><span class="p">(</span>
<span class="p">[{</span><span class="s1">'$match'</span><span class="p">:</span> <span class="p">{</span><span class="s1">'operationType'</span><span class="p">:</span> <span class="s1">'insert'</span><span class="p">}}])</span> <span class="k">as</span> <span class="n">stream</span><span class="p">:</span>
<span class="k">for</span> <span class="n">insert_change</span> <span class="ow">in</span> <span class="n">stream</span><span class="p">:</span>
<span class="k">print</span><span class="p">(</span><span class="n">insert_change</span><span class="p">)</span>
<span class="k">except</span> <span class="n">pymongo</span><span class="o">.</span><span class="n">errors</span><span class="o">.</span><span class="n">PyMongoError</span><span class="p">:</span>
<span class="c1"># The ChangeStream encountered an unrecoverable error or the</span>
<span class="c1"># resume attempt failed to recreate the cursor.</span>
<span class="n">logging</span><span class="o">.</span><span class="n">error</span><span class="p">(</span><span class="s1">'...'</span><span class="p">)</span>
</pre></div>
</div>
<p>For a precise description of the resume process see the
<a class="reference external" href="https://github.com/mongodb/specifications/blob/master/source/change-streams/change-streams.rst">change streams specification</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 simple">
<li><cite>pipeline</cite> (optional): A list of aggregation pipeline stages to
append to an initial <code class="docutils literal notranslate"><span class="pre">$changeStream</span></code> stage. Not all
pipeline stages are valid after a <code class="docutils literal notranslate"><span class="pre">$changeStream</span></code> stage, see the
MongoDB documentation on change streams for the supported stages.</li>
<li><cite>full_document</cite> (optional): The fullDocument to pass as an option
to the <code class="docutils literal notranslate"><span class="pre">$changeStream</span></code> stage. Allowed values: ‘default’,
‘updateLookup’. Defaults to ‘default’.
When set to ‘updateLookup’, the change notification for partial
updates will include both a delta describing the changes to the
document, as well as a copy of the entire document that was
changed from some time after the change occurred.</li>
<li><cite>resume_after</cite> (optional): The logical starting point for this
change stream.</li>
<li><cite>max_await_time_ms</cite> (optional): The maximum time in milliseconds
for the server to wait for changes before responding to a getMore
operation.</li>
<li><cite>batch_size</cite> (optional): The maximum number of documents to return
per batch.</li>
<li><cite>collation</cite> (optional): The <a class="reference internal" href="collation.html#pymongo.collation.Collation" title="pymongo.collation.Collation"><code class="xref py py-class docutils literal notranslate"><span class="pre">Collation</span></code></a>
to use for the aggregation.</li>
<li><cite>start_at_operation_time</cite> (optional): If provided, the resulting
change stream will only return changes that occurred at or after
the specified <a class="reference internal" href="../bson/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>. Requires
MongoDB >= 4.0.</li>
<li><cite>session</cite> (optional): a
<a class="reference internal" href="client_session.html#pymongo.client_session.ClientSession" title="pymongo.client_session.ClientSession"><code class="xref py py-class docutils literal notranslate"><span class="pre">ClientSession</span></code></a>.</li>
</ul>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">A <a class="reference internal" href="change_stream.html#pymongo.change_stream.ClusterChangeStream" title="pymongo.change_stream.ClusterChangeStream"><code class="xref py py-class docutils literal notranslate"><span class="pre">ClusterChangeStream</span></code></a> cursor.</p>
</td>
</tr>
</tbody>
</table>
<div class="versionadded">
<p><span class="versionmodified">New in version 3.7.</span></p>
</div>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p class="admonition-title">The MongoDB documentation on</p>
<p class="last"><a class="reference external" href="http://dochub.mongodb.org/core/changeStreams" name="pymongo.mongo_client.MongoClient.watch"><em>changeStreams</em></a></p>
</div>
</dd></dl>
<dl class="method">
<dt id="pymongo.mongo_client.MongoClient.fsync">
<code class="descname">fsync</code><span class="sig-paren">(</span><em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#pymongo.mongo_client.MongoClient.fsync" title="Permalink to this definition">¶</a></dt>
<dd><p>Flush all pending writes to datafiles.</p>
<dl class="docutils">
<dt>Optional parameters can be passed as keyword arguments:</dt>
<dd><ul class="first last simple">
<li><cite>lock</cite>: If True lock the server to disallow writes.</li>
<li><cite>async</cite>: If True don’t block while synchronizing.</li>
<li><cite>session</cite> (optional): a
<a class="reference internal" href="client_session.html#pymongo.client_session.ClientSession" title="pymongo.client_session.ClientSession"><code class="xref py py-class docutils literal notranslate"><span class="pre">ClientSession</span></code></a>.</li>
</ul>
</dd>
</dl>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p>Starting with Python 3.7 <cite>async</cite> is a reserved keyword.
The async option to the fsync command can be passed using a
dictionary instead:</p>
<div class="last highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">options</span> <span class="o">=</span> <span class="p">{</span><span class="s1">'async'</span><span class="p">:</span> <span class="kc">True</span><span class="p">}</span>
<span class="n">client</span><span class="o">.</span><span class="n">fsync</span><span class="p">(</span><span class="o">**</span><span class="n">options</span><span class="p">)</span>
</pre></div>
</div>
</div>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 3.6: </span>Added <code class="docutils literal notranslate"><span class="pre">session</span></code> parameter.</p>
</div>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last"><cite>async</cite> and <cite>lock</cite> can not be used together.</p>
</div>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">MongoDB does not support the <cite>async</cite> option
on Windows and will raise an exception on that
platform.</p>
</div>
</dd></dl>
<dl class="method">
<dt id="pymongo.mongo_client.MongoClient.unlock">
<code class="descname">unlock</code><span class="sig-paren">(</span><em>session=None</em><span class="sig-paren">)</span><a class="headerlink" href="#pymongo.mongo_client.MongoClient.unlock" title="Permalink to this definition">¶</a></dt>
<dd><p>Unlock a previously locked server.</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>session</cite> (optional): a
<a class="reference internal" href="client_session.html#pymongo.client_session.ClientSession" title="pymongo.client_session.ClientSession"><code class="xref py py-class docutils literal notranslate"><span class="pre">ClientSession</span></code></a>.</li>
</ul>
</td>
</tr>
</tbody>
</table>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 3.6: </span>Added <code class="docutils literal notranslate"><span class="pre">session</span></code> parameter.</p>
</div>
</dd></dl>
<dl class="method">
<dt id="pymongo.mongo_client.MongoClient.get_default_database">
<code class="descname">get_default_database</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pymongo.mongo_client.MongoClient.get_default_database" title="Permalink to this definition">¶</a></dt>
<dd><p>DEPRECATED - Get the database named in the MongoDB connection URI.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">uri</span> <span class="o">=</span> <span class="s1">'mongodb://host/my_database'</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">uri</span><span class="p">)</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_default_database</span><span class="p">()</span>
<span class="gp">>>> </span><span class="k">assert</span> <span class="n">db</span><span class="o">.</span><span class="n">name</span> <span class="o">==</span> <span class="s1">'my_database'</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="gp">>>> </span><span class="k">assert</span> <span class="n">db</span><span class="o">.</span><span class="n">name</span> <span class="o">==</span> <span class="s1">'my_database'</span>
</pre></div>
</div>
<p>Useful in scripts where you want to choose which database to use
based only on the URI in a configuration file.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 3.5: </span>Deprecated, use <a class="reference internal" href="#pymongo.mongo_client.MongoClient.get_database" title="pymongo.mongo_client.MongoClient.get_database"><code class="xref py py-meth docutils literal notranslate"><span class="pre">get_database()</span></code></a> instead.</p>
</div>
</dd></dl>
</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="message.html"
title="previous chapter"><code class="docutils literal notranslate"><span class="pre">message</span></code> – Tools for creating messages to be sent to MongoDB</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="mongo_replica_set_client.html"
title="next chapter"><code class="docutils literal notranslate"><span class="pre">mongo_replica_set_client</span></code> – Tools for connecting to a MongoDB replica set</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../../_sources/api/pymongo/mongo_client.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="mongo_replica_set_client.html" title="mongo_replica_set_client – Tools for connecting to a MongoDB replica set"
>next</a> |</li>
<li class="right" >
<a href="message.html" title="message – Tools for creating messages to be sent to MongoDB"
>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">pymongo</span></code> – Python driver for MongoDB</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
>
i586
>
media
>
core-release
>
by-pkgid
>
bc55833f04f370ac3ed453ef5b0ad686
>
files
>
254
