PYTHON-1326 Remove the "useCursor" aggregate option (mongodb#560)

Author: ShaneHarvey

doc/changelog.rst

@@ -36,6 +36,8 @@ Breaking Changes in 4.0
 - Removed :meth:`pymongo.collection.Collection.remove`.
 - Removed :meth:`pymongo.collection.Collection.find_and_modify`.
 - Removed :meth:`pymongo.collection.Collection.group`.
+- Removed the ``useCursor`` option for
+ :meth:`~pymongo.collection.Collection.aggregate`.
 - Removed :meth:`pymongo.mongo_client.MongoClient.close_cursor`. Use
  :meth:`pymongo.cursor.Cursor.close` instead.
 - Removed :meth:`pymongo.mongo_client.MongoClient.kill_cursors`.

doc/migrate-to-pymongo4.rst

@@ -140,6 +140,14 @@ can be changed to this::
 Collection
 ----------
 
+The useCursor option for Collection.aggregate is removed
+........................................................
+
+Removed the ``useCursor`` option for
+:meth:`~pymongo.collection.Collection.aggregate` which was deprecated in
+PyMongo 3.6. The option was only necessary when upgrading from MongoDB 2.4
+to MongoDB 2.6.
+
 Collection.insert is removed
 ............................
 

pymongo/aggregation.py

@@ -169,15 +169,6 @@ def get_cursor(self, session, server, sock_info, slave_ok):
 
 
 class _CollectionAggregationCommand(_AggregationCommand):
- def __init__(self, *args, **kwargs):
- # Pop additional option and initialize parent class.
- use_cursor = kwargs.pop("use_cursor", True)
- super(_CollectionAggregationCommand, self).__init__(*args, **kwargs)
-
- # Remove the cursor document if the user has set use_cursor to False.
- self._use_cursor = use_cursor
- if not self._use_cursor:
- self._options.pop("cursor", None)
 
  @property
  def _aggregation_target(self):
@@ -201,7 +192,7 @@ def __init__(self, *args, **kwargs):
  super(_CollectionRawAggregationCommand, self).__init__(*args, **kwargs)
 
  # For raw-batches, we set the initial batchSize for the cursor to 0.
- if self._use_cursor and not self._performs_write:
+ if not self._performs_write:
  self._options["cursor"]["batchSize"] = 0
 
 

pymongo/collection.py

@@ -2124,19 +2124,9 @@ def options(self, session=None):
 
  def _aggregate(self, aggregation_command, pipeline, cursor_class, session,
  explicit_session, **kwargs):
- # Remove things that are not command options.
- use_cursor = True
- if "useCursor" in kwargs:
- warnings.warn(
- "The useCursor option is deprecated "
- "and will be removed in PyMongo 4.0",
- DeprecationWarning, stacklevel=2)
- use_cursor = common.validate_boolean(
- "useCursor", kwargs.pop("useCursor", True))
-
  cmd = aggregation_command(
  self, cursor_class, pipeline, kwargs, explicit_session,
- user_fields={'cursor': {'firstBatch': 1}}, use_cursor=use_cursor)
+ user_fields={'cursor': {'firstBatch': 1}})
  return self.__database.client._retryable_read(
  cmd.get_cursor, cmd.get_read_preference(session), session,
  retryable=not cmd._performs_write)
@@ -2155,13 +2145,10 @@ def aggregate(self, pipeline, session=None, **kwargs):
  - `maxTimeMS` (int): The maximum amount of time to allow the operation
  to run in milliseconds.
  - `batchSize` (int): The maximum number of documents to return per
- batch. Ignored if the connected mongod or mongos does not support
- returning aggregate results using a cursor, or `useCursor` is
- ``False``.
+ batch.
  - `collation` (optional): An instance of
  :class:`~pymongo.collation.Collation`. This option is only supported
  on MongoDB 3.4 and above.
- - `useCursor` (bool): Deprecated. Will be removed in PyMongo 4.0.
 
  The :meth:`aggregate` method obeys the :attr:`read_preference` of this
  :class:`Collection`, except when ``$out`` or ``$merge`` are used, in
@@ -2186,6 +2173,8 @@ def aggregate(self, pipeline, session=None, **kwargs):
  A :class:`~pymongo.command_cursor.CommandCursor` over the result
  set.
 
+ .. versionchanged:: 4.0
+ Removed the ``useCursor`` option.
  .. versionchanged:: 3.9
  Apply this collection's read concern to pipelines containing the
  `$out` stage when connected to MongoDB >= 4.2.

test/test_collection.py

@@ -1615,12 +1615,7 @@ def test_aggregate(self):
  self.assertRaises(TypeError, db.test.aggregate, "wow")
 
  pipeline = {"$project": {"_id": False, "foo": True}}
- # MongoDB 3.5.1+ requires either the 'cursor' or 'explain' options.
- if client_context.version.at_least(3, 5, 1):
- result = db.test.aggregate([pipeline])
- else:
- result = db.test.aggregate([pipeline], useCursor=False)
-
+ result = db.test.aggregate([pipeline])
  self.assertTrue(isinstance(result, CommandCursor))
  self.assertEqual([{'foo': [1, 2]}], list(result))
 
@@ -1639,11 +1634,7 @@ def test_aggregate_raw_bson(self):
  coll = db.get_collection(
  'test',
  codec_options=CodecOptions(document_class=RawBSONDocument))
- # MongoDB 3.5.1+ requires either the 'cursor' or 'explain' options.
- if client_context.version.at_least(3, 5, 1):
- result = coll.aggregate([pipeline])
- else:
- result = coll.aggregate([pipeline], useCursor=False)
+ result = coll.aggregate([pipeline])
  self.assertTrue(isinstance(result, CommandCursor))
  first_result = next(result)
  self.assertIsInstance(first_result, RawBSONDocument)
@@ -1655,9 +1646,6 @@ def test_aggregation_cursor_validation(self):
  cursor = db.test.aggregate([projection], cursor={})
  self.assertTrue(isinstance(cursor, CommandCursor))
 
- cursor = db.test.aggregate([projection], useCursor=True)
- self.assertTrue(isinstance(cursor, CommandCursor))
-
  def test_aggregation_cursor(self):
  db = self.db
  if client_context.has_secondaries: