Deprecate legacy implementation

docs/howto/upgrade.rst

@@ -3,8 +3,8 @@ Upgrade to the new :mod:`asyncio` implementation
 
 .. currentmodule:: websockets
 
-The new :mod:`asyncio` implementation is a rewrite of the original
-implementation of websockets.
+The new :mod:`asyncio` implementation, which is now the default, is a rewrite of
+the original implementation of websockets.
 
 It provides a very similar API. However, there are a few differences.
 
@@ -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 ``websockets`` package provides aliases for convenience. Currently, they
-  point to the original implementation. They will be updated to point to the new
-  implementation when it feels mature.
+* 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
+  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.
@@ -90,12 +85,12 @@ Client APIs
 +-------------------------------------------------------------------+-----------------------------------------------------+
 | Legacy :mod:`asyncio` implementation                              | New :mod:`asyncio` implementation                   |
 +===================================================================+=====================================================+
-| ``websockets.connect()``                                     |br| | :func:`websockets.asyncio.client.connect`           |
-| ``websockets.client.connect()``                              |br| |                                                     |
+| ``websockets.connect()`` *(before 14.0)*                     |br| | ``websockets.connect()`` *(since 14.0)*        |br| |
+| ``websockets.client.connect()``                              |br| | :func:`websockets.asyncio.client.connect`           |
 | :func:`websockets.legacy.client.connect`                          |                                                     |
 +-------------------------------------------------------------------+-----------------------------------------------------+
-| ``websockets.unix_connect()``                                |br| | :func:`websockets.asyncio.client.unix_connect`      |
-| ``websockets.client.unix_connect()``                         |br| |                                                     |
+| ``websockets.unix_connect()`` *(before 14.0)*                |br| | ``websockets.unix_connect()`` *(since 14.0)*   |br| |
+| ``websockets.client.unix_connect()``                         |br| | :func:`websockets.asyncio.client.unix_connect`      |
 | :func:`websockets.legacy.client.unix_connect`                     |                                                     |
 +-------------------------------------------------------------------+-----------------------------------------------------+
 | ``websockets.WebSocketClientProtocol``                       |br| | :class:`websockets.asyncio.client.ClientConnection` |
@@ -109,12 +104,12 @@ Server APIs
 +-------------------------------------------------------------------+-----------------------------------------------------+
 | Legacy :mod:`asyncio` implementation                              | New :mod:`asyncio` implementation                   |
 +===================================================================+=====================================================+
-| ``websockets.serve()``                                       |br| | :func:`websockets.asyncio.server.serve`             |
-| ``websockets.server.serve()``                                |br| |                                                     |
+| ``websockets.serve()`` *(before 14.0)*                       |br| | ``websockets.serve()`` *(since 14.0)*          |br| |
+| ``websockets.server.serve()``                                |br| | :func:`websockets.asyncio.server.serve`             |
 | :func:`websockets.legacy.server.serve`                            |                                                     |
 +-------------------------------------------------------------------+-----------------------------------------------------+
-| ``websockets.unix_serve()``                                  |br| | :func:`websockets.asyncio.server.unix_serve`        |
-| ``websockets.server.unix_serve()``                           |br| |                                                     |
+| ``websockets.unix_serve()`` *(before 14.0)*                  |br| | ``websockets.unix_serve()`` *(since 14.0)*     |br| |
+| ``websockets.server.unix_serve()``                           |br| | :func:`websockets.asyncio.server.unix_serve`        |
 | :func:`websockets.legacy.server.unix_serve`                       |                                                     |
 +-------------------------------------------------------------------+-----------------------------------------------------+
 | ``websockets.WebSocketServer``                               |br| | :class:`websockets.asyncio.server.Server`           |
@@ -125,8 +120,8 @@ Server APIs
 | ``websockets.server.WebSocketServerProtocol``                |br| |                                                     |
 | :class:`websockets.legacy.server.WebSocketServerProtocol`         |                                                     |
 +-------------------------------------------------------------------+-----------------------------------------------------+
-| ``websockets.broadcast()``                                   |br| | :func:`websockets.asyncio.server.broadcast`         |
-| :func:`websockets.legacy.server.broadcast()`                      |                                                     |
+| ``websockets.broadcast()`` *(before 14.0)*                   |br| | ``websockets.broadcast()`` *(since 14.0)*      |br| |
+| :func:`websockets.legacy.server.broadcast()`                      | :func:`websockets.asyncio.server.broadcast`         |
 +-------------------------------------------------------------------+-----------------------------------------------------+
 | ``websockets.BasicAuthWebSocketServerProtocol``              |br| | See below :ref:`how to migrate <basic-auth>` to     |
 | ``websockets.auth.BasicAuthWebSocketServerProtocol``         |br| | :func:`websockets.asyncio.server.basic_auth`.       |

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

docs/project/changelog.rst

@@ -40,6 +40,26 @@ Backwards-incompatible changes
 
     websockets 13.1 is the last version supporting Python 3.8.
 
+.. admonition:: The new :mod:`asyncio` implementation is now the default.
+    :class: caution
+
+    The following aliases in the ``websockets`` package were switched to the new
+    :mod:`asyncio` implementation::
+
+        from websockets import connect, unix_connext
+        from websockets import broadcast, serve, unix_serve
+
+    If you're using any of them, then you must follow the :doc:`upgrade guide
+    <../howto/upgrade>` immediately.
+
+.. 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.
 
 .. _13.1:
 

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
 ----------
 
@@ -98,5 +100,5 @@ guarantees of behavior or backwards-compatibility for private APIs.
 Convenience imports
 -------------------
 
-For convenience, many public APIs can be imported directly from the
+For convenience, some public APIs can be imported directly from the
 ``websockets`` package.

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

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)

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

docs/topics/design.rst

@@ -1,3 +1,5 @@
+:orphan:
+
 Design (legacy :mod:`asyncio`)
 ==============================
 

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