PYTHON-988 - Deprecate cursor managers and kill_cursors

Author: behackett

pymongo/cursor_manager.py

@@ -12,30 +12,39 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""A manager to handle when cursors are killed after they are closed.
+"""DEPRECATED - A manager to handle when cursors are killed after they are
+closed.
 
 New cursor managers should be defined as subclasses of CursorManager and can be
 installed on a client by calling
 :meth:`~pymongo.mongo_client.MongoClient.set_cursor_manager`.
 
+.. versionchanged:: 3.3
+   Deprecated, for real this time.
+
 .. versionchanged:: 3.0
    Undeprecated. :meth:`~pymongo.cursor_manager.CursorManager.close` now
    requires an `address` argument. The ``BatchCursorManager`` class is removed.
 """
 
+import warnings
 import weakref
 from bson.py3compat import integer_types
 
 
 class CursorManager(object):
-    """The cursor manager base class."""
+    """DEPRECATED - The cursor manager base class."""
 
     def __init__(self, client):
         """Instantiate the manager.
 
         :Parameters:
           - `client`: a MongoClient
         """
+        warnings.warn(
+            "Cursor managers are deprecated.",
+            DeprecationWarning,
+            stacklevel=2)
         self.__client = weakref.ref(client)
 
     def close(self, cursor_id, address):

pymongo/mongo_client.py

@@ -34,7 +34,9 @@
 import contextlib
 import datetime
 import threading
+import warnings
 import weakref
+
 from collections import defaultdict
 
 from bson.codec_options import DEFAULT_CODEC_OPTIONS
@@ -358,7 +360,7 @@ def __init__(
 
         self.__default_database_name = dbase
         self.__lock = threading.Lock()
-        self.__cursor_manager = CursorManager(self)
+        self.__cursor_manager = None
         self.__kill_cursors_queue = []
 
         self._event_listeners = options.pool_options.event_listeners
@@ -712,7 +714,7 @@ def close(self):
         self._topology.close()
 
     def set_cursor_manager(self, manager_class):
-        """Set this client's cursor manager.
+        """DEPRECATED - Set this client's cursor manager.
 
         Raises :class:`TypeError` if `manager_class` is not a subclass of
         :class:`~pymongo.cursor_manager.CursorManager`. A cursor manager
@@ -723,9 +725,16 @@ def set_cursor_manager(self, manager_class):
         :Parameters:
           - `manager_class`: cursor manager to use
 
+        .. versionchanged:: 3.3
+           Deprecated, for real this time.
+
         .. versionchanged:: 3.0
            Undeprecated.
         """
+        warnings.warn(
+            "set_cursor_manager is Deprecated",
+            DeprecationWarning,
+            stacklevel=2)
         manager = manager_class(self)
         if not isinstance(manager, CursorManager):
             raise TypeError("manager_class must be a subclass of "
@@ -920,12 +929,17 @@ def __getitem__(self, name):
         return database.Database(self, name)
 
     def close_cursor(self, cursor_id, address=None):
-        """Close a single database cursor.
+        """Send a kill cursors message soon with the given id.
 
         Raises :class:`TypeError` if `cursor_id` is not an instance of
         ``(int, long)``. What closing the cursor actually means
         depends on this client's cursor manager.
 
+        This method may be called from a :class:`~pymongo.cursor.Cursor`
+        destructor during garbage collection, so it isn't safe to take a
+        lock or do network I/O. Instead, we schedule the cursor to be closed
+        soon on a background thread.
+
         :Parameters:
           - `cursor_id`: id of cursor to close
           - `address` (optional): (host, port) pair of the cursor's server.
@@ -938,30 +952,36 @@ def close_cursor(self, cursor_id, address=None):
         if not isinstance(cursor_id, integer_types):
             raise TypeError("cursor_id must be an instance of (int, long)")
 
-        self.__cursor_manager.close(cursor_id, address)
+        if self.__cursor_manager is not None:
+            self.__cursor_manager.close(cursor_id, address)
+        else:
+            self.__kill_cursors_queue.append((address, [cursor_id]))
 
     def kill_cursors(self, cursor_ids, address=None):
-        """Send a kill cursors message soon with the given ids.
+        """DEPRECATED - Send a kill cursors message soon with the given ids.
 
         Raises :class:`TypeError` if `cursor_ids` is not an instance of
         ``list``.
 
-        This method may be called from a :class:`~pymongo.cursor.Cursor`
-        destructor during garbage collection, so it isn't safe to take a
-        lock or do network I/O. Instead, we schedule the cursor to be closed
-        soon on a background thread.
-
         :Parameters:
           - `cursor_ids`: list of cursor ids to kill
           - `address` (optional): (host, port) pair of the cursor's server.
             If it is not provided, the client attempts to close the cursor on
             the primary or standalone, or a mongos server.
 
+        .. versionchanged:: 3.3
+           Deprecated.
+
         .. versionchanged:: 3.0
            Now accepts an `address` argument. Schedules the cursors to be
            closed on a background thread instead of sending the message
            immediately.
         """
+        warnings.warn(
+            "kill_cursors is deprecated.",
+            DeprecationWarning,
+            stacklevel=2)
+
         if not isinstance(cursor_ids, list):
             raise TypeError("cursor_ids must be a list")
 

test/test_client.py

@@ -22,7 +22,6 @@
 import sys
 import time
 import traceback
-import warnings
 
 sys.path[0:0] = [""]
 
@@ -39,10 +38,8 @@
                             ConnectionFailure,
                             InvalidName,
                             OperationFailure,
-                            CursorNotFound,
                             NetworkTimeout,
                             InvalidURI)
