Document legacy implementation in websockets.legacy.

Until now it was documented directly in the websockets package.

Also update most examples to use the new asyncio implementation.

Some drive-by documentation improvements too.

Author: aaugustin

compliance/test_client.py

@@ -1,9 +1,9 @@
+import asyncio
 import json
 import logging
 import urllib.parse
 
-import asyncio
-import websockets
+from websockets.asyncio.client import connect
 
 
 logging.basicConfig(level=logging.WARNING)
@@ -18,21 +18,21 @@
 
 async def get_case_count(server):
     uri = f"{server}/getCaseCount"
-    async with websockets.connect(uri) as ws:
+    async with connect(uri) as ws:
         msg = ws.recv()
     return json.loads(msg)
 
 
 async def run_case(server, case, agent):
     uri = f"{server}/runCase?case={case}&agent={agent}"
-    async with websockets.connect(uri, max_size=2 ** 25, max_queue=1) as ws:
+    async with connect(uri, max_size=2 ** 25, max_queue=1) as ws:
         async for msg in ws:
             await ws.send(msg)
 
 
 async def update_reports(server, agent):
     uri = f"{server}/updateReports?agent={agent}"
-    async with websockets.connect(uri):
+    async with connect(uri):
         pass
 
 

compliance/test_server.py

@@ -1,7 +1,7 @@
+import asyncio
 import logging
 
-import asyncio
-import websockets
+from websockets.asyncio.server import serve
 
 
 logging.basicConfig(level=logging.WARNING)
@@ -19,7 +19,7 @@ async def echo(ws):
 
 
 async def main():
-    with websockets.serve(echo, HOST, PORT, max_size=2 ** 25, max_queue=1):
+    with serve(echo, HOST, PORT, max_size=2 ** 25, max_queue=1):
         try:
             await asyncio.get_running_loop().create_future()  # run forever
         except KeyboardInterrupt:

docs/conf.py

@@ -36,20 +36,20 @@
     # topics/design.rst discusses undocumented APIs
     ("py:meth", "client.WebSocketClientProtocol.handshake"),
     ("py:meth", "server.WebSocketServerProtocol.handshake"),
-    ("py:attr", "legacy.protocol.WebSocketCommonProtocol.is_client"),
-    ("py:attr", "legacy.protocol.WebSocketCommonProtocol.messages"),
-    ("py:meth", "legacy.protocol.WebSocketCommonProtocol.close_connection"),
-    ("py:attr", "legacy.protocol.WebSocketCommonProtocol.close_connection_task"),
-    ("py:meth", "legacy.protocol.WebSocketCommonProtocol.keepalive_ping"),
-    ("py:attr", "legacy.protocol.WebSocketCommonProtocol.keepalive_ping_task"),
-    ("py:meth", "legacy.protocol.WebSocketCommonProtocol.transfer_data"),
-    ("py:attr", "legacy.protocol.WebSocketCommonProtocol.transfer_data_task"),
-    ("py:meth", "legacy.protocol.WebSocketCommonProtocol.connection_open"),
-    ("py:meth", "legacy.protocol.WebSocketCommonProtocol.ensure_open"),
-    ("py:meth", "legacy.protocol.WebSocketCommonProtocol.fail_connection"),
-    ("py:meth", "legacy.protocol.WebSocketCommonProtocol.connection_lost"),
-    ("py:meth", "legacy.protocol.WebSocketCommonProtocol.read_message"),
-    ("py:meth", "legacy.protocol.WebSocketCommonProtocol.write_frame"),
+    ("py:attr", "protocol.WebSocketCommonProtocol.is_client"),
+    ("py:attr", "protocol.WebSocketCommonProtocol.messages"),
+    ("py:meth", "protocol.WebSocketCommonProtocol.close_connection"),
+    ("py:attr", "protocol.WebSocketCommonProtocol.close_connection_task"),
+    ("py:meth", "protocol.WebSocketCommonProtocol.keepalive_ping"),
+    ("py:attr", "protocol.WebSocketCommonProtocol.keepalive_ping_task"),
+    ("py:meth", "protocol.WebSocketCommonProtocol.transfer_data"),
+    ("py:attr", "protocol.WebSocketCommonProtocol.transfer_data_task"),
+    ("py:meth", "protocol.WebSocketCommonProtocol.connection_open"),
+    ("py:meth", "protocol.WebSocketCommonProtocol.ensure_open"),
+    ("py:meth", "protocol.WebSocketCommonProtocol.fail_connection"),
+    ("py:meth", "protocol.WebSocketCommonProtocol.connection_lost"),
+    ("py:meth", "protocol.WebSocketCommonProtocol.read_message"),
+    ("py:meth", "protocol.WebSocketCommonProtocol.write_frame"),
 ]
 
 # Add any Sphinx extension module names here, as strings. They can be

