websocket: deprecate callback argument to websocket_connect

tornado/test/websocket_test.py

@@ -14,7 +14,7 @@
 from tornado.netutil import Resolver
 from tornado.simple_httpclient import SimpleAsyncHTTPClient
 from tornado.template import DictLoader
-from tornado.test.util import abstract_base_test
+from tornado.test.util import abstract_base_test, ignore_deprecation
 from tornado.testing import AsyncHTTPTestCase, gen_test, bind_unused_port, ExpectLog
 from tornado.web import Application, RequestHandler
 
@@ -333,9 +333,10 @@ def test_websocket_gen(self):
         self.assertEqual(response, "hello")
 
     def test_websocket_callbacks(self):
-        websocket_connect(
-            "ws://127.0.0.1:%d/echo" % self.get_http_port(), callback=self.stop
-        )
+        with ignore_deprecation():
+            websocket_connect(
+                "ws://127.0.0.1:%d/echo" % self.get_http_port(), callback=self.stop
+            )
         ws = self.wait().result()
         ws.write_message("hello")
         ws.read_message(self.stop)

tornado/websocket.py

@@ -1675,6 +1675,11 @@ def websocket_connect(
 
     .. versionchanged:: 6.3
        Added the ``resolver`` argument.
+
+    .. deprecated:: 6.5
+       The ``callback`` argument is deprecated and will be removed in Tornado 7.0.
+       Use the returned Future instead. Note that ``on_message_callback`` is not
+       deprecated and may still be used.
     """
     if isinstance(url, httpclient.HTTPRequest):
         assert connect_timeout is None
@@ -1699,5 +1704,11 @@ def websocket_connect(
         resolver=resolver,
     )
     if callback is not None:
+        warnings.warn(
+            "The callback argument to websocket_connect is deprecated. "
+            "Use the returned Future instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         IOLoop.current().add_future(conn.connect_future, callback)
     return conn.connect_future