Skip to content
Browse files

Documentation clarifications PYTHON-486 / PYTHON-487

  • Loading branch information...
1 parent 1ba099a commit cf9dca69701a4a3ac9a45466da08922a342e097e @rozza rozza committed Mar 7, 2013
View
6 doc/api/pymongo/database.rst
@@ -17,7 +17,11 @@
Get the `collection_name` :class:`~pymongo.collection.Collection` of
:class:`Database` `db`.
- Raises :class:`~pymongo.errors.InvalidName` if an invalid collection name is used.
+ Raises :class:`~pymongo.errors.InvalidName` if an invalid collection
+ name is used.
+
+ .. note:: Use dictionary style access if `collection_name` is an
+ attribute of the :class:`Database` class eg: db[`collection_name`].
.. autoattribute:: read_preference
.. autoattribute:: tag_sets
View
6 doc/examples/high_availability.rst
@@ -258,6 +258,12 @@ number. In that case, MongoReplicaSetClient distributes reads among matching
members within ``secondary_acceptable_latency_ms`` of the closest member's
ping time.
+.. note:: ``secondary_acceptable_latency_ms`` is ignored when talking to a
+ replica set *through* a mongos. The equivalent is the localThreshold_ command
+ line option.
+
+.. _localThreshold: http://docs.mongodb.org/manual/reference/mongos/#cmdoption-mongos--localThreshold
+
Health Monitoring
'''''''''''''''''
View
3 pymongo/collection.py
@@ -676,6 +676,8 @@ def find(self, *args, **kwargs):
- `secondary_acceptable_latency_ms` (optional): Any replica-set
member whose ping time is within secondary_acceptable_latency_ms of
the nearest member may accept reads. Default 15 milliseconds.
+ **Ignored by mongos** and must be configured on the command line.
+ See the localThreshold_ option for more information.
.. note:: The `manipulate` parameter may default to False in
a future release.
@@ -703,6 +705,7 @@ def find(self, *args, **kwargs):
The `tailable` parameter.
.. mongodoc:: find
+ .. _localThreshold: http://docs.mongodb.org/manual/reference/mongos/#cmdoption-mongos--localThreshold
"""
if not 'slave_okay' in kwargs:
kwargs['slave_okay'] = self.slave_okay
View
6 pymongo/common.py
@@ -435,6 +435,12 @@ def __get_acceptable_latency(self):
See :class:`~pymongo.read_preferences.ReadPreference`.
.. versionadded:: 2.3
+
+ .. note:: ``secondary_acceptable_latency_ms`` is ignored when talking to a
+ replica set *through* a mongos. The equivalent is the localThreshold_ command
+ line option.
+
+ .. _localThreshold: http://docs.mongodb.org/manual/reference/mongos/#cmdoption-mongos--localThreshold
"""
return self.__secondary_acceptable_latency_ms
View
60 pymongo/connection.py
@@ -95,7 +95,21 @@ def __init__(self, host=None, port=None, max_pool_size=10,
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:**
+ | **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`` (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`: 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:**
- `safe`: :class:`Connection` **disables** acknowledgement of write
operations. Use ``safe=True`` to enable write acknowledgement.
@@ -114,27 +128,33 @@ def __init__(self, host=None, port=None, max_pool_size=10,
- `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. Implies safe=True.
- - `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`` (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`: if ``True``, :meth:`start_request()` will ensure
- that the current greenlet uses the same socket for all operations
- until :meth:`end_request()`
+
+ | **Replica-set keyword arguments for connecting with a replica-set
+ - either directly or via a mongos:**
+ | (ignored by standalone mongod instances)
+
- `slave_okay` or `slaveOk` (deprecated): Use `read_preference`
instead.
+ - `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 a
+ :class:`~pymongo.errors.AutoReconnect` "not master" error.
+ 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``.
View
3 pymongo/database.py
@@ -328,6 +328,8 @@ def command(self, command, value=1,
- `secondary_acceptable_latency_ms`: Any replica-set member whose
ping time is within secondary_acceptable_latency_ms of the nearest
member may accept reads. Default 15 milliseconds.
+ **Ignored by mongos** and must be configured on the command line.
+ See the localThreshold_ option for more information.
- `**kwargs` (optional): additional keyword arguments will
be added to the command document before it is sent
@@ -344,6 +346,7 @@ def command(self, command, value=1,
.. versionadded:: 1.4
.. mongodoc:: commands
+ .. _localThreshold: http://docs.mongodb.org/manual/reference/mongos/#cmdoption-mongos--localThreshold
"""
if isinstance(command, basestring):
View
58 pymongo/mongo_client.py
@@ -129,14 +129,28 @@ def __init__(self, host=None, port=None, max_pool_size=10,
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:**
+ | **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.**
+ 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
@@ -146,25 +160,31 @@ def __init__(self, host=None, port=None, max_pool_size=10,
- `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.
- - `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.
+ 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.
- - `read_preference`: The read preference for this client.
- 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()`
- `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``.
@@ -452,7 +472,7 @@ def port(self):
@property
def is_primary(self):
- """If this instance is connected to a standalone, a replica-set
+ """If this instance is connected to a standalone, a replica set
primary, or the master of a master-slave set.
.. versionadded:: 2.3
View
66 pymongo/mongo_replica_set_client.py
@@ -320,14 +320,39 @@ def __init__(self, hosts_or_uri=None, max_pool_size=10,
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:**
+ | **Other optional parameters can be passed as keyword arguments:**
+
+ - `host`: For compatibility with :class:`~mongo_client.MongoClient`.
+ If both `host` and `hosts_or_uri` are specified `host` takes
+ precedence.
+ - `port`: For compatibility with :class:`~mongo_client.MongoClient`.
+ The default port number to use for hosts.
+ - `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:`MongoReplicaSetClient` has a socket allocated to it
+ for the thread's lifetime, for each member of the set. For
+ :class:`~pymongo.read_preferences.ReadPreference` PRIMARY,
+ auto_start_request=True ensures consistent reads, even if you read
+ after an unacknowledged write. For read preferences other than
+ PRIMARY, there are no consistency guarantees. Default to ``False``.
+ - `use_greenlets`: If ``True``, use a background Greenlet instead of
+ a background thread to monitor state of replica set. Additionally,
+ :meth:`start_request()` assigns a greenlet-local, rather than
+ thread-local, socket.
+ `use_greenlets` with :class:`MongoReplicaSetClient` requires
+ `Gevent <http://gevent.org/>`_ to be installed.
+
+ | **Write Concern options:**
- `w`: (integer or string) 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.**
+ 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
@@ -337,13 +362,12 @@ def __init__(self, hosts_or_uri=None, max_pool_size=10,
- `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.
- - `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 servers using SSL.
+
+ | **Read preference options:**
+
- `read_preference`: The read preference for this client.
See :class:`~pymongo.read_preferences.ReadPreference` for available
+ options.
- `tag_sets`: Read from replica-set members with these tags.
To specify a priority-order for tag sets, provide a list of
tag sets: ``[{'dc': 'ny'}, {'dc': 'la'}, {}]``. A final, empty tag
@@ -354,24 +378,12 @@ def __init__(self, hosts_or_uri=None, max_pool_size=10,
- `secondary_acceptable_latency_ms`: (integer) Any replica-set member
whose ping time is within secondary_acceptable_latency_ms of the
nearest member may accept reads. Default 15 milliseconds.
- - `auto_start_request`: If ``True`, each thread that accesses
- this :class:`MongoReplicaSetClient` has a socket allocated to it
- for the thread's lifetime, for each member of the set. For
- :class:`~pymongo.read_preferences.ReadPreference` PRIMARY,
- auto_start_request=True ensures consistent reads, even if you read
- after an unacknowledged write. For read preferences other than PRIMARY,
- there are no consistency guarantees. Default to ``False``.
- - `use_greenlets`: If ``True``, use a background Greenlet instead of
- a background thread to monitor state of replica set. Additionally,
- :meth:`start_request()` assigns a greenlet-local, rather than
- thread-local, socket.
- `use_greenlets` with :class:`MongoReplicaSetClient` requires
- `Gevent <http://gevent.org/>`_ to be installed.
- - `host`: For compatibility with :class:`~mongo_client.MongoClient`.
- If both `host` and `hosts_or_uri` are specified `host` takes
- precedence.
- - `port`: For compatibility with :class:`~mongo_client.MongoClient`.
- The default port number to use for hosts.
+ **Ignored by mongos** and must be configured on the command line.
+ See the localThreshold_ option for more information.
+
+ | **SSL configuration:**
+
+ - `ssl`: If ``True``, create the connection to the servers 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``.
@@ -393,6 +405,8 @@ def __init__(self, hosts_or_uri=None, max_pool_size=10,
.. versionchanged:: 2.4.2+
Added addtional ssl options
.. versionadded:: 2.4
+
+ .. _localThreshold: http://docs.mongodb.org/manual/reference/mongos/#cmdoption-mongos--localThreshold
"""
self.__opts = {}
self.__seeds = set()
View
73 pymongo/replica_set_connection.py
@@ -93,7 +93,36 @@ def __init__(self, hosts_or_uri=None, max_pool_size=10,
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:**
+ | **Other optional parameters can be passed as keyword arguments:**
+
+ - `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.
+ - `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`` (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.read_preferences.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.
+ - `use_greenlets`: if ``True``, use a background Greenlet instead of
+ a background thread to monitor state of replica set. Additionally,
+ :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.
+
+ | **Write Concern options:**
- `safe`: :class:`ReplicaSetConnection` **disables** acknowledgement
of write operations. Use ``safe=True`` to enable write
@@ -113,11 +142,11 @@ def __init__(self, hosts_or_uri=None, max_pool_size=10,
- `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. Implies safe=True.
- - `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 servers using SSL.
+
+ | **Read preference options:**
+
+ - `slave_okay` or `slaveOk` (deprecated): Use `read_preference`
+ instead.
- `read_preference`: The read preference for this connection.
See :class:`~pymongo.read_preferences.ReadPreference` for available
- `tag_sets`: Read from replica-set members with these tags.
@@ -130,30 +159,12 @@ def __init__(self, hosts_or_uri=None, max_pool_size=10,
- `secondary_acceptable_latency_ms`: (integer) Any replica-set member
whose ping time is within secondary_acceptable_latency_ms of the
nearest member may accept reads. Default 15 milliseconds.
- - `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.read_preferences.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.
- - `use_greenlets`: if ``True``, use a background Greenlet instead of
- a background thread to monitor state of replica set. Additionally,
- :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.
+ **Ignored by mongos** and must be configured on the command line.
+ See the localThreshold_ option for more information.
+
+ | **SSL configuration:**
+
+ - `ssl`: If ``True``, create the connection to the servers 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``.
@@ -181,6 +192,8 @@ def __init__(self, hosts_or_uri=None, max_pool_size=10,
Added support for `host`, `port`, and `network_timeout` keyword
arguments for compatibility with connection.Connection.
.. versionadded:: 2.1
+
+ .. _localThreshold: http://docs.mongodb.org/manual/reference/mongos/#cmdoption-mongos--localThreshold
"""
network_timeout = kwargs.pop('network_timeout', None)
if network_timeout is not None:

0 comments on commit cf9dca6

Please sign in to comment.
Something went wrong with that request. Please try again.