-from pymongo.message import _CursorAddress
 from pymongo.mongo_client import MongoClient
 from pymongo.pool import SocketInfo
 from pymongo.read_preferences import ReadPreference
@@ -807,68 +804,6 @@ def test_operation_failure(self):
         new_sock_info = next(iter(pool.sockets))
         self.assertEqual(old_sock_info, new_sock_info)
 
-    def test_kill_cursors_with_cursoraddress(self):
-        if (client_context.is_mongos
-                and not client_context.version.at_least(2, 4, 7)):
-            # Old mongos sends incorrectly formatted error response when
-            # cursor isn't found, see SERVER-9738.
-            raise SkipTest("Can't test kill_cursors against old mongos")
-
-        self.collection = self.client.pymongo_test.test
-        self.collection.drop()
-
-        self.collection.insert_many([{'_id': i} for i in range(200)])
-        cursor = self.collection.find().batch_size(1)
-        next(cursor)
-        self.client.kill_cursors(
-            [cursor.cursor_id],
-            _CursorAddress(self.client.address, self.collection.full_name))
-
-        # Prevent killcursors from reaching the server while a getmore is in
-        # progress -- the server logs "Assertion: 16089:Cannot kill active
-        # cursor."
-        time.sleep(2)
-
-        def raises_cursor_not_found():
-            try:
-                next(cursor)
-                return False
-            except CursorNotFound:
-                return True
-
-        wait_until(raises_cursor_not_found, 'close cursor')
-
-    def test_kill_cursors_with_tuple(self):
-        if (client_context.is_mongos
-                and not client_context.version.at_least(2, 4, 7)):
-            # Old mongos sends incorrectly formatted error response when
-            # cursor isn't found, see SERVER-9738.
-            raise SkipTest("Can't test kill_cursors against old mongos")
-
-        self.collection = self.client.pymongo_test.test
-        self.collection.drop()
-
-        self.collection.insert_many([{'_id': i} for i in range(200)])
-        cursor = self.collection.find().batch_size(1)
-        next(cursor)
-        self.client.kill_cursors(
-            [cursor.cursor_id],
-            self.client.address)
-
-        # Prevent killcursors from reaching the server while a getmore is in
-        # progress -- the server logs "Assertion: 16089:Cannot kill active
-        # cursor."
-        time.sleep(2)
-
-        def raises_cursor_not_found():
-            try:
-                next(cursor)
-                return False
-            except CursorNotFound:
-                return True
-
-        wait_until(raises_cursor_not_found, 'close cursor')
-
     def test_lazy_connect_w0(self):
         # Ensure that connect-on-demand works when the first operation is
         # an unacknowledged write. This exercises _writable_max_wire_version().

