Add trio implementation - step 3

docs/conf.py

@@ -90,6 +90,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/faq/index.rst

@@ -20,6 +20,6 @@ Frequently asked questions
 
     server
     client
-    common
+    connection
     asyncio
     misc

docs/index.rst

@@ -61,6 +61,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:
 
@@ -70,6 +74,10 @@ 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

@@ -74,6 +74,14 @@ Backwards-incompatible changes
 New features
 ............
 
+.. admonition:: websockets 17.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.15.
 
 * Added :func:`~sync.server.broadcast` to the :mod:`threading` implementation.

docs/reference/asyncio/server.rst

@@ -53,6 +53,8 @@ Using a connection
 
 .. autoclass:: ServerConnection
 
+    .. automethod:: respond
+
     .. automethod:: __aiter__
 
     .. automethod:: recv
@@ -69,8 +71,6 @@ Using a connection
 
     .. automethod:: pong
 
-    .. automethod:: respond
-
     WebSocket connection objects also provide these attributes:
 
     .. autoattribute:: id

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/sync/server.rst

@@ -41,6 +41,8 @@ Using a connection
 
 .. autoclass:: ServerConnection
 
+    .. automethod:: respond
+
     .. automethod:: __iter__
 
     .. automethod:: recv
@@ -55,8 +57,6 @@ Using a connection
 
     .. automethod:: pong
 
-    .. automethod:: respond
-
     WebSocket connection objects also provide these attributes:
 
     .. autoattribute:: id

docs/reference/trio/client.rst

@@ -0,0 +1,72 @@
+Client (:mod:`trio`)
+=======================
+
+.. admonition:: The :mod:`trio` API is experimental.
+    :class: caution
+
+    Please provide feedback in GitHub issues about the API, especially if you
+    can propose a more intuitive or convenient way to connect to a server.
+
+.. 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:: 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/connection.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,97 @@
+Server (:mod:`trio`)
+=======================
+
+.. admonition:: The :mod:`trio` API is experimental.
+    :class: caution
+
+    Please provide feedback in GitHub issues about the API, especially if you
+    can propose a more intuitive or convenient way to start and stop a server.
+
+.. automodule:: websockets.trio.server
+
+Creating a server
+-----------------
+
+.. autofunction:: serve
+    :async:
+
+.. admonition:: ``unix_serve`` is not available in the Trio implementation.
+    :class: note
+
+    This is because Trio `does not provide`_ ``open_unix_listeners`` yet.
+    Instead, you can create Trio listeners using Unix domain sockets then
+    call :func:`serve` with a ``listeners`` arguments.
+
+    .. _does not provide: https://github.com/python-trio/trio/issues/279
+
+Running a server
+----------------
+
+.. autoclass:: Server
+
+    .. autoattribute:: connections
+
+    .. automethod:: aclose
+
+    .. autoattribute:: listeners
+
+Using a connection
+------------------
+
+.. autoclass:: ServerConnection
+
+    .. automethod:: respond
+
+    .. 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
+
+HTTP Basic Authentication
+-------------------------
+
+websockets supports HTTP Basic Authentication according to
+:rfc:`7235` and :rfc:`7617`.
+
+.. autofunction:: basic_auth

docs/spelling_wordlist.txt

@@ -47,6 +47,7 @@ lifecycle
 linkerd
 liveness
 lookups
+macOS
 MiB
 middleware
 mutex

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)