PYTHON-2097 Deprecate oplogReplay find command option

doc/changelog.rst

@@ -6,6 +6,10 @@ Changes in Version 3.11.0
 
 Version 3.11 adds support for MongoDB 4.4. Highlights include:
 
+- Deprecated the ``oplog_replay`` parameter to
+  :meth:`pymongo.collection.Collection.find`. Starting in MongoDB 4.4, the
+  server optimizes queries against the oplog collection without requiring
+  the user to set this flag.
 - Added index hinting support to the
   :meth:`pymongo.collection.Collection.replace_one`,
   :meth:`pymongo.collection.Collection.update_one`,

doc/examples/tailable.rst

@@ -24,9 +24,11 @@ of a replica set member::
   while True:
       # For a regular capped collection CursorType.TAILABLE_AWAIT is the
       # only option required to create a tailable cursor. When querying the
-      # oplog the oplog_replay option enables an optimization to quickly
+      # oplog, the oplog_replay option enables an optimization to quickly
       # find the 'ts' value we're looking for. The oplog_replay option
-      # can only be used when querying the oplog.
+      # can only be used when querying the oplog. Starting in MongoDB 4.4
+      # this option is ignored by the server as queries against the oplog
+      # are optimized automatically by the MongoDB query engine.
       cursor = oplog.find({'ts': {'$gt': ts}},
                           cursor_type=pymongo.CursorType.TAILABLE_AWAIT,
                           oplog_replay=True)

pymongo/collection.py

@@ -1366,12 +1366,12 @@ class Collection(common.BaseObject):
           - `allow_partial_results` (optional): if True, mongos will return
             partial results if some shards are down instead of returning an
             error.
-          - `oplog_replay` (optional): If True, set the oplogReplay query
-            flag.
+          - `oplog_replay` (optional): **DEPRECATED** - if True, set the
+            oplogReplay query flag. Default: False.
           - `batch_size` (optional): Limits the number of documents returned in
             a single batch.
-          - `manipulate` (optional): **DEPRECATED** - If True (the default),
-            apply any outgoing SON manipulators before returning.
+          - `manipulate` (optional): **DEPRECATED** - If True, apply any
+            outgoing SON manipulators before returning. Default: True.
           - `collation` (optional): An instance of
             :class:`~pymongo.collation.Collation`. This option is only supported
             on MongoDB 3.4 and above.
@@ -1436,6 +1436,10 @@ class Collection(common.BaseObject):
 
         .. versionchanged:: 3.11
            Added the ``allow_disk_use`` option.
+           Deprecated the ``oplog_replay`` option. Support for this option is
+           deprecated in MongoDB 4.4. The query engine now automatically
+           optimizes queries against the oplog without requiring this
+           option to be set.
 
         .. versionchanged:: 3.7
            Deprecated the ``snapshot`` option, which is deprecated in MongoDB