Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Documentation clarifications PYTHON-486 / PYTHON-487

  • Loading branch information...
commit cf9dca69701a4a3ac9a45466da08922a342e097e 1 parent 1ba099a
Ross Lawley rozza authored
6 doc/api/pymongo/database.rst
Source Rendered
@@ -17,7 +17,11 @@
17 17 Get the `collection_name` :class:`~pymongo.collection.Collection` of
18 18 :class:`Database` `db`.
19 19
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`].
21 25
22 26 .. autoattribute:: read_preference
23 27 .. autoattribute:: tag_sets
6 doc/examples/high_availability.rst
Source Rendered
@@ -258,6 +258,12 @@ number. In that case, MongoReplicaSetClient distributes reads among matching
258 258 members within ``secondary_acceptable_latency_ms`` of the closest member's
259 259 ping time.
260 260
  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 +
261 267 Health Monitoring
262 268 '''''''''''''''''
263 269
3  pymongo/collection.py
@@ -676,6 +676,8 @@ def find(self, *args, **kwargs):
676 676 - `secondary_acceptable_latency_ms` (optional): Any replica-set
677 677 member whose ping time is within secondary_acceptable_latency_ms of
678 678 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.
679 681
680 682 .. note:: The `manipulate` parameter may default to False in
681 683 a future release.
@@ -703,6 +705,7 @@ def find(self, *args, **kwargs):
703 705 The `tailable` parameter.
704 706
705 707 .. mongodoc:: find
  708 + .. _localThreshold: http://docs.mongodb.org/manual/reference/mongos/#cmdoption-mongos--localThreshold
706 709 """
707 710 if not 'slave_okay' in kwargs:
708 711 kwargs['slave_okay'] = self.slave_okay
6 pymongo/common.py
@@ -435,6 +435,12 @@ def __get_acceptable_latency(self):
435 435 See :class:`~pymongo.read_preferences.ReadPreference`.
436 436
437 437 .. 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
438 444 """
439 445 return self.__secondary_acceptable_latency_ms
440 446
60 pymongo/connection.py
@@ -95,7 +95,21 @@ def __init__(self, host=None, port=None, max_pool_size=10,
95 95 in a document by this :class:`Connection` will be timezone
96 96 aware (otherwise they will be naive)
97 97
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:**
99 113
100 114 - `safe`: :class:`Connection` **disables** acknowledgement of write
101 115 operations. Use ``safe=True`` to enable write acknowledgement.
@@ -114,27 +128,33 @@ def __init__(self, host=None, port=None, max_pool_size=10,
114 128 - `fsync`: If ``True`` force the database to fsync all files before
115 129 returning. When used with `j` the server awaits the next group
116 130 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 +
136 136 - `slave_okay` or `slaveOk` (deprecated): Use `read_preference`
137 137 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.
138 158 - `ssl_keyfile`: The private keyfile used to identify the local
139 159 connection against mongod. If included with the ``certfile` then
140 160 only the ``ssl_certfile`` is needed. Implies ``ssl=True``.
3  pymongo/database.py
@@ -328,6 +328,8 @@ def command(self, command, value=1,
328 328 - `secondary_acceptable_latency_ms`: Any replica-set member whose
329 329 ping time is within secondary_acceptable_latency_ms of the nearest
330 330 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.
331 333 - `**kwargs` (optional): additional keyword arguments will
332 334 be added to the command document before it is sent
333 335
@@ -344,6 +346,7 @@ def command(self, command, value=1,
344 346 .. versionadded:: 1.4
345 347
346 348 .. mongodoc:: commands
  349 + .. _localThreshold: http://docs.mongodb.org/manual/reference/mongos/#cmdoption-mongos--localThreshold
347 350 """
348 351
349 352 if isinstance(command, basestring):
58 pymongo/mongo_client.py
@@ -129,14 +129,28 @@ def __init__(self, host=None, port=None, max_pool_size=10,
129 129 in a document by this :class:`MongoClient` will be timezone
130 130 aware (otherwise they will be naive)
131 131
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:**
133 147
134 148 - `w`: (integer or string) If this is a replica set, write operations
135 149 will block until they have been replicated to the specified number
136 150 or tagged set of servers. `w=<int>` always includes the replica set
137 151 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.
140 154 - `wtimeout`: (integer) Used in conjunction with `w`. Specify a value
141 155 in milliseconds to control how long to wait for write propagation
142 156 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,
146 160 - `fsync`: If ``True`` force the database to fsync all files before
147 161 returning. When used with `j` the server awaits the next group
148 162 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 +
149 168 - `replicaSet`: (string) The name of the replica set to connect to.
150 169 The driver will verify that the replica set it connects to matches
151 170 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 +
157 187 - `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()`
168 188 - `ssl_keyfile`: The private keyfile used to identify the local
169 189 connection against mongod. If included with the ``certfile` then
170 190 only the ``ssl_certfile`` is needed. Implies ``ssl=True``.
@@ -452,7 +472,7 @@ def port(self):
452 472
453 473 @property
454 474 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
456 476 primary, or the master of a master-slave set.
457 477
458 478 .. versionadded:: 2.3
66 pymongo/mongo_replica_set_client.py
@@ -320,14 +320,39 @@ def __init__(self, hosts_or_uri=None, max_pool_size=10,
320 320 this replica set. Can be passed as a keyword argument or as a
321 321 MongoDB URI option.
322 322
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:**
324 349
325 350 - `w`: (integer or string) Write operations will block until they have
326 351 been replicated to the specified number or tagged set of servers.
327 352 `w=<int>` always includes the replica set primary (e.g. w=3 means
328 353 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.
331 356 - `wtimeout`: (integer) Used in conjunction with `w`. Specify a value
332 357 in milliseconds to control how long to wait for write propagation
333 358 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,
337 362 - `fsync`: If ``True`` force the database to fsync all files before
338 363 returning. When used with `j` the server awaits the next group
339 364 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 +
345 368 - `read_preference`: The read preference for this client.
346 369 See :class:`~pymongo.read_preferences.ReadPreference` for available
  370 + options.
347 371 - `tag_sets`: Read from replica-set members with these tags.
348 372 To specify a priority-order for tag sets, provide a list of
349 373 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,
354 378 - `secondary_acceptable_latency_ms`: (integer) Any replica-set member
355 379 whose ping time is within secondary_acceptable_latency_ms of the
356 380 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.
375 387 - `ssl_keyfile`: The private keyfile used to identify the local
376 388 connection against mongod. If included with the ``certfile` then
377 389 only the ``ssl_certfile`` is needed. Implies ``ssl=True``.
@@ -393,6 +405,8 @@ def __init__(self, hosts_or_uri=None, max_pool_size=10,
393 405 .. versionchanged:: 2.4.2+
394 406 Added addtional ssl options
395 407 .. versionadded:: 2.4
  408 +
  409 + .. _localThreshold: http://docs.mongodb.org/manual/reference/mongos/#cmdoption-mongos--localThreshold
396 410 """
397 411 self.__opts = {}
398 412 self.__seeds = set()
73 pymongo/replica_set_connection.py
@@ -93,7 +93,36 @@ def __init__(self, hosts_or_uri=None, max_pool_size=10,
93 93 this replica set. Can be passed as a keyword argument or as a
94 94 MongoDB URI option.
95 95
96   - **Other optional parameters can be passed as keyword arguments:**
  96 + | **Other optional parameters can be passed as keyword arguments:**
  97 +
  98 + - `host`: For compatibility with connection.Connection. If both
  99 + `host` and `hosts_or_uri` are specified `host` takes precedence.
  100 + - `port`: For compatibility with connection.Connection. The default
  101 + port number to use for hosts.
  102 + - `network_timeout`: For compatibility with connection.Connection.
  103 + The timeout (in seconds) to use for socket operations - default
  104 + is no timeout. If both `network_timeout` and `socketTimeoutMS` are
  105 + are specified `network_timeout` takes precedence, matching
  106 + connection.Connection.
  107 + - `socketTimeoutMS`: (integer) How long (in milliseconds) a send or
  108 + receive on a socket can take before timing out.
  109 + - `connectTimeoutMS`: (integer) How long (in milliseconds) a
  110 + connection can take to be opened before timing out.
  111 + - `auto_start_request`: If ``True`` (the default), each thread that
  112 + accesses this :class:`ReplicaSetConnection` has a socket allocated
  113 + to it for the thread's lifetime, for each member of the set. For
  114 + :class:`~pymongo.read_preferences.ReadPreference` PRIMARY,
  115 + auto_start_request=True ensures consistent reads, even if you read
  116 + after an unsafe write. For read preferences other than PRIMARY,
  117 + there are no consistency guarantees.
  118 + - `use_greenlets`: if ``True``, use a background Greenlet instead of
  119 + a background thread to monitor state of replica set. Additionally,
  120 + :meth:`start_request()` will ensure that the current greenlet uses
  121 + the same socket for all operations until :meth:`end_request()`.
  122 + `use_greenlets` with ReplicaSetConnection requires `Gevent
  123 + <http://gevent.org/>`_ to be installed.
  124 +
  125 + | **Write Concern options:**
97 126
98 127 - `safe`: :class:`ReplicaSetConnection` **disables** acknowledgement
99 128 of write operations. Use ``safe=True`` to enable write
@@ -113,11 +142,11 @@ def __init__(self, hosts_or_uri=None, max_pool_size=10,
113 142 - `fsync`: If ``True`` force the database to fsync all files before
114 143 returning. When used with `j` the server awaits the next group
115 144 commit before returning. Implies safe=True.
116   - - `socketTimeoutMS`: (integer) How long (in milliseconds) a send or
117   - receive on a socket can take before timing out.
118   - - `connectTimeoutMS`: (integer) How long (in milliseconds) a
119   - connection can take to be opened before timing out.
120   - - `ssl`: If ``True``, create the connection to the servers using SSL.
  145 +
  146 + | **Read preference options:**
  147 +
  148 + - `slave_okay` or `slaveOk` (deprecated): Use `read_preference`
  149 + instead.
121 150 - `read_preference`: The read preference for this connection.
122 151 See :class:`~pymongo.read_preferences.ReadPreference` for available
123 152 - `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,
130 159 - `secondary_acceptable_latency_ms`: (integer) Any replica-set member
131 160 whose ping time is within secondary_acceptable_latency_ms of the
132 161 nearest member may accept reads. Default 15 milliseconds.
133   - - `auto_start_request`: If ``True`` (the default), each thread that
134   - accesses this :class:`ReplicaSetConnection` has a socket allocated
135   - to it for the thread's lifetime, for each member of the set. For
136   - :class:`~pymongo.read_preferences.ReadPreference` PRIMARY,
137   - auto_start_request=True ensures consistent reads, even if you read
138   - after an unsafe write. For read preferences other than PRIMARY,
139   - there are no consistency guarantees.
140   - - `use_greenlets`: if ``True``, use a background Greenlet instead of
141   - a background thread to monitor state of replica set. Additionally,
142   - :meth:`start_request()` will ensure that the current greenlet uses
143   - the same socket for all operations until :meth:`end_request()`.
144   - `use_greenlets` with ReplicaSetConnection requires `Gevent
145   - <http://gevent.org/>`_ to be installed.
146   - - `slave_okay` or `slaveOk` (deprecated): Use `read_preference`
147   - instead.
148   - - `host`: For compatibility with connection.Connection. If both
149   - `host` and `hosts_or_uri` are specified `host` takes precedence.
150   - - `port`: For compatibility with connection.Connection. The default
151   - port number to use for hosts.
152   - - `network_timeout`: For compatibility with connection.Connection.
153   - The timeout (in seconds) to use for socket operations - default
154   - is no timeout. If both `network_timeout` and `socketTimeoutMS` are
155   - are specified `network_timeout` takes precedence, matching
156   - connection.Connection.
  162 + **Ignored by mongos** and must be configured on the command line.
  163 + See the localThreshold_ option for more information.
  164 +
  165 + | **SSL configuration:**
  166 +
  167 + - `ssl`: If ``True``, create the connection to the servers using SSL.
157 168 - `ssl_keyfile`: The private keyfile used to identify the local
158 169 connection against mongod. If included with the ``certfile` then
159 170 only the ``ssl_certfile`` is needed. Implies ``ssl=True``.
@@ -181,6 +192,8 @@ def __init__(self, hosts_or_uri=None, max_pool_size=10,
181 192 Added support for `host`, `port`, and `network_timeout` keyword
182 193 arguments for compatibility with connection.Connection.
183 194 .. versionadded:: 2.1
  195 +
  196 + .. _localThreshold: http://docs.mongodb.org/manual/reference/mongos/#cmdoption-mongos--localThreshold
184 197 """
185 198 network_timeout = kwargs.pop('network_timeout', None)
186 199 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.