Skip to content

Commit cf9dca6

Browse files
rozzarozza
committed
Documentation clarifications PYTHON-486 / PYTHON-487
1 parent 1ba099a commit cf9dca6

File tree

9 files changed

+185
-96
lines changed

9 files changed

+185
-96
lines changed

‎doc/api/pymongo/database.rst‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,11 @@
1717
Get the `collection_name` :class:`~pymongo.collection.Collection` of
1818
:class:`Database` `db`.
1919

20-
Raises :class:`~pymongo.errors.InvalidName` if an invalid collection name is used.
20+
Raises :class:`~pymongo.errors.InvalidName` if an invalid collection
21+
name is used.
22+
23+
.. note:: Use dictionary style access if `collection_name` is an
24+
attribute of the :class:`Database` class eg: db[`collection_name`].
2125

2226
.. autoattribute:: read_preference
2327
.. autoattribute:: tag_sets

‎doc/examples/high_availability.rst‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -258,6 +258,12 @@ number. In that case, MongoReplicaSetClient distributes reads among matching
258258
members within ``secondary_acceptable_latency_ms`` of the closest member's
259259
ping time.
260260

261+
.. note:: ``secondary_acceptable_latency_ms`` is ignored when talking to a
262+
replica set *through* a mongos. The equivalent is the localThreshold_ command
263+
line option.
264+
265+
.. _localThreshold: http://docs.mongodb.org/manual/reference/mongos/#cmdoption-mongos--localThreshold
266+
261267
Health Monitoring
262268
'''''''''''''''''
263269

‎pymongo/collection.py‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -676,6 +676,8 @@ def find(self, *args, **kwargs):
676676
- `secondary_acceptable_latency_ms` (optional): Any replica-set
677677
member whose ping time is within secondary_acceptable_latency_ms of
678678
the nearest member may accept reads. Default 15 milliseconds.
679+
**Ignored by mongos** and must be configured on the command line.
680+
See the localThreshold_ option for more information.
679681
680682
.. note:: The `manipulate` parameter may default to False in
681683
a future release.
@@ -703,6 +705,7 @@ def find(self, *args, **kwargs):
703705
The `tailable` parameter.
704706
705707
.. mongodoc:: find
708+
.. _localThreshold: http://docs.mongodb.org/manual/reference/mongos/#cmdoption-mongos--localThreshold
706709
"""
707710
if not 'slave_okay' in kwargs:
708711
kwargs['slave_okay'] = self.slave_okay

‎pymongo/common.py‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -435,6 +435,12 @@ def __get_acceptable_latency(self):
435435
See :class:`~pymongo.read_preferences.ReadPreference`.
436436
437437
.. versionadded:: 2.3
438+
439+
.. note:: ``secondary_acceptable_latency_ms`` is ignored when talking to a
440+
replica set *through* a mongos. The equivalent is the localThreshold_ command
441+
line option.
442+
443+
.. _localThreshold: http://docs.mongodb.org/manual/reference/mongos/#cmdoption-mongos--localThreshold
438444
"""
439445
return self.__secondary_acceptable_latency_ms
440446

‎pymongo/connection.py‎

Lines changed: 40 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -95,7 +95,21 @@ def __init__(self, host=None, port=None, max_pool_size=10,
9595
in a document by this :class:`Connection` will be timezone
9696
aware (otherwise they will be naive)
9797
98-
**Other optional parameters can be passed as keyword arguments:**
98+
| **Other optional parameters can be passed as keyword arguments:**
99+
100+
- `socketTimeoutMS`: (integer) How long (in milliseconds) a send or
101+
receive on a socket can take before timing out.
102+
- `connectTimeoutMS`: (integer) How long (in milliseconds) a
103+
connection can take to be opened before timing out.
104+
- `auto_start_request`: If ``True`` (the default), each thread that
105+
accesses this Connection has a socket allocated to it for the
106+
thread's lifetime. This ensures consistent reads, even if you read
107+
after an unsafe write.
108+
- `use_greenlets`: if ``True``, :meth:`start_request()` will ensure
109+
that the current greenlet uses the same socket for all operations
110+
until :meth:`end_request()`
111+
112+
| **Write Concern options:**
99113
100114
- `safe`: :class:`Connection` **disables** acknowledgement of write
101115
operations. Use ``safe=True`` to enable write acknowledgement.
@@ -114,27 +128,33 @@ def __init__(self, host=None, port=None, max_pool_size=10,
114128
- `fsync`: If ``True`` force the database to fsync all files before
115129
returning. When used with `j` the server awaits the next group
116130
commit before returning. Implies safe=True.
117-
- `replicaSet`: (string) The name of the replica set to connect to.
118-
The driver will verify that the replica set it connects to matches
119-
this name. Implies that the hosts specified are a seed list and the
120-
driver should attempt to find all members of the set.
121-
- `socketTimeoutMS`: (integer) How long (in milliseconds) a send or
122-
receive on a socket can take before timing out.
123-
- `connectTimeoutMS`: (integer) How long (in milliseconds) a
124-
connection can take to be opened before timing out.
125-
- `ssl`: If ``True``, create the connection to the server using SSL.
126-
- `read_preference`: The read preference for this connection.
127-
See :class:`~pymongo.read_preferences.ReadPreference` for available
128-
options.
129-
- `auto_start_request`: If ``True`` (the default), each thread that
130-
accesses this Connection has a socket allocated to it for the
131-
thread's lifetime. This ensures consistent reads, even if you read
132-
after an unsafe write.
133-
- `use_greenlets`: if ``True``, :meth:`start_request()` will ensure
134-
that the current greenlet uses the same socket for all operations
135-
until :meth:`end_request()`
131+
132+
| **Replica-set keyword arguments for connecting with a replica-set
133+
- either directly or via a mongos:**
134+
| (ignored by standalone mongod instances)
135+
136136
- `slave_okay` or `slaveOk` (deprecated): Use `read_preference`
137137
instead.
138+
- `replicaSet`: (string) The name of the replica-set to connect to.
139+
The driver will verify that the replica-set it connects to matches
140+
this name. Implies that the hosts specified are a seed list and the
141+
driver should attempt to find all members of the set. *Ignored by
142+
mongos*.
143+
- `read_preference`: The read preference for this client. If
144+
connecting to a secondary then a read preference mode *other* than
145+
PRIMARY is required - otherwise all queries will throw a
146+
:class:`~pymongo.errors.AutoReconnect` "not master" error.
147+
See :class:`~pymongo.read_preferences.ReadPreference` for all
148+
available read preference options.
149+
- `tag_sets`: Ignored unless connecting to a replica-set via mongos.
150+
Specify a priority-order for tag sets, provide a list of
151+
tag sets: ``[{'dc': 'ny'}, {'dc': 'la'}, {}]``. A final, empty tag
152+
set, ``{}``, means "read from any member that matches the mode,
153+
ignoring tags.
154+
155+
| **SSL configuration:**
156+
157+
- `ssl`: If ``True``, create the connection to the server using SSL.
138158
- `ssl_keyfile`: The private keyfile used to identify the local
139159
connection against mongod. If included with the ``certfile` then
140160
only the ``ssl_certfile`` is needed. Implies ``ssl=True``.

‎pymongo/database.py‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -328,6 +328,8 @@ def command(self, command, value=1,
328328
- `secondary_acceptable_latency_ms`: Any replica-set member whose
329329
ping time is within secondary_acceptable_latency_ms of the nearest
330330
member may accept reads. Default 15 milliseconds.
331+
**Ignored by mongos** and must be configured on the command line.
332+
See the localThreshold_ option for more information.
331333
- `**kwargs` (optional): additional keyword arguments will
332334
be added to the command document before it is sent
333335
@@ -344,6 +346,7 @@ def command(self, command, value=1,
344346
.. versionadded:: 1.4
345347
346348
.. mongodoc:: commands
349+
.. _localThreshold: http://docs.mongodb.org/manual/reference/mongos/#cmdoption-mongos--localThreshold
347350
"""
348351

349352
if isinstance(command, basestring):

‎pymongo/mongo_client.py‎

Lines changed: 39 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -129,14 +129,28 @@ def __init__(self, host=None, port=None, max_pool_size=10,
129129
in a document by this :class:`MongoClient` will be timezone
130130
aware (otherwise they will be naive)
131131
132-
**Other optional parameters can be passed as keyword arguments:**
132+
| **Other optional parameters can be passed as keyword arguments:**
133+
134+
- `socketTimeoutMS`: (integer) How long (in milliseconds) a send or
135+
receive on a socket can take before timing out.
136+
- `connectTimeoutMS`: (integer) How long (in milliseconds) a
137+
connection can take to be opened before timing out.
138+
- `auto_start_request`: If ``True``, each thread that accesses
139+
this :class:`MongoClient` has a socket allocated to it for the
140+
thread's lifetime. This ensures consistent reads, even if you
141+
read after an unacknowledged write. Defaults to ``False``
142+
- `use_greenlets`: If ``True``, :meth:`start_request()` will ensure
143+
that the current greenlet uses the same socket for all
144+
operations until :meth:`end_request()`
145+
146+
| **Write Concern options:**
133147
134148
- `w`: (integer or string) If this is a replica set, write operations
135149
will block until they have been replicated to the specified number
136150
or tagged set of servers. `w=<int>` always includes the replica set
137151
primary (e.g. w=3 means write to the primary and wait until
138-
replicated to **two** secondaries). **Passing w=0 disables write
139-
acknowledgement and all other write concern options.**
152+
replicated to **two** secondaries). Passing w=0 **disables write
153+
acknowledgement** and all other write concern options.
140154
- `wtimeout`: (integer) Used in conjunction with `w`. Specify a value
141155
in milliseconds to control how long to wait for write propagation
142156
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,
146160
- `fsync`: If ``True`` force the database to fsync all files before
147161
returning. When used with `j` the server awaits the next group
148162
commit before returning.
163+
164+
| **Replica set keyword arguments for connecting with a replica set
165+
- either directly or via a mongos:**
166+
| (ignored by standalone mongod instances)
167+
149168
- `replicaSet`: (string) The name of the replica set to connect to.
150169
The driver will verify that the replica set it connects to matches
151170
this name. Implies that the hosts specified are a seed list and the
152-
driver should attempt to find all members of the set.
153-
- `socketTimeoutMS`: (integer) How long (in milliseconds) a send or
154-
receive on a socket can take before timing out.
155-
- `connectTimeoutMS`: (integer) How long (in milliseconds) a
156-
connection can take to be opened before timing out.
171+
driver should attempt to find all members of the set. *Ignored by
172+
mongos*.
173+
- `read_preference`: The read preference for this client. If
174+
connecting to a secondary then a read preference mode *other* than
175+
PRIMARY is required - otherwise all queries will throw
176+
:class:`~pymongo.errors.AutoReconnect` "not master".
177+
See :class:`~pymongo.read_preferences.ReadPreference` for all
178+
available read preference options.
179+
- `tag_sets`: Ignored unless connecting to a replica set via mongos.
180+
Specify a priority-order for tag sets, provide a list of
181+
tag sets: ``[{'dc': 'ny'}, {'dc': 'la'}, {}]``. A final, empty tag
182+
set, ``{}``, means "read from any member that matches the mode,
183+
ignoring tags.
184+
185+
| **SSL configuration:**
186+
157187
- `ssl`: If ``True``, create the connection to the server using SSL.
158-
- `read_preference`: The read preference for this client.
159-
See :class:`~pymongo.read_preferences.ReadPreference` for available
160-
options.
161-
- `auto_start_request`: If ``True``, each thread that accesses
162-
this :class:`MongoClient` has a socket allocated to it for the
163-
thread's lifetime. This ensures consistent reads, even if you
164-
read after an unacknowledged write. Defaults to ``False``
165-
- `use_greenlets`: If ``True``, :meth:`start_request()` will ensure
166-
that the current greenlet uses the same socket for all
167-
operations until :meth:`end_request()`
168188
- `ssl_keyfile`: The private keyfile used to identify the local
169189
connection against mongod. If included with the ``certfile` then
170190
only the ``ssl_certfile`` is needed. Implies ``ssl=True``.
@@ -452,7 +472,7 @@ def port(self):
452472

453473
@property
454474
def is_primary(self):
455-
"""If this instance is connected to a standalone, a replica-set
475+
"""If this instance is connected to a standalone, a replica set
456476
primary, or the master of a master-slave set.
457477
458478
.. versionadded:: 2.3

‎pymongo/mongo_replica_set_client.py‎

Lines changed: 40 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -320,14 +320,39 @@ def __init__(self, hosts_or_uri=None, max_pool_size=10,
320320
this replica set. Can be passed as a keyword argument or as a
321321
MongoDB URI option.
322322
323-
**Other optional parameters can be passed as keyword arguments:**
323+
| **Other optional parameters can be passed as keyword arguments:**
324+
325+
- `host`: For compatibility with :class:`~mongo_client.MongoClient`.
326+
If both `host` and `hosts_or_uri` are specified `host` takes
327+
precedence.
328+
- `port`: For compatibility with :class:`~mongo_client.MongoClient`.
329+
The default port number to use for hosts.
330+
- `socketTimeoutMS`: (integer) How long (in milliseconds) a send or
331+
receive on a socket can take before timing out.
332+
- `connectTimeoutMS`: (integer) How long (in milliseconds) a
333+
connection can take to be opened before timing out.
334+
- `auto_start_request`: If ``True``, each thread that accesses
335+
this :class:`MongoReplicaSetClient` has a socket allocated to it
336+
for the thread's lifetime, for each member of the set. For
337+
:class:`~pymongo.read_preferences.ReadPreference` PRIMARY,
338+
auto_start_request=True ensures consistent reads, even if you read
339+
after an unacknowledged write. For read preferences other than
340+
PRIMARY, there are no consistency guarantees. Default to ``False``.
341+
- `use_greenlets`: If ``True``, use a background Greenlet instead of
342+
a background thread to monitor state of replica set. Additionally,
343+
:meth:`start_request()` assigns a greenlet-local, rather than
344+
thread-local, socket.
345+
`use_greenlets` with :class:`MongoReplicaSetClient` requires
346+
`Gevent <http://gevent.org/>`_ to be installed.
347+
348+
| **Write Concern options:**
324349
325350
- `w`: (integer or string) Write operations will block until they have
326351
been replicated to the specified number or tagged set of servers.
327352
`w=<int>` always includes the replica set primary (e.g. w=3 means
328353
write to the primary and wait until replicated to **two**
329-
secondaries). **Passing w=0 disables write acknowledgement and all
330-
other write concern options.**
354+
secondaries). Passing w=0 **disables write acknowledgement** and all
355+
other write concern options.
331356
- `wtimeout`: (integer) Used in conjunction with `w`. Specify a value
332357
in milliseconds to control how long to wait for write propagation
333358
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,
337362
- `fsync`: If ``True`` force the database to fsync all files before
338363
returning. When used with `j` the server awaits the next group
339364
commit before returning.
340-
- `socketTimeoutMS`: (integer) How long (in milliseconds) a send or
341-
receive on a socket can take before timing out.
342-
- `connectTimeoutMS`: (integer) How long (in milliseconds) a
343-
connection can take to be opened before timing out.
344-
- `ssl`: If ``True``, create the connection to the servers using SSL.
365+
366+
| **Read preference options:**
367+
345368
- `read_preference`: The read preference for this client.
346369
See :class:`~pymongo.read_preferences.ReadPreference` for available
370+
options.
347371
- `tag_sets`: Read from replica-set members with these tags.
348372
To specify a priority-order for tag sets, provide a list of
349373
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,
354378
- `secondary_acceptable_latency_ms`: (integer) Any replica-set member
355379
whose ping time is within secondary_acceptable_latency_ms of the
356380
nearest member may accept reads. Default 15 milliseconds.
357-
- `auto_start_request`: If ``True`, each thread that accesses
358-
this :class:`MongoReplicaSetClient` has a socket allocated to it
359-
for the thread's lifetime, for each member of the set. For
360-
:class:`~pymongo.read_preferences.ReadPreference` PRIMARY,
361-
auto_start_request=True ensures consistent reads, even if you read
362-
after an unacknowledged write. For read preferences other than PRIMARY,
363-
there are no consistency guarantees. Default to ``False``.
364-
- `use_greenlets`: If ``True``, use a background Greenlet instead of
365-
a background thread to monitor state of replica set. Additionally,
366-
:meth:`start_request()` assigns a greenlet-local, rather than
367-
thread-local, socket.
368-
`use_greenlets` with :class:`MongoReplicaSetClient` requires
369-
`Gevent <http://gevent.org/>`_ to be installed.
370-
- `host`: For compatibility with :class:`~mongo_client.MongoClient`.
371-
If both `host` and `hosts_or_uri` are specified `host` takes
372-
precedence.
373-
- `port`: For compatibility with :class:`~mongo_client.MongoClient`.
374-
The default port number to use for hosts.
381+
**Ignored by mongos** and must be configured on the command line.
382+
See the localThreshold_ option for more information.
383+
384+
| **SSL configuration:**
385+
386+
- `ssl`: If ``True``, create the connection to the servers using SSL.
375387
- `ssl_keyfile`: The private keyfile used to identify the local
376388
connection against mongod. If included with the ``certfile` then
377389
only the ``ssl_certfile`` is needed. Implies ``ssl=True``.
@@ -393,6 +405,8 @@ def __init__(self, hosts_or_uri=None, max_pool_size=10,
393405
.. versionchanged:: 2.4.2+
394406
Added addtional ssl options
395407
.. versionadded:: 2.4
408+
409+
.. _localThreshold: http://docs.mongodb.org/manual/reference/mongos/#cmdoption-mongos--localThreshold
396410
"""
397411
self.__opts = {}
398412
self.__seeds = set()

0 commit comments

Comments
 (0)