docs/faq/asyncio.rst

@@ -1,16 +1,21 @@
 Using asyncio
 =============
 
-.. currentmodule:: websockets
+.. currentmodule:: websockets.asyncio.connection
+
+.. admonition:: This FAQ is written for the new :mod:`asyncio` implementation.
+    :class: hint
+
+    Answers are also valid for the legacy :mod:`asyncio` implementation.
 
 How do I run two coroutines in parallel?
 ----------------------------------------
 
 You must start two tasks, which the event loop will run concurrently. You can
 achieve this with :func:`asyncio.gather` or :func:`asyncio.create_task`.
 
-Keep track of the tasks and make sure they terminate or you cancel them when
-the connection terminates.
+Keep track of the tasks and make sure that they terminate or that you cancel
+them when the connection terminates.
 
 Why does my program never receive any messages?
 -----------------------------------------------
@@ -22,13 +27,12 @@ Putting an ``await`` statement in a ``for`` or a ``while`` loop isn't enough
 to yield control. Awaiting a coroutine may yield control, but there's no
 guarantee that it will.
 
-For example, :meth:`~legacy.protocol.WebSocketCommonProtocol.send` only yields
-control when send buffers are full, which never happens in most practical
-cases.
+For example, :meth:`~Connection.send` only yields control when send buffers are
+full, which never happens in most practical cases.
 
-If you run a loop that contains only synchronous operations and
-a :meth:`~legacy.protocol.WebSocketCommonProtocol.send` call, you must yield
-control explicitly with :func:`asyncio.sleep`::
+If you run a loop that contains only synchronous operations and a
+:meth:`~Connection.send` call, you must yield control explicitly with
+:func:`asyncio.sleep`::
 
     async def producer(websocket):
         message = generate_next_message()
@@ -46,24 +50,26 @@ See `issue 867`_.
 Why am I having problems with threads?
 --------------------------------------
 
-If you choose websockets' default implementation based on :mod:`asyncio`, then
-you shouldn't use threads. Indeed, choosing :mod:`asyncio` to handle concurrency
-is mutually exclusive with :mod:`threading`.
+If you choose websockets' :mod:`asyncio` implementation, then you shouldn't use
+threads. Indeed, choosing :mod:`asyncio` to handle concurrency is mutually
+exclusive with :mod:`threading`.
 
 If you believe that you need to run websockets in a thread and some logic in
 another thread, you should run that logic in a :class:`~asyncio.Task` instead.
-If it blocks the event loop, :meth:`~asyncio.loop.run_in_executor` will help.
 
-This question is really about :mod:`asyncio`. Please review the advice about
-:ref:`asyncio-multithreading` in the Python documentation.
+If it has to run in another thread because it would block the event loop,
+:func:`~asyncio.to_thread` or :meth:`~asyncio.loop.run_in_executor` is the way
+to go.
+
+Please review the advice about :ref:`asyncio-multithreading` in the Python
+documentation.
 
 Why does my simple program misbehave mysteriously?
 --------------------------------------------------
 
 You are using :func:`time.sleep` instead of :func:`asyncio.sleep`, which
 blocks the event loop and prevents asyncio from operating normally.
 
-This may lead to messages getting send but not received, to connection
-timeouts, and to unexpected results of shotgun debugging e.g. adding an
-unnecessary call to :meth:`~legacy.protocol.WebSocketCommonProtocol.send`
-makes the program functional.
+This may lead to messages getting send but not received, to connection timeouts,
+and to unexpected results of shotgun debugging e.g. adding an unnecessary call
+to a coroutine makes the program functional.

docs/faq/client.rst

@@ -1,7 +1,16 @@
 Client
 ======
 
