New asyncio implementation

docs/project/changelog.rst

@@ -52,7 +52,7 @@ Backwards-incompatible changes
         async def handler(request, path):
           ...
 
-    You should switch to the recommended pattern since 10.1::
+    You should switch to the pattern recommended since version 10.1::
 
         async def handler(request):
             path = request.path  # only if handler() uses the path argument
@@ -61,6 +61,16 @@ Backwards-incompatible changes
 New features
 ............
 
+.. admonition:: websockets 11.0 introduces a new :mod:`asyncio` implementation.
+    :class: important
+
+    This new implementation is intended to be a drop-in replacement for the
+    current implementation. It will become the default in a future release.
+    Please try it and report any issue that you encounter!
+
+    See :func:`websockets.asyncio.client.connect` and
+    :func:`websockets.asyncio.server.serve` for details.
+
 * Validated compatibility with Python 3.12.
 
 12.0
@@ -175,7 +185,8 @@ New features
     It is particularly suited to client applications that establish only one
     connection. It may be used for servers handling few connections.
 
-    See :func:`~sync.client.connect` and :func:`~sync.server.serve` for details.
+    See :func:`websockets.sync.client.connect` and
+    :func:`websockets.sync.server.serve` for details.
 
 * Added ``open_timeout`` to :func:`~server.serve`.
 

docs/reference/index.rst

@@ -26,6 +26,18 @@ clients concurrently.
    asyncio/server
    asyncio/client
 
+:mod:`asyncio` (new)
+--------------------
+
+This is a rewrite of the :mod:`asyncio` implementation. It will become the
+default in the future.
+
+.. toctree::
+   :titlesonly:
+
+   new-asyncio/server
+   new-asyncio/client
+
 :mod:`threading`
 ----------------
 

docs/reference/new-asyncio/client.rst

@@ -0,0 +1,53 @@
+Client (:mod:`asyncio` - new)
+=============================
+
+.. automodule:: websockets.asyncio.client
+
+Opening a connection
+--------------------
+
+.. autofunction:: connect
+    :async:
+
+.. autofunction:: unix_connect
+    :async:
+
+Using a connection
+------------------
+
+.. autoclass:: ClientConnection
+
+    .. automethod:: __aiter__
+
+    .. automethod:: recv
+
+    .. automethod:: recv_streaming
+
+    .. automethod:: send
+
+    .. automethod:: close
+
+    .. automethod:: wait_closed
+
+    .. automethod:: ping
+
+    .. automethod:: pong
+
+    WebSocket connection objects also provide these attributes:
+
+    .. autoattribute:: id
+
+    .. autoattribute:: logger
+
+    .. autoproperty:: local_address
+
+    .. autoproperty:: remote_address
+
+    The following attributes are available after the opening handshake,
+    once the WebSocket connection is open:
+
+    .. autoattribute:: request
+
+    .. autoattribute:: response
+
+    .. autoproperty:: subprotocol

docs/reference/new-asyncio/common.rst

@@ -0,0 +1,43 @@
+:orphan:
+
+Both sides (:mod:`asyncio` - new)
+=================================
+
+.. automodule:: websockets.asyncio.connection
+
+.. autoclass:: Connection
+
+    .. automethod:: __aiter__
+
+    .. automethod:: recv
+
+    .. automethod:: recv_streaming
+
+    .. automethod:: send
+
+    .. automethod:: close
+
+    .. automethod:: wait_closed
+
+    .. automethod:: ping
+
+    .. automethod:: pong
+
+    WebSocket connection objects also provide these attributes:
+
+    .. autoattribute:: id
+
+    .. autoattribute:: logger
+
+    .. autoproperty:: local_address
+
+    .. autoproperty:: remote_address
+
+    The following attributes are available after the opening handshake,
+    once the WebSocket connection is open:
+
+    .. autoattribute:: request
+
+    .. autoattribute:: response
+
+    .. autoproperty:: subprotocol

docs/reference/new-asyncio/server.rst

@@ -0,0 +1,72 @@
+Server (:mod:`asyncio` - new)
+=============================
+
+.. automodule:: websockets.asyncio.server
+
+Creating a server
+-----------------
+
+.. autofunction:: serve
+    :async:
+
+.. autofunction:: unix_serve
+    :async:
+
+Running a server
+----------------
+
+.. autoclass:: WebSocketServer
+
+    .. automethod:: close
+
+    .. automethod:: wait_closed
+
+    .. automethod:: get_loop
+
+    .. automethod:: is_serving
+
+    .. automethod:: start_serving
+
+    .. automethod:: serve_forever
+
+    .. autoattribute:: sockets
+
+Using a connection
+------------------
+
+.. autoclass:: ServerConnection
+
+    .. automethod:: __aiter__
+
+    .. automethod:: recv
+
+    .. automethod:: recv_streaming
+
+    .. automethod:: send
+
+    .. automethod:: close
+
+    .. automethod:: wait_closed
+
+    .. automethod:: ping
+
+    .. automethod:: pong
+
+    WebSocket connection objects also provide these attributes:
+
+    .. autoattribute:: id
+
+    .. autoattribute:: logger
+
+    .. autoproperty:: local_address
+
+    .. autoproperty:: remote_address
+
+    The following attributes are available after the opening handshake,
+    once the WebSocket connection is open:
+
+    .. autoattribute:: request
+
+    .. autoattribute:: response
+
+    .. autoproperty:: subprotocol

pyproject.toml

@@ -47,8 +47,8 @@ branch = true
 omit = [
     # */websockets matches src/websockets and .tox/**/site-packages/websockets
     "*/websockets/__main__.py",
-    "*/websockets/legacy/async_timeout.py",
-    "*/websockets/legacy/compatibility.py",
+    "*/websockets/asyncio/async_timeout.py",
+    "*/websockets/asyncio/compatibility.py",
     "tests/maxi_cov.py",
 ]