Add trio client and server.

Author: aaugustin

docs/conf.py

@@ -85,6 +85,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/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/features.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/index.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/client.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/common.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/reference/trio/server.rst

@@ -0,0 +1,25 @@
+#!/usr/bin/env python
+
+"""Client example using the trio API."""
+
+import logging
+logging.basicConfig(level=logging.DEBUG)
+
+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/client.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)