mongodb/mongo-python-driver
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Documentation clarifications PYTHON-486 / PYTHON-487

Browse Source
This commit is contained in:
Ross Lawley 2013-03-07 10:50:01 +00:00
parent 1ba099a15b
commit cf9dca6970
9 changed files with 185 additions and 96 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
doc/api/pymongo/database.rst
View File

@ -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

6
doc/examples/high_availability.rst
View File

@ -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
'''''''''''''''''

3
pymongo/collection.py
View File

@ -676,6 +676,8 @@ class Collection(common.BaseObject):
- `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 @@ class Collection(common.BaseObject):
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

6
pymongo/common.py
View File

@ -435,6 +435,12 @@ class BaseObject(object):
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

60
pymongo/connection.py
View File

@ -95,7 +95,21 @@ class Connection(MongoClient):
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 @@ class Connection(MongoClient):
- `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``.

3
pymongo/database.py
View File

@ -328,6 +328,8 @@ class Database(common.BaseObject):
- `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 @@ class Database(common.BaseObject):
.. versionadded:: 1.4
.. mongodoc:: commands
.. _localThreshold: http://docs.mongodb.org/manual/reference/mongos/#cmdoption-mongos--localThreshold
"""
if isinstance(command, basestring):

58
pymongo/mongo_client.py
View File

@ -129,14 +129,28 @@ class MongoClient(common.BaseObject):
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 @@ class MongoClient(common.BaseObject):
- `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 @@ class MongoClient(common.BaseObject):
@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

66
pymongo/mongo_replica_set_client.py
View File

@ -320,14 +320,39 @@ class MongoReplicaSetClient(common.BaseObject):
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 @@ class MongoReplicaSetClient(common.BaseObject):
- `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 @@ class MongoReplicaSetClient(common.BaseObject):
- `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 @@ class MongoReplicaSetClient(common.BaseObject):
.. 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()

73
pymongo/replica_set_connection.py
View File

@ -93,7 +93,36 @@ class ReplicaSetConnection(MongoReplicaSetClient):
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 @@ class ReplicaSetConnection(MongoReplicaSetClient):
- `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 @@ class ReplicaSetConnection(MongoReplicaSetClient):
- `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 @@ class ReplicaSetConnection(MongoReplicaSetClient):
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: