Deprecate the legacy asyncio implementation.

aaugustin · aaugustin · commit d62e423744b3 · 2024-09-22T21:04:05.000+02:00
diff --git a/docs/howto/upgrade.rst b/docs/howto/upgrade.rst
@@ -27,15 +27,9 @@ respectively.
 .. admonition:: What will happen to the original implementation?
     :class: hint
 
-    The original implementation is now considered legacy.
-
-    The next steps are:
-
-    1. Deprecating it once the new implementation is considered sufficiently
-       robust.
-    2. Maintaining it for five years per the :ref:`backwards-compatibility
-       policy <backwards-compatibility policy>`.
-    3. Removing it. This is expected to happen around 2030.
+    The original implementation is deprecated. It will be maintained for five
+    years after deprecation according to the :ref:`backwards-compatibility
+    policy <backwards-compatibility policy>`. Then, by 2030, it will be removed.
 
 .. _deprecated APIs:
 
@@ -69,13 +63,14 @@ Import paths
 For context, the ``websockets`` package is structured as follows:
 
 * The new implementation is found in the ``websockets.asyncio`` package.
-* The original implementation was moved to the ``websockets.legacy`` package.
+* The original implementation was moved to the ``websockets.legacy`` package
+  and deprecated.
 * The ``websockets`` package provides aliases for convenience. They were
   switched to the new implementation in version 14.0 or deprecated when there
-  isn't an equivalent API.
+  wasn't an equivalent API.
 * The ``websockets.client`` and ``websockets.server`` packages provide aliases
-  for backwards-compatibility with earlier versions of websockets. They will
-  be deprecated together with the original implementation.
+  for backwards-compatibility with earlier versions of websockets. They were
+  deprecated.
 
 To upgrade to the new :mod:`asyncio` implementation, change import paths as
 shown in the tables below.
diff --git a/docs/index.rst b/docs/index.rst
@@ -28,37 +28,38 @@ with a focus on correctness, simplicity, robustness, and performance.
 
 It supports several network I/O and control flow paradigms.
 
-1. The primary implementation builds upon :mod:`asyncio`, Python's standard
-   asynchronous I/O framework. It provides an elegant coroutine-based API. It's
-   ideal for servers that handle many clients concurrently.
-
-   .. admonition:: As of version :ref:`13.0`, there is a new :mod:`asyncio`
-      implementation.
-      :class: important
-
-      The historical implementation in ``websockets.legacy`` traces its roots to
-      early versions of websockets. Although it's stable and robust, it is now
-      considered legacy.
-
-      The new implementation in ``websockets.asyncio`` is a rewrite on top of
-      the Sans-I/O implementation. It adds a few features that were impossible
-      to implement within the original design.
-
-      The new implementation provides all features of the historical
-      implementation, and a few more. If you're using the historical
-      implementation, you should :doc:`ugrade to the new implementation
-      <howto/upgrade>`. It's usually straightforward.
+1. The default implementation builds upon :mod:`asyncio`, Python's built-in
+   asynchronous I/O library. It provides an elegant coroutine-based API. It's
+   ideal for servers that handle many client connections.
 
 2. The :mod:`threading` implementation is a good alternative for clients,
    especially if you aren't familiar with :mod:`asyncio`. It may also be used
-   for servers that don't need to serve many clients.
+   for servers that handle few client connections.
 
 3. The `Sans-I/O`_ implementation is designed for integrating in third-party
    libraries, typically application servers, in addition being used internally
    by websockets.
 
 .. _Sans-I/O: https://sans-io.readthedocs.io/
 
+Refer to the :doc:`feature support matrices <reference/features>` for the full
+list of features provided by each implementation.
+
+.. admonition:: The :mod:`asyncio` implementation was rewritten.
+   :class: tip
+
+   The new implementation in ``websockets.asyncio`` builds upon the Sans-I/O
+   implementation. It adds features that were impossible to provide in the
+   original design. It was introduced in version 13.0.
+
+   The historical implementation in ``websockets.legacy`` traces its roots to
+   early versions of websockets. While it's stable and robust, it was deprecated
+   in version 14.0 and it will be removed by 2030.
+
+   The new implementation provides the same features as the historical
+   implementation, and then some. If you're using the historical implementation,
+   you should :doc:`ugrade to the new implementation <howto/upgrade>`.
+
 Here's an echo server using the :mod:`asyncio` API:
 
 .. literalinclude:: ../example/echo.py
diff --git a/docs/project/changelog.rst b/docs/project/changelog.rst
@@ -55,6 +55,9 @@ Backwards-incompatible changes
 .. admonition:: The legacy :mod:`asyncio` implementation is now deprecated.
     :class: caution
 
+    The :doc:`upgrade guide <../howto/upgrade>` provides complete instructions
+    to migrate your application.
+
     Aliases for deprecated API were removed from ``__all__``. As a consequence,
     they cannot be imported e.g. with ``from websockets import *`` anymore.
 
diff --git a/docs/reference/index.rst b/docs/reference/index.rst
@@ -13,30 +13,19 @@ Check which implementations support which features and known limitations.
 
    features
 
-:mod:`asyncio` (new)
---------------------
+:mod:`asyncio`
+--------------
 
 It's ideal for servers that handle many clients concurrently.
 
-It's a rewrite of the legacy :mod:`asyncio` implementation.
+This is the default implementation.
 
 .. toctree::
    :titlesonly:
 
    asyncio/server
    asyncio/client
 
-:mod:`asyncio` (legacy)
------------------------
-
-This is the historical implementation.
-
-.. toctree::
-   :titlesonly:
-
-   legacy/server
-   legacy/client
-
 :mod:`threading`
 ----------------
 
@@ -62,6 +51,19 @@ application servers.
    sansio/server
    sansio/client
 
+:mod:`asyncio` (legacy)
+-----------------------
+
+This is the historical implementation.
+
+It is deprecated and will be removed.
+
+.. toctree::
+   :titlesonly:
+
+   legacy/server
+   legacy/client
+
 Extensions
 ----------
 
diff --git a/docs/reference/legacy/client.rst b/docs/reference/legacy/client.rst
@@ -1,6 +1,12 @@
 Client (legacy :mod:`asyncio`)
 ==============================
 
+.. admonition:: The legacy :mod:`asyncio` implementation is deprecated.
+    :class: caution
+
+    The :doc:`upgrade guide <../../howto/upgrade>` provides complete instructions
+    to migrate your application.
+
 .. automodule:: websockets.legacy.client
 
 Opening a connection
diff --git a/docs/reference/legacy/common.rst b/docs/reference/legacy/common.rst
@@ -3,6 +3,12 @@
 Both sides (legacy :mod:`asyncio`)
 ==================================
 
+.. admonition:: The legacy :mod:`asyncio` implementation is deprecated.
+    :class: caution
+
+    The :doc:`upgrade guide <../../howto/upgrade>` provides complete instructions
+    to migrate your application.
+
 .. automodule:: websockets.legacy.protocol
 
 .. autoclass:: WebSocketCommonProtocol(*, logger=None, ping_interval=20, ping_timeout=20, close_timeout=10, max_size=2 ** 20, max_queue=2 ** 5, read_limit=2 ** 16, write_limit=2 ** 16)
diff --git a/docs/reference/legacy/server.rst b/docs/reference/legacy/server.rst
@@ -1,6 +1,12 @@
 Server (legacy :mod:`asyncio`)
 ==============================
 
+.. admonition:: The legacy :mod:`asyncio` implementation is deprecated.
+    :class: caution
+
+    The :doc:`upgrade guide <../../howto/upgrade>` provides complete instructions
+    to migrate your application.
+
 .. automodule:: websockets.legacy.server
 
 Starting a server
diff --git a/docs/topics/design.rst b/docs/topics/design.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 Design (legacy :mod:`asyncio`)
 ==============================
 
diff --git a/docs/topics/index.rst b/docs/topics/index.rst
@@ -12,7 +12,6 @@ Get a deeper understanding of how websockets is built and why.
    broadcast
    compression
    keepalive
-   design
    memory
    security
    performance
diff --git a/src/websockets/auth.py b/src/websockets/auth.py
@@ -2,11 +2,17 @@
 
 import warnings
 
-from .legacy.auth import *
-from .legacy.auth import __all__  # noqa: F401
+
+with warnings.catch_warnings():
+    # Suppress redundant DeprecationWarning raised by websockets.legacy.
+    warnings.filterwarnings("ignore", category=DeprecationWarning)
+    from .legacy.auth import *
+    from .legacy.auth import __all__  # noqa: F401
 
 
 warnings.warn(  # deprecated in 14.0
-    "websockets.auth is deprecated",
+    "websockets.auth, an alias for websockets.legacy.auth, is deprecated; "
+    "see https://websockets.readthedocs.io/en/stable/howto/upgrade.html "
+    "for upgrade instructions",
     DeprecationWarning,
 )
diff --git a/src/websockets/http.py b/src/websockets/http.py
@@ -3,7 +3,12 @@
 import warnings
 
 from .datastructures import Headers, MultipleValuesError  # noqa: F401
-from .legacy.http import read_request, read_response  # noqa: F401
+
+
+with warnings.catch_warnings():
+    # Suppress redundant DeprecationWarning raised by websockets.legacy.
+    warnings.filterwarnings("ignore", category=DeprecationWarning)
+    from .legacy.http import read_request, read_response  # noqa: F401
 
 
 warnings.warn(  # deprecated in 9.0 - 2021-09-01
diff --git a/src/websockets/legacy/__init__.py b/src/websockets/legacy/__init__.py
@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+import warnings
+
+
+warnings.warn(  # deprecated in 14.0
+    "websockets.legacy is deprecated; "
+    "see https://websockets.readthedocs.io/en/stable/howto/upgrade.html "
+    "for upgrade instructions",
+    DeprecationWarning,
+)
diff --git a/tests/legacy/__init__.py b/tests/legacy/__init__.py
@@ -0,0 +1,9 @@
+from __future__ import annotations
+
+import warnings
+
+
+with warnings.catch_warnings():
+    # Suppress DeprecationWarning raised by websockets.legacy.
+    warnings.filterwarnings("ignore", category=DeprecationWarning)
+    import websockets.legacy  # noqa: F401
diff --git a/tests/maxi_cov.py b/tests/maxi_cov.py
@@ -9,7 +9,6 @@
 
 
 UNMAPPED_SRC_FILES = [
-    "websockets/auth.py",
     "websockets/typing.py",
     "websockets/version.py",
 ]
@@ -105,7 +104,6 @@ def get_ignored_files(src_dir="src"):
         # or websockets (import locations).
         "*/websockets/asyncio/async_timeout.py",
         "*/websockets/asyncio/compatibility.py",
-        "*/websockets/auth.py",
         # This approach isn't applicable to the test suite of the legacy
         # implementation, due to the huge test_client_server test module.
         "*/websockets/legacy/*",
diff --git a/tests/test_auth.py b/tests/test_auth.py
@@ -0,0 +1,14 @@
+from .utils import DeprecationTestCase
+
+
+class BackwardsCompatibilityTests(DeprecationTestCase):
+    def test_headers_class(self):
+        with self.assertDeprecationWarning(
+            "websockets.auth, an alias for websockets.legacy.auth, is deprecated; "
+            "see https://websockets.readthedocs.io/en/stable/howto/upgrade.html "
+            "for upgrade instructions",
+        ):
+            from websockets.auth import (
+                BasicAuthWebSocketServerProtocol,  # noqa: F401
+                basic_auth_protocol_factory,  # noqa: F401
+            )

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+:orphan:`
	`2`	`+`
`1`	`3`	Design (legacy :mod:`asyncio`)
`2`	`4`	`==============================`
`3`	`5`