Add trio implementation

docs/conf.py

@@ -50,6 +50,8 @@
     ("py:meth", "protocol.WebSocketCommonProtocol.connection_lost"),
     ("py:meth", "protocol.WebSocketCommonProtocol.read_message"),
     ("py:meth", "protocol.WebSocketCommonProtocol.write_frame"),
+    # Caused by https://github.com/sphinx-doc/sphinx/issues/13838
+    ("py:class", "ssl_module.SSLContext"),
 ]
 
 # Add any Sphinx extension module names here, as strings. They can be
@@ -85,6 +87,7 @@
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3", None),
     "sesame": ("https://django-sesame.readthedocs.io/en/stable/", None),
+    "trio": ("https://trio.readthedocs.io/en/stable/", None),
     "werkzeug": ("https://werkzeug.palletsprojects.com/en/stable/", None),
 }
 

docs/index.rst

@@ -70,6 +70,10 @@ Here's an echo server and corresponding client.
 
     .. literalinclude:: ../example/sync/echo.py
 
+.. tab:: trio
+
+    .. literalinclude:: ../example/trio/echo.py
+
 .. tab:: asyncio
     :new-set:
 
@@ -79,6 +83,11 @@ Here's an echo server and corresponding client.
 
     .. literalinclude:: ../example/sync/hello.py
 
+.. tab:: trio
+
+    .. literalinclude:: ../example/trio/hello.py
+
+
 Don't worry about the opening and closing handshakes, pings and pongs, or any
 other behavior described in the WebSocket specification. websockets takes care
 of this under the hood so you can focus on your application!

docs/project/changelog.rst

@@ -43,6 +43,14 @@ Backwards-incompatible changes
 New features
 ............
 
+.. admonition:: websockets 16.0 introduces a :mod:`trio` implementation.
+    :class: important
+
+    It is an alternative to the :mod:`asyncio` implementation.
+
+    See :func:`websockets.trio.client.connect` and
+    :func:`websockets.trio.server.serve` for details.
+
 * Validated compatibility with Python 3.14.
 
 Improvements

docs/reference/asyncio/server.rst

@@ -46,7 +46,7 @@ Running a server
 
     .. automethod:: serve_forever
 
-    .. autoattribute:: sockets
+    .. autoproperty:: sockets
 
 Using a connection
 ------------------

docs/reference/index.rst

@@ -37,6 +37,17 @@ This alternative implementation can be a good choice for clients.
    sync/server
    sync/client
 
+:mod:`trio`
+------------
+
+This is another option for servers that handle many clients concurrently.
+
+.. toctree::
+   :titlesonly:
+
+   trio/server
+   trio/client
+
 `Sans-I/O`_
 -----------
 

docs/reference/trio/client.rst

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

docs/reference/trio/common.rst

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

docs/reference/trio/server.rst

@@ -0,0 +1,84 @@
+Server (:mod:`trio`)
+=======================
+
+.. automodule:: websockets.trio.server
+
+Creating a server
+-----------------
+
+.. autofunction:: serve
+    :async:
+
+.. currentmodule:: websockets.trio.server
+
+Running a server
+----------------
+
+.. autoclass:: Server
+
+    .. autoattribute:: connections
+
+    .. automethod:: aclose
+
+    .. autoattribute:: listeners
+
+Using a connection
+------------------
+
+.. autoclass:: ServerConnection
+
+    .. automethod:: __aiter__
+
+    .. automethod:: recv
+
+    .. automethod:: recv_streaming
+
+    .. automethod:: send
+
+    .. automethod:: aclose
+
+    .. automethod:: wait_closed
+
+    .. automethod:: ping
+
+    .. automethod:: pong
+
+    .. automethod:: respond
+
+    WebSocket connection objects also provide these attributes:
+
+    .. autoattribute:: id
+
+    .. autoattribute:: logger
+
+    .. autoproperty:: local_address
+
+    .. autoproperty:: remote_address
+
+    .. autoattribute:: latency
+
+    .. autoproperty:: state
+
+    The following attributes are available after the opening handshake,
+    once the WebSocket connection is open:
+
+    .. autoattribute:: request
+
+    .. autoattribute:: response
+
+    .. autoproperty:: subprotocol
+
+    The following attributes are available after the closing handshake,
+    once the WebSocket connection is closed:
+
+    .. autoproperty:: close_code
+
+    .. autoproperty:: close_reason
+
+HTTP Basic Authentication
+-------------------------
+
+websockets supports HTTP Basic Authentication according to
+:rfc:`7235` and :rfc:`7617`.
+
+.. autofunction:: basic_auth

docs/topics/keepalive.rst

@@ -136,8 +136,8 @@ measured during the last exchange of Ping and Pong frames::
 Alternatively, you can measure the latency at any time by calling
 :attr:`~asyncio.connection.Connection.ping` and awaiting its result::
 
-    pong_waiter = await websocket.ping()
-    latency = await pong_waiter
+    pong_received = await websocket.ping()
+    latency = await pong_received
 
 Latency between a client and a server may increase for two reasons:
 

example/asyncio/client.py

@@ -3,7 +3,6 @@
 """Client example using the asyncio API."""
 
 import asyncio
-
 from websockets.asyncio.client import connect
 
 

example/trio/client.py

@@ -0,0 +1,21 @@
+#!/usr/bin/env python
+
+"""Client example using the trio API."""
+
+import trio
+from websockets.trio.client import connect
+
+
+async def hello():
+    async with connect("ws://localhost:8765") as websocket:
+        name = input("What's your name? ")
+
+        await websocket.send(name)
+        print(f">>> {name}")
+
+        greeting = await websocket.recv()
+        print(f"<<< {greeting}")
+
+
+if __name__ == "__main__":
+    trio.run(hello)

example/trio/echo.py

@@ -0,0 +1,15 @@
+#!/usr/bin/env python
+
+"""Echo server using the trio API."""
+
+import trio
+from websockets.trio.server import serve
+
+
+async def echo(websocket):
+    async for message in websocket:
+        await websocket.send(message)
+
+
+if __name__ == "__main__":
+    trio.run(serve, echo, 8765)

example/trio/hello.py

@@ -0,0 +1,17 @@
+#!/usr/bin/env python
+
+"""Client using the trio API."""
+
+import trio
+from websockets.trio.client import connect
+
+
+async def hello():
+    async with connect("ws://localhost:8765") as websocket:
+        await websocket.send("Hello world!")
+        message = await websocket.recv()
+        print(message)
+
+
+if __name__ == "__main__":
+    trio.run(hello)

example/trio/server.py

@@ -0,0 +1,20 @@
+#!/usr/bin/env python
+
+"""Server example using the trio API."""
+
+import trio
+from websockets.trio.server import serve
+
+
+async def hello(websocket):
+    name = await websocket.recv()
+    print(f"<<< {name}")
+
+    greeting = f"Hello {name}!"
+
+    await websocket.send(greeting)
+    print(f">>> {greeting}")
+
+
+if __name__ == "__main__":
+    trio.run(serve, hello, 8765)