Deprecate the old callback-based asynchronous API

doc/changelog.rst

@@ -3,6 +3,12 @@ Changelog
 
 .. currentmodule:: motor.motor_tornado
 
+Motor 1.3.0
+-----------
+
+Deprecate Motor's old callback-based async API in preparation for removing it in
+Motor 2.0. Raise ``DeprecationWarning`` whenever a callback is passed.
+
 Motor 1.2.3
 -----------
 

motor/frameworks/tornado/__init__.py

@@ -21,6 +21,7 @@ See "Frameworks" in the Developer Guide.
 
 import functools
 import os
+import warnings
 from concurrent.futures import ThreadPoolExecutor
 
 import tornado.process
@@ -89,6 +90,10 @@ def future_or_callback(future, callback, io_loop, return_value=_DEFAULT):
     internally.
     """
     if callback:
+        warnings.warn(
+            'Motor\'s callback interface is deprecated, see the "Migrating'
+            ' to Motor 2.0" guide', DeprecationWarning, stacklevel=2)
+
         if not callable(callback):
             raise callback_type_error
 

test/__init__.py

@@ -16,8 +16,10 @@ from __future__ import unicode_literals
 
 """Test Motor, an asynchronous driver for MongoDB and Tornado."""
 
+import contextlib
 import logging
 import unittest
+import warnings
 from unittest import SkipTest
 
 from test.test_environment import env, db_user, CLIENT_PEM
@@ -77,3 +79,13 @@ class MockRequestHandler(object):
 
     def flush(self):
         pass
+
+
+@contextlib.contextmanager
+def assert_deprecation_warnings(n=1):
+    with warnings.catch_warnings(record=True) as records:
+        warnings.filterwarnings('always', category=DeprecationWarning)
+        yield
+
+    assert len(records) == n, \
+        "Expected %d DeprecationWarning, not %r" % (n, records,)

test/asyncio_tests/test_asyncio_cursor.py

@@ -153,7 +153,11 @@ class TestAsyncIOCursor(AsyncIOMockServerTestCase):
                 # Done iterating.
                 future.set_result(True)
 
-        cursor.each(callback)
+        with warnings.catch_warnings():
+            # Should not raise, and not deprecated.
+            warnings.filterwarnings('error')
+            cursor.each(callback)
+
         yield from future
         expected = [{'_id': i} for i in range(200)]
         self.assertEqual(expected, results)

test/tornado_tests/test_motor_collection.py

@@ -142,8 +142,10 @@ class MotorCollectionTest(MotorTest):
     def test_save_callback(self):
         yield self.collection.save({}, callback=None)
 
-        # Should not raise
-        (result, error), _ = yield gen.Task(self.collection.save, {})
+        # PyMongo deprecated "save", Motor deprecated the callback API used by
+        # gen.Task.
+        with test.assert_deprecation_warnings(2):
+            (result, error), _ = yield gen.Task(self.collection.save, {})
         if error:
             raise error
 
@@ -399,7 +401,9 @@ class MotorCollectionTest(MotorTest):
                 else:
                     future.set_result(result)
 
-            cursor.to_list(collection_size, callback=cb)
+            with test.assert_deprecation_warnings():
+                cursor.to_list(collection_size, callback=cb)
+
             docs = yield future
             self.assertAllDocs(expected_sum, docs)
 

test/tornado_tests/test_motor_cursor.py

@@ -32,7 +32,7 @@ from pymongo.errors import OperationFailure
 
 import motor
 import motor.motor_tornado
-from test import SkipTest, env
+from test import SkipTest, env, assert_deprecation_warnings
 from test.tornado_tests import (get_command_line,
                                 MotorTest,
                                 MotorMockServerTest,
@@ -182,7 +182,11 @@ class MotorCursorTest(MotorMockServerTest):
                 # Done iterating.
                 future.set_result(True)
 
-        cursor.each(callback)
+        with warnings.catch_warnings():
+            # Should not raise, and not deprecated.
+            warnings.filterwarnings('error')
+            cursor.each(callback)
+
         yield future
         expected = [{'_id': i} for i in range(200)]
         self.assertEqual(expected, results)
@@ -205,11 +209,15 @@ class MotorCursorTest(MotorMockServerTest):
         cursor = self.collection.find({}, {'_id': 1})
         cursor.sort([('_id', pymongo.ASCENDING)])
         expected = [{'_id': i} for i in range(200)]
-        (result, error), _ = yield gen.Task(cursor.to_list, length=1000)
+        with assert_deprecation_warnings():
+            (result, error), _ = yield gen.Task(cursor.to_list, length=1000)
+
         self.assertEqual(expected, result)
 
         cursor = self.collection.find().where('return foo')
-        (result, error), _ = yield gen.Task(cursor.to_list, length=1000)
+        with assert_deprecation_warnings():
+            (result, error), _ = yield gen.Task(cursor.to_list, length=1000)
+
         self.assertEqual(None, result)
         self.assertTrue(isinstance(error, OperationFailure))
 

test/tornado_tests/test_motor_gridfs.py

@@ -28,6 +28,7 @@ from tornado.testing import gen_test
 
 import motor
 from motor.motor_py3_compat import StringIO
+from test import assert_deprecation_warnings
 from test.tornado_tests import MotorTest
 
 
@@ -147,13 +148,15 @@ class MotorGridfsTest(MotorTest):
 
     @gen_test
     def test_put_callback(self):
-        (oid, error), _ = yield gen.Task(self.fs.put, b"hello")
-        self.assertTrue(isinstance(oid, ObjectId))
-        self.assertEqual(None, error)
+        with assert_deprecation_warnings():
+            (oid, error), _ = yield gen.Task(self.fs.put, b"hello")
+            self.assertTrue(isinstance(oid, ObjectId))
+            self.assertEqual(None, error)
 
-        (result, error), _ = yield gen.Task(self.fs.put, b"hello", _id=oid)
-        self.assertEqual(None, result)
-        self.assertTrue(isinstance(error, FileExists))
+        with assert_deprecation_warnings():
+            (result, error), _ = yield gen.Task(self.fs.put, b"hello", _id=oid)
+            self.assertEqual(None, result)
+            self.assertTrue(isinstance(error, FileExists))
 
     @gen_test
     def test_put_duplicate(self):