test/test_cursor.py

@@ -30,9 +30,7 @@
                      DESCENDING,
                      ALL,
                      OFF)
-from pymongo.command_cursor import CommandCursor
 from pymongo.cursor import CursorType
-from pymongo.cursor_manager import CursorManager
 from pymongo.errors import (InvalidOperation,
                             OperationFailure,
                             ExecutionTimeout)
@@ -1217,38 +1215,6 @@ def test_comment(self):
         next(cursor)
         self.assertRaises(InvalidOperation, cursor.comment, 'hello')
 
-    def test_cursor_transfer(self):
-
-        # This is just a test, don't try this at home...
-
-        client = client_context.rs_or_standalone_client
-        db = client.pymongo_test
-
-        db.test.delete_many({})
-        db.test.insert_many([{'_id': i} for i in range(200)])
-
-        class CManager(CursorManager):
-            def __init__(self, client):
-                super(CManager, self).__init__(client)
-
-            def close(self, dummy, dummy2):
-                # Do absolutely nothing...
-                pass
-
-        client.set_cursor_manager(CManager)
-        self.addCleanup(client.set_cursor_manager, CursorManager)
-        docs = []
-        cursor = db.test.find().batch_size(10)
-        docs.append(next(cursor))
-        cursor.close()
-        docs.extend(cursor)
-        self.assertEqual(len(docs), 10)
-        cmd_cursor = {'id': cursor.cursor_id, 'firstBatch': []}
-        ccursor = CommandCursor(cursor.collection, cmd_cursor,
-                                cursor.address, retrieved=cursor.retrieved)
-        docs.extend(ccursor)
-        self.assertEqual(len(docs), 200)
-
     def test_modifiers(self):
         cur = self.db.test.find()
         self.assertTrue('$query' not in cur._Cursor__query_spec())

test/test_cursor_manager.py

@@ -15,9 +15,11 @@
 """Test the cursor_manager module."""
 
 import sys
+import warnings
 
 sys.path[0:0] = [""]
 
+from pymongo.command_cursor import CommandCursor
 from pymongo.cursor_manager import CursorManager
 from pymongo.errors import CursorNotFound
 from pymongo.message import _CursorAddress
@@ -34,6 +36,10 @@ class TestCursorManager(IntegrationTest):
     @classmethod
     def setUpClass(cls):
         super(TestCursorManager, cls).setUpClass()
+        cls.warn_context = warnings.catch_warnings()
+        cls.warn_context.__enter__()
+        warnings.simplefilter("ignore", DeprecationWarning)
+
         cls.collection = cls.db.test
         cls.collection.drop()
 
@@ -42,6 +48,8 @@ def setUpClass(cls):
 
     @classmethod
     def tearDownClass(cls):
+        cls.warn_context.__exit__()
+        cls.warn_context = None 
         cls.collection.drop()
 
     def test_cursor_manager_validation(self):
@@ -89,6 +97,37 @@ def raises_cursor_not_found():
             wait_until(raises_cursor_not_found, 'close cursor')
             self.assertTrue(self.close_was_called)
 
+    def test_cursor_transfer(self):
+
+        # This is just a test, don't try this at home...
+
+        client = rs_or_single_client()
+        db = client.pymongo_test
+
+        db.test.delete_many({})
+        db.test.insert_many([{'_id': i} for i in range(200)])
+
+        class CManager(CursorManager):
+            def __init__(self, client):
+                super(CManager, self).__init__(client)
+
+            def close(self, dummy, dummy2):
+                # Do absolutely nothing...
+                pass
+
+        client.set_cursor_manager(CManager)
+        docs = []
+        cursor = db.test.find().batch_size(10)
+        docs.append(next(cursor))
+        cursor.close()
+        docs.extend(cursor)
+        self.assertEqual(len(docs), 10)
+        cmd_cursor = {'id': cursor.cursor_id, 'firstBatch': []}
+        ccursor = CommandCursor(cursor.collection, cmd_cursor,
+                                cursor.address, retrieved=cursor.retrieved)
+        docs.extend(ccursor)
+        self.assertEqual(len(docs), 200)
+
 
 if __name__ == "__main__":
     unittest.main()