Skip to content

Commit f6a260c

Browse files
behackettbehackett
committed
PYTHON-805 - Add with_options and remove per helper read_preference
This change removes the read_preference parameter from various command helpers on the Collection object. Those options were never shipped in a PyMongo release. It also documents which helpers obey Collection.read_preference. The bigger change is the removal of the read_preference, tag_sets, and secondary_acceptable_latency_ms params from find() and find_one() - a major backward breaking change. Collection.with_options is intended to replace their use. coll.find(read_preference=ReadPreference.SECONDARY) changes to coll.with_options(read_preference=ReadPreference.SECONDARY).find()
1 parent f0daebf commit f6a260c

File tree

7 files changed

+102
-102
lines changed

7 files changed

+102
-102
lines changed

‎doc/api/pymongo/collection.rst‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,14 +28,15 @@
2828
.. autoattribute:: read_preference
2929
.. autoattribute:: write_concern
3030
.. autoattribute:: uuid_subtype
31+
.. automethod:: with_options
3132
.. automethod:: insert(doc_or_docs[, manipulate=True[, check_keys=True[, continue_on_error=False[, **kwargs]]]])
3233
.. automethod:: save(to_save[, manipulate=True[, check_keys=True[, **kwargs]]])
3334
.. automethod:: update(spec, document[, upsert=False[, manipulate=False[, multi=False[, check_keys=True[, **kwargs]]]]])
3435
.. automethod:: remove([spec_or_id=None[, multi=True[, **kwargs]]])
3536
.. automethod:: initialize_unordered_bulk_op
3637
.. automethod:: initialize_ordered_bulk_op
3738
.. automethod:: drop
38-
.. automethod:: find([spec=None[, fields=None[, skip=0[, limit=0[, timeout=True[, snapshot=False[, tailable=False[, sort=None[, max_scan=None[, as_class=None[, await_data=False[, partial=False[, manipulate=True[, read_preference=None[, exhaust=False]]]]]]]]]]]]]]])
39+
.. automethod:: find([spec=None[, fields=None[, skip=0[, limit=0[, timeout=True[, snapshot=False[, tailable=False[, sort=None[, max_scan=None[, as_class=None[, await_data=False[, partial=False[, manipulate=True[, exhaust=False]]]]]]]]]]]]]]])
3940
.. automethod:: find_one([spec_or_id=None[, *args[, **kwargs]]])
4041
.. automethod:: parallel_scan
4142
.. automethod:: count

‎gridfs/__init__.py‎

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -318,16 +318,15 @@ def find(self, *args, **kwargs):
318318
:meth:`~pymongo.cursor.Cursor.sort` for details.
319319
- `max_scan` (optional): limit the number of file documents
320320
examined when performing the query
321-
- `read_preference` (optional): The read preference for
322-
this query.
323-
- `tag_sets` **DEPRECATED**
324-
- `secondary_acceptable_latency_ms` **DEPRECATED**
325321
326322
Raises :class:`TypeError` if any of the arguments are of
327323
improper type. Returns an instance of
328324
:class:`~gridfs.grid_file.GridOutCursor`
329325
corresponding to this query.
330326
327+
.. versionchanged:: 3.0
328+
Removed the read_preference, tag_sets, and
329+
secondary_acceptable_latency_ms options.
331330
.. versionadded:: 2.7
332331
.. mongodoc:: find
333332
"""

‎gridfs/grid_file.py‎

Lines changed: 2 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -603,9 +603,7 @@ class GridOutCursor(Cursor):
603603
of an arbitrary query against the GridFS files collection.
604604
"""
605605
def __init__(self, collection, spec=None, skip=0, limit=0,
606-
timeout=True, sort=None, max_scan=None,
607-
read_preference=None, tag_sets=None,
608-
secondary_acceptable_latency_ms=None):
606+
timeout=True, sort=None, max_scan=None):
609607
"""Create a new cursor, similar to the normal
610608
:class:`~pymongo.cursor.Cursor`.
611609
@@ -619,14 +617,9 @@ def __init__(self, collection, spec=None, skip=0, limit=0,
619617
# Hold on to the base "fs" collection to create GridOut objects later.
620618
self.__root_collection = collection
621619

622-
# Copy these settings from collection if they are not set by caller.
623-
read_preference = read_preference or collection.files.read_preference
624-
625620
super(GridOutCursor, self).__init__(
626621
collection.files, spec, skip=skip, limit=limit, timeout=timeout,
627-
sort=sort, max_scan=max_scan, read_preference=read_preference,
628-
secondary_acceptable_latency_ms=secondary_acceptable_latency_ms,
629-
tag_sets=tag_sets)
622+
sort=sort, max_scan=max_scan)
630623

631624
def next(self):
632625
"""Get next GridOut object from cursor.

