[WIP] Add trio client and server.

Author: aaugustin

Makefile

@@ -18,9 +18,8 @@ tests:
 	python -m unittest
 
 coverage:
-	coverage run --source src/websockets,tests -m unittest
+	coverage run --source src/websockets,tests -m unittest tests/trio/test_client.py
 	coverage html
-	coverage report --show-missing --fail-under=100
 
 maxi_cov:
 	python tests/maxi_cov.py

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/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,66 @@
+Client (:mod:`trio`)
+=======================
+
+.. automodule:: websockets.trio.client
+
+.. Opening a connection
+.. --------------------
+
+.. .. autofunction:: connect
+..     :async:
+
+.. .. autofunction:: unix_connect
+..     :async:
+
+.. .. autofunction:: process_exception
+
+.. 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
+
+..     .. 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,58 @@
+:orphan:
+
+Both sides (:mod:`trio`)
+===========================
+
+.. automodule:: websockets.trio.connection
+
+.. autoclass:: Connection
+
+    .. automethod:: __aiter__
+
+    .. automethod:: recv
+
+    .. automethod:: receive
+
+    .. automethod:: recv_streaming
+
+    .. automethod:: send
+
+    .. automethod:: close
+
+    .. 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,110 @@
+Server (:mod:`trio`)
+=======================
+
+.. automodule:: websockets.trio.server
+
+.. Creating a server
+.. -----------------
+
+.. .. autofunction:: serve
+..     :async:
+
+.. .. autofunction:: unix_serve
+..     :async:
+
+.. Routing connections
+.. -------------------
+
+.. .. automodule:: websockets.trio.router
+
+.. .. autofunction:: route
+..     :async:
+
+.. .. autofunction:: unix_route
+..     :async:
+
+.. .. autoclass:: Router
+
+.. .. currentmodule:: websockets.trio.server
+
+.. Running a server
+.. ----------------
+
+.. .. autoclass:: Server
+
+..     .. autoattribute:: connections
+
+..     .. 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
+
+..     .. 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,22 @@
+#!/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/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)