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, host=None, port=None, io_loop=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 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.
- `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.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.1.1+
Added `auto_start_request` option back.
.. 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")
nodes = set()
database = None
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)
nodes.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:
nodes.update(uri_parser.split_hosts(entity, port))
if not nodes:
raise ConfigurationError("need to specify at least one host")
self.__nodes = nodes
self.__host = None
self.__port = None
self.__io_loop = io_loop
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 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.ConnectionStreamPool
else:
self.pool_class = pool.ConnectionStreamPool
self.__pool = self.pool_class(
(self.HOST, self.PORT, ),
# self.__max_pool_size,
self.__net_timeout,
self.__conn_timeout,
self.__use_ssl,
self.io_loop,
0,
0,
0,
5
)
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:
def mod_callback(response):
"""docstring for mod_callback"""
pass
self.__find_node(mod_callback)
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")