def __init__(self,
hosts_or_uri=None,
max_pool_size=10,
document_class=dict,
tz_aware=False,
**kwargs):
"""Create a new connection to a MongoDB replica set.
The resultant connection object has connection-pooling built
in. It also performs auto-reconnection when necessary. If an
operation fails because of a connection error,
:class:`~pymongo.errors.ConnectionFailure` is raised. If
auto-reconnection will be performed,
:class:`~pymongo.errors.AutoReconnect` will be
raised. Application code should handle this exception
(recognizing that the operation failed) and then continue to
execute.
Raises :class:`~pymongo.errors.ConnectionFailure` if
the connection cannot be made.
The `hosts_or_uri` parameter can be a full `mongodb URI
<http://dochub.mongodb.org/core/connections>`_, in addition to
a string of `host:port` pairs (e.g. 'host1:port1,host2:port2').
If `hosts_or_uri` is None 'localhost:27017' will be used.
.. note:: Instances of :class:`~ReplicaSetConnection` start a
background task to monitor the state of the replica set. This allows
it to quickly respond to changes in replica set configuration.
Before discarding an instance of :class:`~ReplicaSetConnection` make
sure you call :meth:`~close` to ensure that the monitor task is
cleanly shut down.
:Parameters:
- `hosts_or_uri` (optional): A MongoDB URI or string of `host:port`
pairs. If a host is an IPv6 literal it must be enclosed in '[' and
']' characters following the RFC2732 URL syntax (e.g. '[::1]' for
localhost)
- `max_pool_size` (optional): The maximum size limit for
each connection pool.
- `document_class` (optional): default class to use for
documents returned from queries on this connection
- `tz_aware` (optional): if ``True``,
:class:`~datetime.datetime` instances returned as values
in a document by this :class:`ReplicaSetConnection` will be timezone
aware (otherwise they will be naive)
- `replicaSet`: (required) The name of the replica set to connect to.
The driver will verify that each host it connects to is a member of
this replica set. Can be passed as a keyword argument or as a
MongoDB URI option.
Other optional parameters can be passed as keyword arguments:
- `safe`: Use getlasterror for each write operation?
- `j` or `journal`: Block until write operations have been commited
to the journal. Ignored if the server is running without
journaling. Implies safe=True.
- `w`: (integer or string) If this is a replica set write operations
won't return until they have been replicated to the specified
number or tagged set of servers.
Implies safe=True.
- `wtimeoutMS`: Used in conjunction with `j` and/or `w`. Wait this
many milliseconds for journal acknowledgement and/or write
replication. Implies safe=True.
- `fsync`: Force the database to fsync all files before returning
When used with `j` the server awaits the next group commit before
returning. Implies safe=True.
- `socketTimeoutMS`: How long a send or receive on a socket can take
before timing out.
- `connectTimeoutMS`: How long a connection can take to be opened
before timing out.
- `ssl`: If True, create the connection to the servers using SSL.
- `read_preference`: The read preference for this connection.
See :class:`~pymongo.ReadPreference` for available options.
- `auto_start_request`: If True (the default), each thread that
accesses this :class:`ReplicaSetConnection` has a socket allocated
to it for the thread's lifetime, for each member of the set. For
:class:`~pymongo.ReadPreference` PRIMARY, auto_start_request=True
ensures consistent reads, even if you read after an unsafe
write. For read preferences other than PRIMARY, there are no
consistency guarantees. (The semantics of auto_start_request,
:class:`~pymongo.ReadPreference`, and :class:`ReplicaSetConnection`
may change in future releases of PyMongo.)
- `use_greenlets` (optional): if ``True``, use a background Greenlet
instead of a background thread to monitor state of replica set.
:meth:`start_request()` will ensure that the current greenlet uses
the same socket for all operations until :meth:`end_request()`.
`use_greenlets` with ReplicaSetConnection requires `Gevent
<http://gevent.org/>`_ to be installed.
- `slave_okay` or `slaveOk` (deprecated): Use `read_preference`
instead.
- `host`: For compatibility with connection.Connection. If both
`host` and `hosts_or_uri` are specified `host` takes precedence.
- `port`: For compatibility with connection.Connection. The default
port number to use for hosts.
- `network_timeout`: For compatibility with connection.Connection.
The timeout (in seconds) to use for socket operations - default
is no timeout. If both `network_timeout` and `socketTimeoutMS` are
are specified `network_timeout` takes precedence, matching
connection.Connection.
.. versionchanged:: 2.2
Added `auto_start_request` and `use_greenlets` options.
Added support for `host`, `port`, and `network_timeout` keyword
arguments for compatibility with connection.Connection.
.. versionadded:: 2.1
"""
self.__opts = {}
self.__seeds = set()
self.__hosts = None
self.__arbiters = set()
self.__writer = None
self.__readers = []
self.__pools = {}
self.__index_cache = {}
self.__auth_credentials = {}
self.__max_pool_size = common.validate_positive_integer(
'max_pool_size', max_pool_size)
self.__tz_aware = common.validate_boolean('tz_aware', tz_aware)
self.__document_class = document_class
# Compatibility with connection.Connection
host = kwargs.pop('host', hosts_or_uri)
port = kwargs.pop('port', 27017)
if not isinstance(port, int):
raise TypeError("port must be an instance of int")
network_timeout = kwargs.pop('network_timeout', None)
if network_timeout is not None:
if (not isinstance(network_timeout, (int, float))
or network_timeout <= 0):
raise ConfigurationError("network_timeout must "
"be a positive integer")
username = None
db_name = None
if host is None:
self.__seeds.add(('localhost', port))
elif '://' in host:
res = uri_parser.parse_uri(host, port)
self.__seeds.update(res['nodelist'])
username = res['username']
password = res['password']
db_name = res['database']
self.__opts = res['options']
else:
self.__seeds.update(uri_parser.split_hosts(host, port))
for option, value in kwargs.iteritems():
option, value = common.validate(option, value)
self.__opts[option] = value
if self.__opts.get('use_greenlets', False):
if not have_gevent:
raise ConfigurationError(
"The gevent module is not available. "
"Install the gevent package from PyPI.")
self.pool_class = pool.GreenletPool
else:
self.pool_class = pool.Pool
self.__auto_start_request = self.__opts.get('auto_start_request', True)
self.__in_request = self.__auto_start_request
self.__name = self.__opts.get('replicaset')
if not self.__name:
raise ConfigurationError("the replicaSet "
"keyword parameter is required.")
self.__net_timeout = (network_timeout
or self.__opts.get('sockettimeoutms'))
self.__conn_timeout = self.__opts.get('connecttimeoutms')
self.__use_ssl = self.__opts.get('ssl', False)
if self.__use_ssl and not pool.have_ssl:
raise ConfigurationError("The ssl module is not available. If you "
"are using a python version previous to "
"2.6 you must install the ssl package "
"from PyPI.")
super(ReplicaSetConnection, self).__init__(**self.__opts)
if self.slave_okay:
warnings.warn(
"slave_okay is deprecated. Please "
"use read_preference instead.", DeprecationWarning)
self.refresh()
if db_name and username is None:
warnings.warn("must provide a username and password "
"to authenticate to %s" % (db_name, ))
if username:
db_name = db_name or 'admin'
if not self[db_name].authenticate(username, password):
raise ConfigurationError("authentication failed")
# Start the monitor after we know the configuration is correct.
if self.__opts.get('use_greenlets', False):
self.__monitor = MonitorGreenlet(self)
else:
# NOTE: Don't ever make this a daemon thread in CPython. Daemon
# threads in CPython cause serious issues when the interpreter is
# torn down. Symptoms range from random exceptions to the
# interpreter dumping core.
self.__monitor = MonitorThread(self)
# Sadly, weakrefs aren't totally reliable in PyPy and Jython
# so use a daemon thread there.
if (sys.platform.startswith('java') or 'PyPy' in sys.version):
self.__monitor.setDaemon(True)
self.__monitor.start()
def __init__(self, host=None, port=None, max_pool_size=10,
document_class=dict, tz_aware=False, _connect=True, **kwargs):
"""Create a new connection to a single MongoDB instance at *host:port*.
The resultant client object has connection-pooling built
in. It also performs auto-reconnection when necessary. If an
operation fails because of a connection error,
:class:`~pymongo.errors.ConnectionFailure` is raised. If
auto-reconnection will be performed,
:class:`~pymongo.errors.AutoReconnect` will be
raised. Application code should handle this exception
(recognizing that the operation failed) and then continue to
execute.
Raises :class:`TypeError` if port is not an instance of
``int``. Raises :class:`~pymongo.errors.ConnectionFailure` if
the connection cannot be made.
The `host` parameter can be a full `mongodb URI
<http://dochub.mongodb.org/core/connections>`_, 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 `port` 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
escaped following RFC 2396.
:Parameters:
- `host` (optional): hostname or IP address of the
instance to connect to, or a mongodb URI, or a list of
hostnames / mongodb URIs. If `host` is an IPv6 literal
it must be enclosed in '[' and ']' characters following
the RFC2732 URL syntax (e.g. '[::1]' for localhost)
- `port` (optional): port number on which to connect
- `max_pool_size` (optional): The maximum number of idle connections
to keep open in the pool for future use
- `document_class` (optional): default class to use for
documents returned from queries on this client
- `tz_aware` (optional): if ``True``,
:class:`~datetime.datetime` instances returned as values
in a document by this :class:`MongoClient` will be timezone
aware (otherwise they will be naive)
| **Other optional parameters can be passed as keyword arguments:**
- `socketTimeoutMS`: (integer) How long (in milliseconds) a send or
receive on a socket can take before timing out.
- `connectTimeoutMS`: (integer) How long (in milliseconds) a
connection can take to be opened before timing out.
- `auto_start_request`: If ``True``, each thread that accesses
this :class:`MongoClient` has a socket allocated to it for the
thread's lifetime. This ensures consistent reads, even if you
read after an unacknowledged write. Defaults to ``False``
- `use_greenlets`: If ``True``, :meth:`start_request()` will ensure
that the current greenlet uses the same socket for all
operations until :meth:`end_request()`
| **Write Concern options:**
- `w`: (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. `w=<int>` always includes the replica set
primary (e.g. w=3 means write to the primary and wait until
replicated to **two** secondaries). Passing w=0 **disables write
acknowledgement** and all other write concern options.
- `wtimeout`: (integer) Used in conjunction with `w`. 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.
- `j`: If ``True`` block until write operations have been committed
to the journal. Ignored if the server is running without journaling.
- `fsync`: If ``True`` force the database to fsync all files before
returning. When used with `j` the server awaits the next group
commit before returning.
| **Replica set keyword arguments for connecting with a replica set
- either directly or via a mongos:**
| (ignored by standalone mongod instances)
- `replicaSet`: (string) The name of the replica set to connect to.
The driver will verify that the replica set it connects to matches
this name. Implies that the hosts specified are a seed list and the
driver should attempt to find all members of the set. *Ignored by
mongos*.
- `read_preference`: The read preference for this client. If
connecting to a secondary then a read preference mode *other* than
PRIMARY is required - otherwise all queries will throw
:class:`~pymongo.errors.AutoReconnect` "not master".
See :class:`~pymongo.read_preferences.ReadPreference` for all
available read preference options.
- `tag_sets`: Ignored unless connecting to a replica set via mongos.
Specify a priority-order for tag sets, provide a list of
tag sets: ``[{'dc': 'ny'}, {'dc': 'la'}, {}]``. A final, empty tag
set, ``{}``, means "read from any member that matches the mode,
ignoring tags.
| **SSL configuration:**
- `ssl`: If ``True``, create the connection to the server using SSL.
- `ssl_keyfile`: The private keyfile used to identify the local
connection against mongod. If included with the ``certfile` then
only the ``ssl_certfile`` is needed. Implies ``ssl=True``.
- `ssl_certfile`: The certificate file used to identify the local
connection against mongod. Implies ``ssl=True``.
- `ssl_cert_reqs`: 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 ``ssl.CERT_NONE``
(certificates ignored), ``ssl.CERT_OPTIONAL``
(not required, but validated if provided), or ``ssl.CERT_REQUIRED``
(required and validated). If the value of this parameter is not
``ssl.CERT_NONE``, then the ``ssl_ca_certs`` parameter must point
to a file of CA certificates. Implies ``ssl=True``.
- `ssl_ca_certs`: 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 ``ssl=True``.
.. seealso:: :meth:`end_request`
.. mongodoc:: connections
.. versionchanged:: 2.5
Added additional ssl options
.. versionadded:: 2.4
"""
if host is None:
host = self.HOST
if isinstance(host, basestring):
host = [host]
if port is None:
port = self.PORT
if not isinstance(port, int):
raise TypeError("port must be an instance of int")
seeds = set()
username = None
password = None
db_name = None
opts = {}
for entity in host:
if "://" in entity:
if entity.startswith("mongodb://"):
res = uri_parser.parse_uri(entity, port)
seeds.update(res["nodelist"])
username = res["username"] or username
password = res["password"] or password
db_name = res["database"] or db_name
opts = res["options"]
else:
idx = entity.find("://")
raise InvalidURI("Invalid URI scheme: "
"%s" % (entity[:idx],))
else:
seeds.update(uri_parser.split_hosts(entity, port))
if not seeds:
raise ConfigurationError("need to specify at least one host")
self.__nodes = seeds
self.__host = None
self.__port = None
self.__is_primary = False
self.__is_mongos = False
# _pool_class option is for deep customization of PyMongo, e.g. Motor.
# SHOULD NOT BE USED BY DEVELOPERS EXTERNAL TO 10GEN.
pool_class = kwargs.pop('_pool_class', pool.Pool)
options = {}
for option, value in kwargs.iteritems():
option, value = common.validate(option, value)
options[option] = value
options.update(opts)
self.__max_pool_size = common.validate_positive_integer(
'max_pool_size', max_pool_size)
self.__cursor_manager = CursorManager(self)
self.__repl = options.get('replicaset')
if len(seeds) == 1 and not self.__repl:
self.__direct = True
else:
self.__direct = False
self.__nodes = set()
self.__net_timeout = options.get('sockettimeoutms')
self.__conn_timeout = options.get('connecttimeoutms')
self.__use_ssl = options.get('ssl', None)
self.__ssl_keyfile = options.get('ssl_keyfile', None)
self.__ssl_certfile = options.get('ssl_certfile', None)
self.__ssl_cert_reqs = options.get('ssl_cert_reqs', None)
self.__ssl_ca_certs = options.get('ssl_ca_certs', None)
ssl_kwarg_keys = [k for k in kwargs.keys() if k.startswith('ssl_')]
if self.__use_ssl == False and ssl_kwarg_keys:
raise ConfigurationError("ssl has not been enabled but the "
"following ssl parameters have been set: "
"%s. Please set `ssl=True` or remove."
% ', '.join(ssl_kwarg_keys))
if self.__ssl_cert_reqs and not self.__ssl_ca_certs:
raise ConfigurationError("If `ssl_cert_reqs` is not "
"`ssl.CERT_NONE` then you must "
"include `ssl_ca_certs` to be able "
"to validate the server.")
if ssl_kwarg_keys and self.__use_ssl is None:
# ssl options imply ssl = True
self.__use_ssl = True
if self.__use_ssl and not HAS_SSL:
raise ConfigurationError("The ssl module is not available. If you "
"are using a python version previous to "
"2.6 you must install the ssl package "
"from PyPI.")
self.__use_greenlets = options.get('use_greenlets', False)
self.__pool = pool_class(
None,
self.__max_pool_size,
self.__net_timeout,
self.__conn_timeout,
self.__use_ssl,
use_greenlets=self.__use_greenlets,
ssl_keyfile=self.__ssl_keyfile,
ssl_certfile=self.__ssl_certfile,
ssl_cert_reqs=self.__ssl_cert_reqs,
ssl_ca_certs=self.__ssl_ca_certs)
self.__document_class = document_class
self.__tz_aware = common.validate_boolean('tz_aware', tz_aware)
self.__auto_start_request = options.get('auto_start_request', False)
# cache of existing indexes used by ensure_index ops
self.__index_cache = {}
self.__auth_credentials = {}
super(MongoClient, self).__init__(**options)
if self.slave_okay:
warnings.warn("slave_okay is deprecated. Please "
"use read_preference instead.", DeprecationWarning,
stacklevel=2)
if _connect:
try:
self.__find_node(seeds)
except AutoReconnect, e:
# ConnectionFailure makes more sense here than AutoReconnect
raise ConnectionFailure(str(e))
def __init__(self, host=None, port=None, max_pool_size=10,
network_timeout=None, document_class=dict,
tz_aware=False, _connect=True, **kwargs):
"""Create a new connection to a single MongoDB instance at *host:port*.
The resultant connection object has connection-pooling built
in. It also performs auto-reconnection when necessary. If an
operation fails because of a connection error,
:class:`~pymongo.errors.ConnectionFailure` is raised. If
auto-reconnection will be performed,
:class:`~pymongo.errors.AutoReconnect` will be
raised. Application code should handle this exception
(recognizing that the operation failed) and then continue to
execute.
Raises :class:`TypeError` if port is not an instance of
``int``. Raises :class:`~pymongo.errors.ConnectionFailure` if
the connection cannot be made.
The `host` parameter can be a full `mongodb URI
<http://dochub.mongodb.org/core/connections>`_, 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 `port` 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
escaped following RFC 2396.
:Parameters:
- `host` (optional): hostname or IP address of the
instance to connect to, or a mongodb URI, or a list of
hostnames / mongodb URIs. If `host` is an IPv6 literal
it must be enclosed in '[' and ']' characters following
the RFC2732 URL syntax (e.g. '[::1]' for localhost)
- `port` (optional): port number on which to connect
- `max_pool_size` (optional): The maximum size limit for
the connection pool.
- `network_timeout` (optional): timeout (in seconds) to use
for socket operations - default is no timeout
- `document_class` (optional): default class to use for
documents returned from queries on this connection
- `tz_aware` (optional): if ``True``,
:class:`~datetime.datetime` instances returned as values
in a document by this :class:`Connection` will be timezone
aware (otherwise they will be naive)
Other optional parameters can be passed as keyword arguments:
- `safe`: Use getlasterror for each write operation?
- `j` or `journal`: Block until write operations have been committed
to the journal. Ignored if the server is running without journaling.
Implies safe=True.
- `w`: (integer or string) If this is a replica set write operations
won't return until they have been replicated to the specified
number or tagged set of servers. `w` always includes the replica set
primary (e.g. w=3 means write to the primary and wait until replicated
to **two** secondaries). Implies safe=True.
- `wtimeout`: Used in conjunction with `j` and/or `w`. Wait this many
milliseconds for journal acknowledgement and/or write replication.
Implies safe=True.
- `fsync`: Force the database to fsync all files before returning
When used with `j` the server awaits the next group commit before
returning.
Implies safe=True.
- `replicaSet`: The name of the replica set to connect to. The driver
will verify that the replica set it connects to matches this name.
Implies that the hosts specified are a seed list and the driver should
attempt to find all members of the set.
- `socketTimeoutMS`: How long (in milliseconds) a send or receive on a
socket can take before timing out.
- `connectTimeoutMS`: How long (in milliseconds) a connection can take
to be opened before timing out.
- `ssl`: If True, create the connection to the server using SSL.
- `read_preference`: The read preference for this connection.
See :class:`~pymongo.read_preferences.ReadPreference` for available
options.
- `auto_start_request`: If True (the default), each thread that
accesses this Connection has a socket allocated to it for the
thread's lifetime. This ensures consistent reads, even if you read
after an unsafe write.
- `use_greenlets` (optional): if ``True``, :meth:`start_request()`
will ensure that the current greenlet uses the same socket for all
operations until :meth:`end_request()`
- `slave_okay` or `slaveOk` (deprecated): Use `read_preference`
instead.
.. seealso:: :meth:`end_request`
.. versionchanged:: 2.3
Added support for failover between mongos seed list members.
.. versionchanged:: 2.2
Added `auto_start_request` option back. Added `use_greenlets`
option.
.. versionchanged:: 2.1
Support `w` = integer or string.
Added `ssl` option.
DEPRECATED slave_okay/slaveOk.
.. versionchanged:: 2.0
`slave_okay` is a pure keyword argument. Added support for safe,
and getlasterror options as keyword arguments.
.. versionchanged:: 1.11
Added `max_pool_size`. Completely removed previously deprecated
`pool_size`, `auto_start_request` and `timeout` parameters.
.. versionchanged:: 1.8
The `host` parameter can now be a full `mongodb URI
<http://dochub.mongodb.org/core/connections>`_, in addition
to a simple hostname. It can also be a list of hostnames or
URIs.
.. versionadded:: 1.8
The `tz_aware` parameter.
.. versionadded:: 1.7
The `document_class` parameter.
.. versionadded:: 1.1
The `network_timeout` parameter.
.. mongodoc:: connections
"""
if host is None:
host = self.HOST
if isinstance(host, basestring):
host = [host]
if port is None:
port = self.PORT
if not isinstance(port, int):
raise TypeError("port must be an instance of int")
seeds = set()
username = None
password = None
db = None
options = {}
for entity in host:
if "://" in entity:
if entity.startswith("mongodb://"):
res = uri_parser.parse_uri(entity, port)
seeds.update(res["nodelist"])
username = res["username"] or username
password = res["password"] or password
db = res["database"] or db
options = res["options"]
else:
idx = entity.find("://")
raise InvalidURI("Invalid URI scheme: "
"%s" % (entity[:idx],))
else:
seeds.update(uri_parser.split_hosts(entity, port))
if not seeds:
raise ConfigurationError("need to specify at least one host")
self.__nodes = seeds
self.__host = None
self.__port = None
self.__is_primary = False
self.__is_mongos = False
for option, value in kwargs.iteritems():
option, value = common.validate(option, value)
options[option] = value
self.__max_pool_size = common.validate_positive_integer(
'max_pool_size', max_pool_size)
self.__cursor_manager = CursorManager(self)
self.__repl = options.get('replicaset')
if len(seeds) == 1 and not self.__repl:
self.__direct = True
else:
self.__direct = False
self.__nodes = set()
if network_timeout is not None:
if (not isinstance(network_timeout, (int, float)) or
network_timeout <= 0):
raise ConfigurationError("network_timeout must "
"be a positive integer")
self.__net_timeout = (network_timeout or
options.get('sockettimeoutms'))
self.__conn_timeout = options.get('connecttimeoutms')
self.__use_ssl = options.get('ssl', False)
if self.__use_ssl and not pool.have_ssl:
raise ConfigurationError("The ssl module is not available. If you "
"are using a python version previous to "
"2.6 you must install the ssl package "
"from PyPI.")
if options.get('use_greenlets', False):
if not pool.have_greenlet:
raise ConfigurationError(
"The greenlet module is not available. "
"Install the greenlet package from PyPI."
)
self.pool_class = pool.GreenletPool
else:
self.pool_class = pool.Pool
self.__pool = self.pool_class(
None,
self.__max_pool_size,
self.__net_timeout,
self.__conn_timeout,
self.__use_ssl
)
self.__document_class = document_class
self.__tz_aware = common.validate_boolean('tz_aware', tz_aware)
self.__auto_start_request = options.get('auto_start_request', True)
# cache of existing indexes used by ensure_index ops
self.__index_cache = {}
self.__auth_credentials = {}
super(Connection, self).__init__(**options)
if self.slave_okay:
warnings.warn("slave_okay is deprecated. Please "
"use read_preference instead.", DeprecationWarning)
if _connect:
try:
self.__find_node(seeds)
except AutoReconnect, e:
# ConnectionFailure makes more sense here than AutoReconnect
raise ConnectionFailure(str(e))
def __init__(self,
host=None,
port=None,
max_pool_size=10,
document_class=dict,
tz_aware=False,
_connect=True,
**kwargs):
"""Create a new connection to a single MongoDB instance at *host:port*.
The resultant client object has connection-pooling built
in. It also performs auto-reconnection when necessary. If an
operation fails because of a connection error,
:class:`~pymongo.errors.ConnectionFailure` is raised. If
auto-reconnection will be performed,
:class:`~pymongo.errors.AutoReconnect` will be
raised. Application code should handle this exception
(recognizing that the operation failed) and then continue to
execute.
Raises :class:`TypeError` if port is not an instance of
``int``. Raises :class:`~pymongo.errors.ConnectionFailure` if
the connection cannot be made.
The `host` parameter can be a full `mongodb URI
<http://dochub.mongodb.org/core/connections>`_, 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 `port` 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
escaped following RFC 2396.
:Parameters:
- `host` (optional): hostname or IP address of the
instance to connect to, or a mongodb URI, or a list of
hostnames / mongodb URIs. If `host` is an IPv6 literal
it must be enclosed in '[' and ']' characters following
the RFC2732 URL syntax (e.g. '[::1]' for localhost)
- `port` (optional): port number on which to connect
- `max_pool_size` (optional): The maximum number of idle connections
to keep open in the pool for future use
- `document_class` (optional): default class to use for
documents returned from queries on this client
- `tz_aware` (optional): if ``True``,
:class:`~datetime.datetime` instances returned as values
in a document by this :class:`MongoClient` will be timezone
aware (otherwise they will be naive)
| **Other optional parameters can be passed as keyword arguments:**
- `socketTimeoutMS`: (integer) How long (in milliseconds) a send or
receive on a socket can take before timing out.
- `connectTimeoutMS`: (integer) How long (in milliseconds) a
connection can take to be opened before timing out.
- `auto_start_request`: If ``True``, each thread that accesses
this :class:`MongoClient` has a socket allocated to it for the
thread's lifetime. This ensures consistent reads, even if you
read after an unacknowledged write. Defaults to ``False``
- `use_greenlets`: If ``True``, :meth:`start_request()` will ensure
that the current greenlet uses the same socket for all
operations until :meth:`end_request()`
| **Write Concern options:**
- `w`: (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. `w=<int>` always includes the replica set
primary (e.g. w=3 means write to the primary and wait until
replicated to **two** secondaries). Passing w=0 **disables write
acknowledgement** and all other write concern options.
- `wtimeout`: (integer) Used in conjunction with `w`. 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.
- `j`: If ``True`` block until write operations have been committed
to the journal. Ignored if the server is running without journaling.
- `fsync`: If ``True`` force the database to fsync all files before
returning. When used with `j` the server awaits the next group
commit before returning.
| **Replica set keyword arguments for connecting with a replica set
- either directly or via a mongos:**
| (ignored by standalone mongod instances)
- `replicaSet`: (string) The name of the replica set to connect to.
The driver will verify that the replica set it connects to matches
this name. Implies that the hosts specified are a seed list and the
driver should attempt to find all members of the set. *Ignored by
mongos*.
- `read_preference`: The read preference for this client. If
connecting to a secondary then a read preference mode *other* than
PRIMARY is required - otherwise all queries will throw
:class:`~pymongo.errors.AutoReconnect` "not master".
See :class:`~pymongo.read_preferences.ReadPreference` for all
available read preference options.
- `tag_sets`: Ignored unless connecting to a replica set via mongos.
Specify a priority-order for tag sets, provide a list of
tag sets: ``[{'dc': 'ny'}, {'dc': 'la'}, {}]``. A final, empty tag
set, ``{}``, means "read from any member that matches the mode,
ignoring tags.
| **SSL configuration:**
- `ssl`: If ``True``, create the connection to the server using SSL.
- `ssl_keyfile`: The private keyfile used to identify the local
connection against mongod. If included with the ``certfile` then
only the ``ssl_certfile`` is needed. Implies ``ssl=True``.
- `ssl_certfile`: The certificate file used to identify the local
connection against mongod. Implies ``ssl=True``.
- `ssl_cert_reqs`: 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 ``ssl.CERT_NONE``
(certificates ignored), ``ssl.CERT_OPTIONAL``
(not required, but validated if provided), or ``ssl.CERT_REQUIRED``
(required and validated). If the value of this parameter is not
``ssl.CERT_NONE``, then the ``ssl_ca_certs`` parameter must point
to a file of CA certificates. Implies ``ssl=True``.
- `ssl_ca_certs`: 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 ``ssl=True``.
.. seealso:: :meth:`end_request`
.. mongodoc:: connections
.. versionchanged:: 2.5
Added addtional ssl options
.. versionadded:: 2.4
"""
if host is None:
host = self.HOST
if isinstance(host, basestring):
host = [host]
if port is None:
port = self.PORT
if not isinstance(port, int):
raise TypeError("port must be an instance of int")
seeds = set()
username = None
password = None
db_name = None
opts = {}
for entity in host:
if "://" in entity:
if entity.startswith("mongodb://"):
res = uri_parser.parse_uri(entity, port)
seeds.update(res["nodelist"])
username = res["username"] or username
password = res["password"] or password
db_name = res["database"] or db_name
opts = res["options"]
else:
idx = entity.find("://")
raise InvalidURI("Invalid URI scheme: "
"%s" % (entity[:idx], ))
else:
seeds.update(uri_parser.split_hosts(entity, port))
if not seeds:
raise ConfigurationError("need to specify at least one host")
self.__nodes = seeds
self.__host = None
self.__port = None
self.__is_primary = False
self.__is_mongos = False
# _pool_class option is for deep customization of PyMongo, e.g. Motor.
# SHOULD NOT BE USED BY DEVELOPERS EXTERNAL TO 10GEN.
pool_class = kwargs.pop('_pool_class', pool.Pool)
options = {}
for option, value in kwargs.iteritems():
option, value = common.validate(option, value)
options[option] = value
options.update(opts)
self.__max_pool_size = common.validate_positive_integer(
'max_pool_size', max_pool_size)
self.__cursor_manager = CursorManager(self)
self.__repl = options.get('replicaset')
if len(seeds) == 1 and not self.__repl:
self.__direct = True
else:
self.__direct = False
self.__nodes = set()
self.__net_timeout = options.get('sockettimeoutms')
self.__conn_timeout = options.get('connecttimeoutms')
self.__use_ssl = options.get('ssl', None)
self.__ssl_keyfile = options.get('ssl_keyfile', None)
self.__ssl_certfile = options.get('ssl_certfile', None)
self.__ssl_cert_reqs = options.get('ssl_cert_reqs', None)
self.__ssl_ca_certs = options.get('ssl_ca_certs', None)
ssl_kwarg_keys = [k for k in kwargs.keys() if k.startswith('ssl_')]
if self.__use_ssl == False and ssl_kwarg_keys:
raise ConfigurationError("ssl has not been enabled but the "
"following ssl parameters have been set: "
"%s. Please set `ssl=True` or remove." %
', '.join(ssl_kwarg_keys))
if self.__ssl_cert_reqs and not self.__ssl_ca_certs:
raise ConfigurationError("If `ssl_cert_reqs` is not "
"`ssl.CERT_NONE` then you must "
"include `ssl_ca_certs` to be able "
"to validate the server.")
if ssl_kwarg_keys and self.__use_ssl is None:
# ssl options imply ssl = True
self.__use_ssl = True
if self.__use_ssl and not HAS_SSL:
raise ConfigurationError("The ssl module is not available. If you "
"are using a python version previous to "
"2.6 you must install the ssl package "
"from PyPI.")
self.__use_greenlets = options.get('use_greenlets', False)
self.__pool = pool_class(None,
self.__max_pool_size,
self.__net_timeout,
self.__conn_timeout,
self.__use_ssl,
use_greenlets=self.__use_greenlets,
ssl_keyfile=self.__ssl_keyfile,
ssl_certfile=self.__ssl_certfile,
ssl_cert_reqs=self.__ssl_cert_reqs,
ssl_ca_certs=self.__ssl_ca_certs)
self.__document_class = document_class
self.__tz_aware = common.validate_boolean('tz_aware', tz_aware)
self.__auto_start_request = options.get('auto_start_request', False)
# cache of existing indexes used by ensure_index ops
self.__index_cache = {}
self.__auth_credentials = {}
super(MongoClient, self).__init__(**options)
if self.slave_okay:
warnings.warn(
"slave_okay is deprecated. Please "
"use read_preference instead.",
DeprecationWarning,
stacklevel=2)
if _connect:
try:
self.__find_node(seeds)
except AutoReconnect, e:
# ConnectionFailure makes more sense here than AutoReconnect
raise ConnectionFailure(str(e))
def __init__(self,
host=None,
port=None,
max_pool_size=10,
network_timeout=None,
document_class=dict,
tz_aware=False,
_connect=True,
**kwargs):
"""Create a new connection to a single MongoDB instance at *host:port*.
The resultant connection object has connection-pooling built
in. It also performs auto-reconnection when necessary. If an
operation fails because of a connection error,
:class:`~pymongo.errors.ConnectionFailure` is raised. If
auto-reconnection will be performed,
:class:`~pymongo.errors.AutoReconnect` will be
raised. Application code should handle this exception
(recognizing that the operation failed) and then continue to
execute.
Raises :class:`TypeError` if port is not an instance of
``int``. Raises :class:`~pymongo.errors.ConnectionFailure` if
the connection cannot be made.
The `host` parameter can be a full `mongodb URI
<http://dochub.mongodb.org/core/connections>`_, 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 `port` 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
escaped following RFC 2396.
:Parameters:
- `host` (optional): hostname or IP address of the
instance to connect to, or a mongodb URI, or a list of
hostnames / mongodb URIs. If `host` is an IPv6 literal
it must be enclosed in '[' and ']' characters following
the RFC2732 URL syntax (e.g. '[::1]' for localhost)
- `port` (optional): port number on which to connect
- `max_pool_size` (optional): The maximum size limit for
the connection pool.
- `network_timeout` (optional): timeout (in seconds) to use
for socket operations - default is no timeout
- `document_class` (optional): default class to use for
documents returned from queries on this connection
- `tz_aware` (optional): if ``True``,
:class:`~datetime.datetime` instances returned as values
in a document by this :class:`Connection` will be timezone
aware (otherwise they will be naive)
Other optional parameters can be passed as keyword arguments:
- `safe`: Use getlasterror for each write operation?
- `j` or `journal`: Block until write operations have been committed
to the journal. Ignored if the server is running without journaling.
Implies safe=True.
- `w`: (integer or string) If this is a replica set write operations
won't return until they have been replicated to the specified
number or tagged set of servers.
Implies safe=True.
- `wtimeout`: Used in conjunction with `j` and/or `w`. Wait this many
milliseconds for journal acknowledgement and/or write replication.
Implies safe=True.
- `fsync`: Force the database to fsync all files before returning
When used with `j` the server awaits the next group commit before
returning.
Implies safe=True.
- `replicaSet`: The name of the replica set to connect to. The driver
will verify that the replica set it connects to matches this name.
Implies that the hosts specified are a seed list and the driver should
attempt to find all members of the set.
- `socketTimeoutMS`: How long a send or receive on a socket can take
before timing out.
- `connectTimeoutMS`: How long a connection can take to be opened
before timing out.
- `ssl`: If True, create the connection to the server using SSL.
- `read_preference`: The read preference for this connection.
See :class:`~pymongo.read_preferences.ReadPreference` for available
options.
- `auto_start_request`: If True (the default), each thread that
accesses this Connection has a socket allocated to it for the
thread's lifetime. This ensures consistent reads, even if you read
after an unsafe write.
- `use_greenlets` (optional): if ``True``, :meth:`start_request()`
will ensure that the current greenlet uses the same socket for all
operations until :meth:`end_request()`
- `slave_okay` or `slaveOk` (deprecated): Use `read_preference`
instead.
.. seealso:: :meth:`end_request`
.. versionchanged:: 2.3
Added support for failover between mongos seed list members.
.. versionchanged:: 2.2
Added `auto_start_request` option back. Added `use_greenlets`
option.
.. versionchanged:: 2.1
Support `w` = integer or string.
Added `ssl` option.
DEPRECATED slave_okay/slaveOk.
.. versionchanged:: 2.0
`slave_okay` is a pure keyword argument. Added support for safe,
and getlasterror options as keyword arguments.
.. versionchanged:: 1.11
Added `max_pool_size`. Completely removed previously deprecated
`pool_size`, `auto_start_request` and `timeout` parameters.
.. versionchanged:: 1.8
The `host` parameter can now be a full `mongodb URI
<http://dochub.mongodb.org/core/connections>`_, in addition
to a simple hostname. It can also be a list of hostnames or
URIs.
.. versionadded:: 1.8
The `tz_aware` parameter.
.. versionadded:: 1.7
The `document_class` parameter.
.. versionadded:: 1.1
The `network_timeout` parameter.
.. mongodoc:: connections
"""
if host is None:
host = self.HOST
if isinstance(host, basestring):
host = [host]
if port is None:
port = self.PORT
if not isinstance(port, int):
raise TypeError("port must be an instance of int")
seeds = set()
username = None
password = None
db = None
options = {}
for entity in host:
if "://" in entity:
if entity.startswith("mongodb://"):
res = uri_parser.parse_uri(entity, port)
seeds.update(res["nodelist"])
username = res["username"] or username
password = res["password"] or password
db = res["database"] or db
options = res["options"]
else:
idx = entity.find("://")
raise InvalidURI("Invalid URI scheme: "
"%s" % (entity[:idx], ))
else:
seeds.update(uri_parser.split_hosts(entity, port))
if not seeds:
raise ConfigurationError("need to specify at least one host")
self.__nodes = seeds
self.__host = None
self.__port = None
self.__is_primary = False
self.__is_mongos = False
for option, value in kwargs.iteritems():
option, value = common.validate(option, value)
options[option] = value
self.__max_pool_size = common.validate_positive_integer(
'max_pool_size', max_pool_size)
self.__cursor_manager = CursorManager(self)
self.__repl = options.get('replicaset')
if len(seeds) == 1 and not self.__repl:
self.__direct = True
else:
self.__direct = False
self.__nodes = set()
if network_timeout is not None:
if (not isinstance(network_timeout, (int, float))
or network_timeout <= 0):
raise ConfigurationError("network_timeout must "
"be a positive integer")
self.__net_timeout = (network_timeout
or options.get('sockettimeoutms'))
self.__conn_timeout = options.get('connecttimeoutms')
self.__use_ssl = options.get('ssl', False)
if self.__use_ssl and not pool.have_ssl:
raise ConfigurationError("The ssl module is not available. If you "
"are using a python version previous to "
"2.6 you must install the ssl package "
"from PyPI.")
if options.get('use_greenlets', False):
if not pool.have_greenlet:
raise ConfigurationError(
"The greenlet module is not available. "
"Install the greenlet package from PyPI.")
self.pool_class = pool.GreenletPool
else:
self.pool_class = pool.Pool
self.__pool = self.pool_class(None, self.__max_pool_size,
self.__net_timeout, self.__conn_timeout,
self.__use_ssl)
self.__document_class = document_class
self.__tz_aware = common.validate_boolean('tz_aware', tz_aware)
self.__auto_start_request = options.get('auto_start_request', True)
# cache of existing indexes used by ensure_index ops
self.__index_cache = {}
self.__auth_credentials = {}
super(Connection, self).__init__(**options)
if self.slave_okay:
warnings.warn(
"slave_okay is deprecated. Please "
"use read_preference instead.", DeprecationWarning)
if _connect:
self.__find_node(seeds)
if db and username is None:
warnings.warn("must provide a username and password "
"to authenticate to %s" % (db, ))
if username:
db = db or "admin"
if not self[db].authenticate(username, password):
raise ConfigurationError("authentication failed")
def __init__(self, hosts_or_uri=None, max_pool_size=10,
document_class=dict, tz_aware=False, **kwargs):
"""Create a new connection to a MongoDB replica set.
The resultant connection object has connection-pooling built
in. It also performs auto-reconnection when necessary. If an
operation fails because of a connection error,
:class:`~pymongo.errors.ConnectionFailure` is raised. If
auto-reconnection will be performed,
:class:`~pymongo.errors.AutoReconnect` will be
raised. Application code should handle this exception
(recognizing that the operation failed) and then continue to
execute.
Raises :class:`~pymongo.errors.ConnectionFailure` if
the connection cannot be made.
The `hosts_or_uri` parameter can be a full `mongodb URI
<http://dochub.mongodb.org/core/connections>`_, in addition to
a string of `host:port` pairs (e.g. 'host1:port1,host2:port2').
If `hosts_or_uri` is None 'localhost:27017' will be used.
:Parameters:
- `hosts_or_uri` (optional): A MongoDB URI or string of `host:port`
pairs. If a host is an IPv6 literal it must be enclosed in '[' and
']' characters following the RFC2732 URL syntax (e.g. '[::1]' for
localhost)
- `max_pool_size` (optional): The maximum size limit for
each connection pool.
- `document_class` (optional): default class to use for
documents returned from queries on this connection
- `tz_aware` (optional): if ``True``,
:class:`~datetime.datetime` instances returned as values
in a document by this :class:`ReplicaSetConnection` will be timezone
aware (otherwise they will be naive)
- `replicaSet`: (required) The name of the replica set to connect to.
The driver will verify that each host it connects to is a member of
this replica set. Can be passed as a keyword argument or as a
MongoDB URI option.
Other optional parameters can be passed as keyword arguments:
- `safe`: Use getlasterror for each write operation?
- `j` or `journal`: Block until write operations have been commited
to the journal. Ignored if the server is running without
journaling. Implies safe=True.
- `w`: (integer or string) If this is a replica set write operations
won't return until they have been replicated to the specified
number or tagged set of servers.
Implies safe=True.
- `wtimeoutMS`: Used in conjunction with `j` and/or `w`. Wait this
many milliseconds for journal acknowledgement and/or write
replication. Implies safe=True.
- `fsync`: Force the database to fsync all files before returning
When used with `j` the server awaits the next group commit before
returning. Implies safe=True.
- `socketTimeoutMS`: How long a send or receive on a socket can take
before timing out.
- `connectTimeoutMS`: How long a connection can take to be opened
before timing out.
- `ssl`: If True, create the connection to the servers using SSL.
- `read_preference`: The read preference for this connection.
See :class:`~pymongo.ReadPreference` for available options.
- `auto_start_request`: If True (the default), each thread that
accesses this :class:`ReplicaSetConnection` has a socket allocated
to it for the thread's lifetime, for each member of the set. For
:class:`~pymongo.ReadPreference` PRIMARY, auto_start_request=True
ensures consistent reads, even if you read after an unsafe
write. For read preferences other than PRIMARY, there are no
consistency guarantees. (The semantics of auto_start_request,
:class:`~pymongo.ReadPreference`, and :class:`ReplicaSetConnection`
may change in future releases of PyMongo.)
- `use_greenlets` (optional): if ``True``, :meth:`start_request()`
will ensure that the current greenlet uses the same socket for all
operations until :meth:`end_request()`
- `slave_okay` or `slaveOk` (deprecated): Use `read_preference`
instead.
.. versionchanged:: 2.1.1+
Added `auto_start_request` option.
.. versionadded:: 2.1
"""
self.__opts = {}
self.__seeds = set()
self.__hosts = None
self.__arbiters = set()
self.__writer = None
self.__readers = []
self.__pools = {}
self.__index_cache = {}
self.__auth_credentials = {}
self.__max_pool_size = common.validate_positive_integer(
'max_pool_size', max_pool_size)
self.__tz_aware = common.validate_boolean('tz_aware', tz_aware)
self.__document_class = document_class
username = None
db_name = None
if hosts_or_uri is None:
self.__seeds.add(('localhost', 27017))
elif '://' in hosts_or_uri:
res = uri_parser.parse_uri(hosts_or_uri)
self.__seeds.update(res['nodelist'])
username = res['username']
password = res['password']
db_name = res['database']
self.__opts = res['options']
else:
self.__seeds.update(uri_parser.split_hosts(hosts_or_uri))
for option, value in kwargs.iteritems():
option, value = common.validate(option, value)
self.__opts[option] = value
if self.__opts.get('use_greenlets', False):
if not pool.have_greenlet:
raise ConfigurationError(
"The greenlet module is not available. "
"Install the greenlet package from PyPI."
)
self.pool_class = pool.GreenletPool
else:
self.pool_class = pool.Pool
self.__auto_start_request = self.__opts.get('auto_start_request', True)
self.__in_request = self.__auto_start_request
self.__name = self.__opts.get('replicaset')
if not self.__name:
raise ConfigurationError("the replicaSet "
"keyword parameter is required.")
self.__net_timeout = self.__opts.get('sockettimeoutms')
self.__conn_timeout = self.__opts.get('connecttimeoutms')
self.__use_ssl = self.__opts.get('ssl', False)
if self.__use_ssl and not pool.have_ssl:
raise ConfigurationError("The ssl module is not available. If you "
"are using a python version previous to "
"2.6 you must install the ssl package "
"from PyPI.")
super(ReplicaSetConnection, self).__init__(**self.__opts)
if self.slave_okay:
warnings.warn("slave_okay is deprecated. Please "
"use read_preference instead.", DeprecationWarning)
self.refresh()
monitor_thread = Monitor(self)
monitor_thread.setName("ReplicaSetMonitorThread")
monitor_thread.setDaemon(True)
monitor_thread.start()
if db_name and username is None:
warnings.warn("must provide a username and password "
"to authenticate to %s" % (db_name,))
if username:
db_name = db_name or 'admin'
if not self[db_name].authenticate(username, password):
raise ConfigurationError("authentication failed")
def __init__(self, hosts_or_uri=None, max_pool_size=10, document_class=dict, tz_aware=False, **kwargs):
"""Create a new connection to a MongoDB replica set.
The resultant connection object has connection-pooling built
in. It also performs auto-reconnection when necessary. If an
operation fails because of a connection error,
:class:`~pymongo.errors.ConnectionFailure` is raised. If
auto-reconnection will be performed,
:class:`~pymongo.errors.AutoReconnect` will be
raised. Application code should handle this exception
(recognizing that the operation failed) and then continue to
execute.
Raises :class:`~pymongo.errors.ConnectionFailure` if
the connection cannot be made.
The `hosts_or_uri` parameter can be a full `mongodb URI
<http://dochub.mongodb.org/core/connections>`_, in addition to
a string of `host:port` pairs (e.g. 'host1:port1,host2:port2').
If `hosts_or_uri` is None 'localhost:27017' will be used.
:Parameters:
- `hosts_or_uri` (optional): A MongoDB URI or string of `host:port`
pairs. If a host is an IPv6 literal it must be enclosed in '[' and
']' characters following the RFC2732 URL syntax (e.g. '[::1]' for
localhost)
- `max_pool_size` (optional): The maximum size limit for
each connection pool.
- `document_class` (optional): default class to use for
documents returned from queries on this connection
- `tz_aware` (optional): if ``True``,
:class:`~datetime.datetime` instances returned as values
in a document by this :class:`ReplicaSetConnection` will be timezone
aware (otherwise they will be naive)
- `replicaSet`: (required) The name of the replica set to connect to.
The driver will verify that each host it connects to is a member of
this replica set. Can be passed as a keyword argument or as a
MongoDB URI option.
Other optional parameters can be passed as keyword arguments:
- `safe`: Use getlasterror for each write operation?
- `j` or `journal`: Block until write operations have been commited
to the journal. Ignored if the server is running without
journaling. Implies safe=True.
- `w`: (integer or string) If this is a replica set write operations
won't return until they have been replicated to the specified
number or tagged set of servers.
Implies safe=True.
- `wtimeoutMS`: Used in conjunction with `j` and/or `w`. Wait this
many milliseconds for journal acknowledgement and/or write
replication. Implies safe=True.
- `fsync`: Force the database to fsync all files before returning
When used with `j` the server awaits the next group commit before
returning. Implies safe=True.
- `socketTimeoutMS`: How long a send or receive on a socket can take
before timing out.
- `connectTimeoutMS`: How long a connection can take to be opened
before timing out.
- `ssl`: If True, create the connection to the servers using SSL.
- `read_preference`: The read preference for this connection.
See :class:`~pymongo.ReadPreference` for available options.
- `auto_start_request`: If True (the default), each thread that
accesses this :class:`ReplicaSetConnection` has a socket allocated
to it for the thread's lifetime, for each member of the set. For
:class:`~pymongo.ReadPreference` PRIMARY, auto_start_request=True
ensures consistent reads, even if you read after an unsafe
write. For read preferences other than PRIMARY, there are no
consistency guarantees. (The semantics of auto_start_request,
:class:`~pymongo.ReadPreference`, and :class:`ReplicaSetConnection`
may change in future releases of PyMongo.)
- `use_greenlets` (optional): if ``True``, use a background Greenlet
instead of a background thread to monitor state of replica set.
:meth:`start_request()` will ensure that the current greenlet uses
the same socket for all operations until :meth:`end_request()`.
`use_greenlets` with ReplicaSetConnection requires `Gevent
<http://gevent.org/>`_ to be installed.
- `slave_okay` or `slaveOk` (deprecated): Use `read_preference`
instead.
- `host`: For compatibility with connection.Connection. If both
`host` and `hosts_or_uri` are specified `host` takes precedence.
- `port`: For compatibility with connection.Connection. The default
port number to use for hosts.
- `network_timeout`: For compatibility with connection.Connection.
The timeout (in seconds) to use for socket operations - default
is no timeout. If both `network_timeout` and `socketTimeoutMS` are
are specified `network_timeout` takes precedence, matching
connection.Connection.
.. versionchanged:: 2.2
Added `auto_start_request` and `use_greenlets` options.
Added support for `host`, `port`, and `network_timeout` keyword
arguments for compatibility with connection.Connection.
.. versionadded:: 2.1
"""
self.__opts = {}
self.__seeds = set()
self.__hosts = None
self.__arbiters = set()
self.__writer = None
self.__readers = []
self.__pools = {}
self.__index_cache = {}
self.__auth_credentials = {}
self.__max_pool_size = common.validate_positive_integer("max_pool_size", max_pool_size)
self.__tz_aware = common.validate_boolean("tz_aware", tz_aware)
self.__document_class = document_class
# Compatibility with connection.Connection
host = kwargs.pop("host", hosts_or_uri)
port = kwargs.pop("port", 27017)
if not isinstance(port, int):
raise TypeError("port must be an instance of int")
network_timeout = kwargs.pop("network_timeout", None)
if network_timeout is not None:
if not isinstance(network_timeout, (int, float)) or network_timeout <= 0:
raise ConfigurationError("network_timeout must " "be a positive integer")
username = None
db_name = None
if host is None:
self.__seeds.add(("localhost", port))
elif "://" in host:
res = uri_parser.parse_uri(host, port)
self.__seeds.update(res["nodelist"])
username = res["username"]
password = res["password"]
db_name = res["database"]
self.__opts = res["options"]
else:
self.__seeds.update(uri_parser.split_hosts(host, port))
for option, value in kwargs.iteritems():
option, value = common.validate(option, value)
self.__opts[option] = value
if self.__opts.get("use_greenlets", False):
if not have_gevent:
raise ConfigurationError("The gevent module is not available. " "Install the gevent package from PyPI.")
self.pool_class = pool.GreenletPool
else:
self.pool_class = pool.Pool
self.__auto_start_request = self.__opts.get("auto_start_request", True)
self.__in_request = self.__auto_start_request
self.__name = self.__opts.get("replicaset")
if not self.__name:
raise ConfigurationError("the replicaSet " "keyword parameter is required.")
self.__net_timeout = network_timeout or self.__opts.get("sockettimeoutms")
self.__conn_timeout = self.__opts.get("connecttimeoutms")
self.__use_ssl = self.__opts.get("ssl", False)
if self.__use_ssl and not pool.have_ssl:
raise ConfigurationError(
"The ssl module is not available. If you "
"are using a python version previous to "
"2.6 you must install the ssl package "
"from PyPI."
)
super(ReplicaSetConnection, self).__init__(**self.__opts)
if self.slave_okay:
warnings.warn("slave_okay is deprecated. Please " "use read_preference instead.", DeprecationWarning)
self.refresh()
if db_name and username is None:
warnings.warn("must provide a username and password " "to authenticate to %s" % (db_name,))
if username:
db_name = db_name or "admin"
if not self[db_name].authenticate(username, password):
raise ConfigurationError("authentication failed")
# Start the monitor after we know the configuration is correct.
if self.__opts.get("use_greenlets", False):
monitor = GreenletMonitor(self)
else:
# NOTE: Don't ever make this a daemon thread in CPython. Daemon
# threads in CPython cause serious issues when the interpreter is
# torn down. Symptoms range from random exceptions to the
# interpreter dumping core.
monitor = Monitor(self)
monitor.setName("ReplicaSetMonitorThread")
# Sadly, weakrefs aren't totally reliable in PyPy and Jython
# so use a daemon thread there.
if sys.platform.startswith("java") or "PyPy" in sys.version:
monitor.setDaemon(True)
monitor.start()
def __init__(self,
host=None,
port=None,
max_pool_size=10,
document_class=dict,
tz_aware=False,
_connect=True,
**kwargs):
"""Create a new connection to a single MongoDB instance at *host:port*.
The resultant connection object has connection-pooling built
in. It also performs auto-reconnection when necessary. If an
operation fails because of a connection error,
:class:`~pymongo.errors.ConnectionFailure` is raised. If
auto-reconnection will be performed,
:class:`~pymongo.errors.AutoReconnect` will be
raised. Application code should handle this exception
(recognizing that the operation failed) and then continue to
execute.
Raises :class:`TypeError` if port is not an instance of
``int``. Raises :class:`~pymongo.errors.ConnectionFailure` if
the connection cannot be made.
The `host` parameter can be a full `mongodb URI
<http://dochub.mongodb.org/core/connections>`_, 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 `port` 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
escaped following RFC 2396.
:Parameters:
- `host` (optional): hostname or IP address of the
instance to connect to, or a mongodb URI, or a list of
hostnames / mongodb URIs. If `host` is an IPv6 literal
it must be enclosed in '[' and ']' characters following
the RFC2732 URL syntax (e.g. '[::1]' for localhost)
- `port` (optional): port number on which to connect
- `max_pool_size` (optional): The maximum number of idle connections
to keep open in the pool for future use
- `document_class` (optional): default class to use for
documents returned from queries on this connection
- `tz_aware` (optional): if ``True``,
:class:`~datetime.datetime` instances returned as values
in a document by this :class:`MongoClient` will be timezone
aware (otherwise they will be naive)
**Other optional parameters can be passed as keyword arguments:**
- `w`: (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. `w=<int>` always includes the replica set
primary (e.g. w=3 means write to the primary and wait until
replicated to **two** secondaries). **Passing w=0 disables write
acknowledgement and all other write concern options.**
- `wtimeout`: (integer) Used in conjunction with `w`. 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.
- `j`: If ``True`` block until write operations have been committed
to the journal. Ignored if the server is running without journaling.
- `fsync`: If ``True`` force the database to fsync all files before
returning. When used with `j` the server awaits the next group
commit before returning.
- `replicaSet`: (string) The name of the replica set to connect to.
The driver will verify that the replica set it connects to matches
this name. Implies that the hosts specified are a seed list and the
driver should attempt to find all members of the set.
- `socketTimeoutMS`: (integer) How long (in milliseconds) a send or
receive on a socket can take before timing out.
- `connectTimeoutMS`: (integer) How long (in milliseconds) a
connection can take to be opened before timing out.
- `ssl`: If ``True``, create the connection to the server using SSL.
- `read_preference`: The read preference for this connection.
See :class:`~pymongo.read_preferences.ReadPreference` for available
options.
- `auto_start_request`: If ``True``, each thread that accesses
this :class:`MongoClient` has a socket allocated to it for the
thread's lifetime. This ensures consistent reads, even if you
read after an unacknowledged write. Defaults to ``False``
- `use_greenlets`: If ``True``, :meth:`start_request()` will ensure
that the current greenlet uses the same socket for all
operations until :meth:`end_request()`
.. seealso:: :meth:`end_request`
.. mongodoc:: connections
.. versionadded:: 2.4
"""
if host is None:
host = self.HOST
if isinstance(host, basestring):
host = [host]
if port is None:
port = self.PORT
if not isinstance(port, int):
raise TypeError("port must be an instance of int")
seeds = set()
username = None
password = None
db = None
opts = {}
for entity in host:
if "://" in entity:
if entity.startswith("mongodb://"):
res = uri_parser.parse_uri(entity, port)
seeds.update(res["nodelist"])
username = res["username"] or username
password = res["password"] or password
db = res["database"] or db
opts = res["options"]
else:
idx = entity.find("://")
raise InvalidURI("Invalid URI scheme: "
"%s" % (entity[:idx], ))
else:
seeds.update(uri_parser.split_hosts(entity, port))
if not seeds:
raise ConfigurationError("need to specify at least one host")
self.__nodes = seeds
self.__host = None
self.__port = None
self.__is_primary = False
self.__is_mongos = False
options = {}
for option, value in kwargs.iteritems():
option, value = common.validate(option, value)
options[option] = value
options.update(opts)
self.__max_pool_size = common.validate_positive_integer(
'max_pool_size', max_pool_size)
self.__cursor_manager = CursorManager(self)
self.__repl = options.get('replicaset')
if len(seeds) == 1 and not self.__repl:
self.__direct = True
else:
self.__direct = False
self.__nodes = set()
self.__net_timeout = options.get('sockettimeoutms')
self.__conn_timeout = options.get('connecttimeoutms')
self.__use_ssl = options.get('ssl', False)
if self.__use_ssl and not pool.have_ssl:
raise ConfigurationError("The ssl module is not available. If you "
"are using a python version previous to "
"2.6 you must install the ssl package "
"from PyPI.")
if options.get('use_greenlets', False):
if not pool.have_greenlet:
raise ConfigurationError(
"The greenlet module is not available. "
"Install the greenlet package from PyPI.")
self.pool_class = pool.GreenletPool
else:
self.pool_class = pool.Pool
self.__pool = self.pool_class(None, self.__max_pool_size,
self.__net_timeout, self.__conn_timeout,
self.__use_ssl)
self.__document_class = document_class
self.__tz_aware = common.validate_boolean('tz_aware', tz_aware)
self.__auto_start_request = options.get('auto_start_request', False)
# cache of existing indexes used by ensure_index ops
self.__index_cache = {}
self.__auth_credentials = {}
super(MongoClient, self).__init__(**options)
if self.slave_okay:
warnings.warn(
"slave_okay is deprecated. Please "
"use read_preference instead.", DeprecationWarning)
if _connect:
try:
self.__find_node(seeds)
except AutoReconnect, e:
# ConnectionFailure makes more sense here than AutoReconnect
raise ConnectionFailure(str(e))
def __init__(
self, host=None, port=None, max_pool_size=10, document_class=dict, tz_aware=False, _connect=True, **kwargs
):
"""Create a new connection to a single MongoDB instance at *host:port*.
The resultant connection object has connection-pooling built
in. It also performs auto-reconnection when necessary. If an
operation fails because of a connection error,
:class:`~pymongo.errors.ConnectionFailure` is raised. If
auto-reconnection will be performed,
:class:`~pymongo.errors.AutoReconnect` will be
raised. Application code should handle this exception
(recognizing that the operation failed) and then continue to
execute.
Raises :class:`TypeError` if port is not an instance of
``int``. Raises :class:`~pymongo.errors.ConnectionFailure` if
the connection cannot be made.
The `host` parameter can be a full `mongodb URI
<http://dochub.mongodb.org/core/connections>`_, 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 `port` 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
escaped following RFC 2396.
:Parameters:
- `host` (optional): hostname or IP address of the
instance to connect to, or a mongodb URI, or a list of
hostnames / mongodb URIs. If `host` is an IPv6 literal
it must be enclosed in '[' and ']' characters following
the RFC2732 URL syntax (e.g. '[::1]' for localhost)
- `port` (optional): port number on which to connect
- `max_pool_size` (optional): The maximum number of idle connections
to keep open in the pool for future use
- `document_class` (optional): default class to use for
documents returned from queries on this connection
- `tz_aware` (optional): if ``True``,
:class:`~datetime.datetime` instances returned as values
in a document by this :class:`MongoClient` will be timezone
aware (otherwise they will be naive)
**Other optional parameters can be passed as keyword arguments:**
- `w`: (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. `w=<int>` always includes the replica set
primary (e.g. w=3 means write to the primary and wait until
replicated to **two** secondaries). **Passing w=0 disables write
acknowledgement and all other write concern options.**
- `wtimeout`: (integer) Used in conjunction with `w`. 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.
- `j`: If ``True`` block until write operations have been committed
to the journal. Ignored if the server is running without journaling.
- `fsync`: If ``True`` force the database to fsync all files before
returning. When used with `j` the server awaits the next group
commit before returning.
- `replicaSet`: (string) The name of the replica set to connect to.
The driver will verify that the replica set it connects to matches
this name. Implies that the hosts specified are a seed list and the
driver should attempt to find all members of the set.
- `socketTimeoutMS`: (integer) How long (in milliseconds) a send or
receive on a socket can take before timing out.
- `connectTimeoutMS`: (integer) How long (in milliseconds) a
connection can take to be opened before timing out.
- `ssl`: If ``True``, create the connection to the server using SSL.
- `read_preference`: The read preference for this connection.
See :class:`~pymongo.read_preferences.ReadPreference` for available
options.
- `auto_start_request`: If ``True``, each thread that accesses
this :class:`MongoClient` has a socket allocated to it for the
thread's lifetime. This ensures consistent reads, even if you
read after an unacknowledged write. Defaults to ``False``
- `use_greenlets`: If ``True``, :meth:`start_request()` will ensure
that the current greenlet uses the same socket for all
operations until :meth:`end_request()`
.. seealso:: :meth:`end_request`
.. mongodoc:: connections
.. versionadded:: 2.4
"""
if host is None:
host = self.HOST
if isinstance(host, basestring):
host = [host]
if port is None:
port = self.PORT
if not isinstance(port, int):
raise TypeError("port must be an instance of int")
seeds = set()
username = None
password = None
db = None
opts = {}
for entity in host:
if "://" in entity:
if entity.startswith("mongodb://"):
res = uri_parser.parse_uri(entity, port)
seeds.update(res["nodelist"])
username = res["username"] or username
password = res["password"] or password
db = res["database"] or db
opts = res["options"]
else:
idx = entity.find("://")
raise InvalidURI("Invalid URI scheme: " "%s" % (entity[:idx],))
else:
seeds.update(uri_parser.split_hosts(entity, port))
if not seeds:
raise ConfigurationError("need to specify at least one host")
self.__nodes = seeds
self.__host = None
self.__port = None
self.__is_primary = False
self.__is_mongos = False
options = {}
for option, value in kwargs.iteritems():
option, value = common.validate(option, value)
options[option] = value
options.update(opts)
self.__max_pool_size = common.validate_positive_integer("max_pool_size", max_pool_size)
self.__cursor_manager = CursorManager(self)
self.__repl = options.get("replicaset")
if len(seeds) == 1 and not self.__repl:
self.__direct = True
else:
self.__direct = False
self.__nodes = set()
self.__net_timeout = options.get("sockettimeoutms")
self.__conn_timeout = options.get("connecttimeoutms")
self.__use_ssl = options.get("ssl", False)
if self.__use_ssl and not pool.have_ssl:
raise ConfigurationError(
"The ssl module is not available. If you "
"are using a python version previous to "
"2.6 you must install the ssl package "
"from PyPI."
)
use_greenlets = options.get("use_greenlets", False)
self.__pool = pool.Pool(
None, self.__max_pool_size, self.__net_timeout, self.__conn_timeout, self.__use_ssl, use_greenlets
)
self.__document_class = document_class
self.__tz_aware = common.validate_boolean("tz_aware", tz_aware)
self.__auto_start_request = options.get("auto_start_request", False)
# cache of existing indexes used by ensure_index ops
self.__index_cache = {}
self.__auth_credentials = {}
super(MongoClient, self).__init__(**options)
if self.slave_okay:
warnings.warn("slave_okay is deprecated. Please " "use read_preference instead.", DeprecationWarning)
if _connect:
try:
self.__find_node(seeds)
except AutoReconnect, e:
# ConnectionFailure makes more sense here than AutoReconnect
raise ConnectionFailure(str(e))