-.. currentmodule:: websockets
+.. currentmodule:: websockets.asyncio.client
+
+.. admonition:: This FAQ is written for the new :mod:`asyncio` implementation.
+    :class: hint
+
+    Answers are also valid for the legacy :mod:`asyncio` implementation.
+
+    They translate to the :mod:`threading` implementation by removing ``await``
+    and ``async`` keywords and by using a :class:`~threading.Thread` instead of
+    a :class:`~asyncio.Task` for concurrent execution.
 
 Why does the client close the connection prematurely?
 -----------------------------------------------------
@@ -22,46 +31,47 @@ change it to::
 How do I access HTTP headers?
 -----------------------------
 
-Once the connection is established, HTTP headers are available in
-:attr:`~client.WebSocketClientProtocol.request_headers` and
-:attr:`~client.WebSocketClientProtocol.response_headers`.
+Once the connection is established, HTTP headers are available in the
+:attr:`~ClientConnection.request` and :attr:`~ClientConnection.response`
+objects::
+
+    async with connect(...) as websocket:
+        websocket.request.headers
+        websocket.response.headers
 
 How do I set HTTP headers?
 --------------------------
 
 To set the ``Origin``, ``Sec-WebSocket-Extensions``, or
 ``Sec-WebSocket-Protocol`` headers in the WebSocket handshake request, use the
-``origin``, ``extensions``, or ``subprotocols`` arguments of
-:func:`~client.connect`.
+``origin``, ``extensions``, or ``subprotocols`` arguments of :func:`~connect`.
 
 To override the ``User-Agent`` header, use the ``user_agent_header`` argument.
 Set it to :obj:`None` to remove the header.
 
 To set other HTTP headers, for example the ``Authorization`` header, use the
-``extra_headers`` argument::
+``additional_headers`` argument::
 
-    async with connect(..., extra_headers={"Authorization": ...}) as websocket:
+    async with connect(..., additional_headers={"Authorization": ...}) as websocket:
         ...
 
-In the :mod:`threading` API, this argument is named ``additional_headers``::
-
-    with connect(..., additional_headers={"Authorization": ...}) as websocket:
-        ...
+In the legacy :mod:`asyncio` API, this argument is named ``extra_headers``.
 
 How do I force the IP address that the client connects to?
 ----------------------------------------------------------
 
-Use the ``host`` argument of :meth:`~asyncio.loop.create_connection`::
+Use the ``host`` argument :func:`~connect`::
 
-    await websockets.connect("ws://example.com", host="192.168.0.1")
+    async with connect(..., host="192.168.0.1") as websocket:
+        ...
 
-:func:`~client.connect` accepts the same arguments as
-:meth:`~asyncio.loop.create_connection`.
+:func:`~connect` accepts the same arguments as
+:meth:`~asyncio.loop.create_connection` and passes them through.
 
 How do I close a connection?
 ----------------------------
 
-The easiest is to use :func:`~client.connect` as a context manager::
+The easiest is to use :func:`~connect` as a context manager::
 
     async with connect(...) as websocket:
         ...
@@ -71,9 +81,17 @@ The connection is closed when exiting the context manager.
 How do I reconnect when the connection drops?
 ---------------------------------------------
 
-Use :func:`~client.connect` as an asynchronous iterator::
+.. admonition:: This feature is only supported by the legacy :mod:`asyncio`
+    implementation.
+    :class: warning
+
+    It will be added to the new :mod:`asyncio` implementation soon.
+
+Use :func:`~websockets.legacy.client.connect` as an asynchronous iterator::
+
+    from websockets.legacy.client import connect
 
-    async for websocket in websockets.connect(...):
+    async for websocket in connect(...):
         try:
             ...
         except websockets.ConnectionClosed:
@@ -90,12 +108,12 @@ You can close the connection.
 Here's an example that terminates cleanly when it receives SIGTERM on Unix:
 
 .. literalinclude:: ../../example/faq/shutdown_client.py
-    :emphasize-lines: 10-13
+    :emphasize-lines: 11-13
 
 How do I disable TLS/SSL certificate verification?
 --------------------------------------------------
 
 Look at the ``ssl`` argument of :meth:`~asyncio.loop.create_connection`.
 
-:func:`~client.connect` accepts the same arguments as
-:meth:`~asyncio.loop.create_connection`.
+:func:`~connect` accepts the same arguments as
+:meth:`~asyncio.loop.create_connection` and passes them through.