‎pymongo/collection.py‎

Lines changed: 70 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -222,6 +222,30 @@ def database(self):
222222
"""
223223
return self.__database
224224

225+
def with_options(
226+
self, codec_options=None, read_preference=None, write_concern=None):
227+
"""Get a clone of this collection changing the specified settings.
228+
229+
:Parameters:
230+
- `codec_options` (optional): An instance of
231+
:class:`~pymongo.codec_options.CodecOptions`. If ``None`` (the
232+
default) the :attr:`codec_options` of this :class:`Collection`
233+
is used.
234+
- `read_preference` (optional): The read preference to use. If
235+
``None`` (the default) the :attr:`read_preference` of this
236+
:class:`Collection` is used.
237+
- `write_concern` (optional): An instance of
238+
:class:`~pymongo.write_concern.WriteConcern`. If ``None`` (the
239+
default) the :attr:`write_concern` of this :class:`Collection`
240+
is used.
241+
"""
242+
return Collection(self.__database,
243+
self.__name,
244+
False,
245+
codec_options or self.codec_options,
246+
read_preference or self.read_preference,
247+
write_concern or self.write_concern)
248+
225249
def initialize_unordered_bulk_op(self):
226250
"""Initialize an unordered batch of write operations.
227251
@@ -711,6 +735,9 @@ def find_one(self, spec_or_id=None, *args, **kwargs):
711735
ignored. Returns a single document, or ``None`` if no matching
712736
document is found.
713737
738+
The :meth:`find_one` method obeys the :attr:`read_preference` of
739+
this :class:`Collection`.
740+
714741
:Parameters:
715742
716743
- `spec_or_id` (optional): a dictionary specifying
@@ -759,6 +786,9 @@ def find(self, *args, **kwargs):
759786
improper type. Returns an instance of
760787
:class:`~pymongo.cursor.Cursor` corresponding to this query.
761788
789+
The :meth:`find` method obeys the :attr:`read_preference` of
790+
this :class:`Collection`.
791+
762792
:Parameters:
763793
- `spec` (optional): a SON object specifying elements which
764794
must be present for a document to be included in the
@@ -806,10 +836,6 @@ def find(self, *args, **kwargs):
806836
results if some shards are down instead of returning an error.
807837
- `manipulate`: (optional): If True (the default), apply any
808838
outgoing SON manipulators before returning.
809-
- `read_preference` (optional): The read preference for
810-
this query.
811-
- `tag_sets` **DEPRECATED**
812-
- `secondary_acceptable_latency_ms` **DEPRECATED**
813839
- `exhaust` (optional): If ``True`` create an "exhaust" cursor.
814840
MongoDB will stream batched results to the client without waiting
815841
for the client to request each batch, reducing latency.
@@ -834,8 +860,7 @@ def find(self, *args, **kwargs):
834860
release.
835861
836862
.. versionchanged:: 3.0
837-
Removed the `network_timeout` parameter.
838-
Deprecated the `tag_sets`, and
863+
Removed the `network_timeout`, `read_preference`, `tag_sets`, and
839864
`secondary_acceptable_latency_ms` parameters.
840865
Removed `compile_re` option: PyMongo now always represents BSON
841866
regular expressions as :class:`~bson.regex.Regex` objects. Use
@@ -858,7 +883,7 @@ def find(self, *args, **kwargs):
858883
"""
859884
return Cursor(self, *args, **kwargs)
860885

861-
def parallel_scan(self, num_cursors, read_preference=None, **kwargs):
886+
def parallel_scan(self, num_cursors):
862887
"""Scan this entire collection in parallel.
863888
864889
Returns a list of up to ``num_cursors`` cursors that can be iterated
@@ -888,24 +913,23 @@ def process_cursor(cursor):
888913
889914
# All documents have now been processed.
890915
891-
With :class:`~pymongo.mongo_replica_set_client.MongoReplicaSetClient`,
892-
if the `read_preference` attribute of this instance is not set to
893-
:attr:`pymongo.read_preferences.ReadPreference.PRIMARY` or
894-
:attr:`pymongo.read_preferences.ReadPreference.PRIMARY_PREFERRED`
895-
the command will be sent to a secondary.
916+
The :meth:`parallel_scan` method obeys the :attr:`read_preference` of
917+
this :class:`Collection`.
896918
897919
:Parameters:
898920
- `num_cursors`: the number of cursors to return
899-
- `read_preference`: the read preference to use for this scan
900921
901922
.. note:: Requires server version **>= 2.5.5**.
902923
924+
.. versionchanged:: 3.0
925+
Removed support for arbitrary keyword arguments, since
926+
the parallelCollectionScan command has no optional arguments.
927+
903928
"""
904929
cmd = SON([('parallelCollectionScan', self.__name),
905930
('numCursors', num_cursors)])
906-
cmd.update(kwargs)
907931

908-
result, address = self._command(cmd, read_preference)
932+
result, address = self._command(cmd)
909933

910934
return [CommandCursor(self,
911935
cursor['cursor'],
@@ -916,6 +940,9 @@ def count(self):
916940
917941
To get the number of documents matching a specific query use
918942
:meth:`pymongo.cursor.Cursor.count`.
943+
944+
The :meth:`count` method obeys the :attr:`read_preference` of
945+
this :class:`Collection`.
919946
"""
920947
return self.find().count()
921948

@@ -1266,20 +1293,17 @@ def options(self):
12661293

12671294
return options
12681295

1269-
def aggregate(self, pipeline, read_preference=None, **kwargs):
1296+
def aggregate(self, pipeline, **kwargs):
12701297
"""Perform an aggregation using the aggregation framework on this
12711298
collection.
12721299
1273-
With :class:`~pymongo.mongo_replica_set_client.MongoReplicaSetClient`,
1274-
if the `read_preference` attribute of this instance is not set to
1275-
:attr:`pymongo.read_preferences.ReadPreference.PRIMARY` or
1276-
:attr:`pymongo.read_preferences.ReadPreference.PRIMARY_PREFERRED`
1277-
the command will be sent to a secondary.
1300+
The :meth:`aggregate` method obeys the :attr:`read_preference` of this
1301+
:class:`Collection`.
12781302
12791303
:Parameters:
12801304
- `pipeline`: a single command or list of aggregation commands
1281-
- `read_preference`: read preference to use for this aggregate
1282-
- `**kwargs`: send arbitrary parameters to the aggregate command
1305+
- `**kwargs` (optional): additional arguments to the aggregate
1306+
command may be passed as keyword arguments to this helper method
12831307
12841308
.. note:: Requires server version **>= 2.1.0**.
12851309
@@ -1314,6 +1338,7 @@ def aggregate(self, pipeline, read_preference=None, **kwargs):
13141338
cmd.update(kwargs)
13151339

13161340
# XXX: Keep doing this automatically?
1341+
read_preference = self.read_preference
13171342
for stage in pipeline:
13181343
if '$out' in stage:
13191344
read_preference = ReadPreference.PRIMARY
@@ -1331,8 +1356,7 @@ def aggregate(self, pipeline, read_preference=None, **kwargs):
13311356

13321357
# TODO key and condition ought to be optional, but deprecation
13331358
# could be painful as argument order would have to change.
1334-
def group(self, key, condition, initial,
1335-
reduce, finalize=None, read_preference=None, **kwargs):
1359+
def group(self, key, condition, initial, reduce, finalize=None, **kwargs):
13361360
"""Perform a query similar to an SQL *group by* operation.
13371361
13381362
Returns an array of grouped items.
@@ -1347,11 +1371,8 @@ def group(self, key, condition, initial,
13471371
function to be applied to each document, returning the key
13481372
to group by.
13491373
1350-
With :class:`~pymongo.mongo_replica_set_client.MongoReplicaSetClient`,
1351-
if the `read_preference` attribute of this instance is not set to
1352-
:attr:`pymongo.read_preferences.ReadPreference.PRIMARY` or
1353-
:attr:`pymongo.read_preferences.ReadPreference.PRIMARY_PREFERRED`
1354-
the command will be sent to a secondary.
1374+
The :meth:`group` method obeys the :attr:`read_preference` of this
1375+
:class:`Collection`.
13551376
13561377
:Parameters:
13571378
- `key`: fields to group by (see above description)
@@ -1360,7 +1381,8 @@ def group(self, key, condition, initial,
13601381
- `initial`: initial value of the aggregation counter object
13611382
- `reduce`: aggregation function as a JavaScript string
13621383
- `finalize`: function to be called on each object in output list.
1363-
- `read_preference`: read preference to use for this group
1384+
- `**kwargs` (optional): additional arguments to the group command
1385+
may be passed as keyword arguments to this helper method
13641386
13651387
.. versionchanged:: 2.2
13661388
Removed deprecated argument: command
@@ -1380,7 +1402,7 @@ def group(self, key, condition, initial,
13801402
cmd = SON([("group", group)])
13811403
cmd.update(kwargs)
13821404

1383-
return self._command(cmd, read_preference)[0]["retval"]
1405+
return self._command(cmd)[0]["retval"]
13841406

13851407
def rename(self, new_name, **kwargs):
13861408
"""Rename this collection.
@@ -1393,8 +1415,8 @@ def rename(self, new_name, **kwargs):
13931415
13941416
:Parameters:
13951417
- `new_name`: new name for this collection
1396-
- `**kwargs` (optional): any additional rename options
1397-
should be passed as keyword arguments
1418+
- `**kwargs` (optional): additional arguments to the rename command
1419+
may be passed as keyword arguments to this helper method
13981420
(i.e. ``dropTarget=True``)
13991421
"""
14001422
if not isinstance(new_name, string_type):
@@ -1424,20 +1446,25 @@ def distinct(self, key):
14241446
To get the distinct values for a key in the result set of a
14251447
query use :meth:`~pymongo.cursor.Cursor.distinct`.
14261448
1449+
The :meth:`distinct` method obeys the :attr:`read_preference` of
1450+
this :class:`Collection`.
1451+
14271452
:Parameters:
14281453
- `key`: name of key for which we want to get the distinct values
14291454
"""
14301455
return self.find().distinct(key)
14311456

1432-
def map_reduce(self, map, reduce, out,
1433-
full_response=False, read_preference=None, **kwargs):
1457+
def map_reduce(self, map, reduce, out, full_response=False, **kwargs):
14341458
"""Perform a map/reduce operation on this collection.
14351459
14361460
If `full_response` is ``False`` (default) returns a
14371461
:class:`~pymongo.collection.Collection` instance containing
14381462
the results of the operation. Otherwise, returns the full
14391463
response from the server to the `map reduce command`_.
14401464
1465+
The :meth:`map_reduce` method obeys the :attr:`read_preference` of this
1466+
:class:`Collection`.
1467+
14411468
:Parameters:
14421469
- `map`: map function (as a JavaScript string)
14431470
- `reduce`: reduce function (as a JavaScript string)
@@ -1448,7 +1475,6 @@ def map_reduce(self, map, reduce, out,
14481475
e.g. SON([('replace', <collection name>), ('db', <database name>)])
14491476
- `full_response` (optional): if ``True``, return full response to
14501477
this command - otherwise just return the result collection
1451-
- `read_preference`: read preference to use for this map reduce
14521478
- `**kwargs` (optional): additional arguments to the
14531479
`map reduce command`_ may be passed as keyword arguments to this
14541480
helper method, e.g.::
@@ -1475,6 +1501,7 @@ def map_reduce(self, map, reduce, out,
14751501
cmd.update(kwargs)
14761502

14771503
# XXX: Keep doing this automatically?
1504+
read_preference = self.read_preference
14781505
if not isinstance(out, collections.Mapping) or not out.get('inline'):
14791506
read_preference = ReadPreference.PRIMARY
14801507

@@ -1489,8 +1516,7 @@ def map_reduce(self, map, reduce, out,
14891516
else:
14901517
return self.__database[response["result"]]
14911518

1492-
def inline_map_reduce(self, map, reduce,
1493-
full_response=False, read_preference=None, **kwargs):
1519+
def inline_map_reduce(self, map, reduce, full_response=False, **kwargs):
14941520
"""Perform an inline map/reduce operation on this collection.
14951521
14961522
Perform the map/reduce operation on the server in RAM. A result
@@ -1501,31 +1527,26 @@ def inline_map_reduce(self, map, reduce,
15011527
result documents in a list. Otherwise, returns the full
15021528
response from the server to the `map reduce command`_.
15031529
1504-
With :class:`~pymongo.mongo_replica_set_client.MongoReplicaSetClient`,
1505-
if the `read_preference` attribute of this instance is not set to
1506-
:attr:`pymongo.read_preferences.ReadPreference.PRIMARY` or
1507-
:attr:`pymongo.read_preferences.ReadPreference.PRIMARY_PREFERRED`
1508-
the command will be sent to a secondary.
1530+
The :meth:`inline_map_reduce` method obeys the :attr:`read_preference`
1531+
of this :class:`Collection`.
15091532
15101533
:Parameters:
15111534
- `map`: map function (as a JavaScript string)
15121535
- `reduce`: reduce function (as a JavaScript string)
15131536
- `full_response` (optional): if ``True``, return full response to
15141537
this command - otherwise just return the result collection
1515-
- `read_preference`: read preference to use for this map reduce
15161538
- `**kwargs` (optional): additional arguments to the
15171539
`map reduce command`_ may be passed as keyword arguments to this
15181540
helper method, e.g.::
15191541
15201542
>>> db.test.inline_map_reduce(map, reduce, limit=2)
15211543
"""
1522-
15231544
cmd = SON([("mapreduce", self.__name),
15241545
("map", map),
15251546
("reduce", reduce),
15261547
("out", {"inline": 1})])
15271548
cmd.update(kwargs)
1528-
res = self._command(cmd, read_preference)[0]
1549+
res = self._command(cmd)[0]
15291550

15301551
if full_response:
15311552
return res
@@ -1569,9 +1590,8 @@ def find_and_modify(self, query={}, update=None,
15691590
- `manipulate`: (optional): If ``True``, apply any outgoing SON
15701591
manipulators before returning. Ignored when `full_response`
15711592
is set to True. Defaults to ``False``.
1572-
- `**kwargs`: any other options the findAndModify_ command
1573-
supports can be passed here.
1574-
1593+
- `**kwargs` (optional): additional arguments to the findAndModify_
1594+
command may be passed as keyword arguments to this helper method
15751595
15761596
.. mongodoc:: findAndModify
15771597

0 commit comments

Comments
 (0)