Move broadcast() to the server module.

Rationale:

* It is only useful for servers. (Maybe there's a use case for client
  but I couldn't picture it.)
* It was already documented in the page covering the server module.
* Within this page, it was the only API from the connection or protocol
  module.

The implementation remains in the connection or protocol module because
moving it would require refactoring tests. I'd rather keep them simple.
(And I'm lazy.)

This change doesn't require a backwards compatibility shim because the
documentated location of the legacy implementation of broadcast was
websockets.broadcast, it's changing with the introduction of the new
asyncio API, and the changes are already documented.

Author: aaugustin

docs/faq/server.rst

@@ -116,9 +116,9 @@ Record all connections in a global variable::
         finally:
             CONNECTIONS.remove(websocket)
 
-Then, call :func:`~websockets.asyncio.connection.broadcast`::
+Then, call :func:`~websockets.asyncio.server.broadcast`::
 
-    from websockets.asyncio.connection import broadcast
+    from websockets.asyncio.server import broadcast
 
     def message_all(message):
         broadcast(CONNECTIONS, message)

docs/howto/patterns.rst

@@ -90,7 +90,7 @@ connect and unregister them when they disconnect::
         connected.add(websocket)
         try:
             # Broadcast a message to all connected clients.
-            websockets.broadcast(connected, "Hello!")
+            broadcast(connected, "Hello!")
             await asyncio.sleep(10)
         finally:
             # Unregister.

docs/howto/upgrade.rst

@@ -162,8 +162,8 @@ Server APIs
 | ``websockets.server.WebSocketServerProtocol``                |br| |                                                     |
 | :class:`websockets.legacy.server.WebSocketServerProtocol`         |                                                     |
 +-------------------------------------------------------------------+-----------------------------------------------------+
-| ``websockets.broadcast``                                     |br| | :func:`websockets.asyncio.connection.broadcast`     |
-| :func:`websockets.legacy.protocol.broadcast()`                    |                                                     |
+| ``websockets.broadcast``                                     |br| | :func:`websockets.asyncio.server.broadcast`         |
+| :func:`websockets.legacy.server.broadcast()`                      |                                                     |
 +-------------------------------------------------------------------+-----------------------------------------------------+
 | ``websockets.BasicAuthWebSocketServerProtocol``              |br| | *not available yet*                                 |
 | ``websockets.auth.BasicAuthWebSocketServerProtocol``         |br| |                                                     |

docs/intro/tutorial2.rst

@@ -482,11 +482,11 @@ you're using this pattern:
         ...
 
 Since this is a very common pattern in WebSocket servers, websockets provides
-the :func:`~asyncio.connection.broadcast` helper for this purpose:
+the :func:`~asyncio.server.broadcast` helper for this purpose:
 
 .. code-block:: python
 
-    from websockets.asyncio.connection import broadcast
+    from websockets.asyncio.server import broadcast
 
     async def handler(websocket):
 
@@ -496,13 +496,12 @@ the :func:`~asyncio.connection.broadcast` helper for this purpose:
 
         ...
 
-Calling :func:`~asyncio.connection.broadcast` once is more efficient than
+Calling :func:`~asyncio.server.broadcast` once is more efficient than
 calling :meth:`~asyncio.server.ServerConnection.send` in a loop.
 
 However, there's a subtle difference in behavior. Did you notice that there's no
-``await`` in the second version? Indeed, :func:`~asyncio.connection.broadcast`
-is a function, not a coroutine like
-:meth:`~asyncio.server.ServerConnection.send` or
+``await`` in the second version? Indeed, :func:`~asyncio.server.broadcast` is a
+function, not a coroutine like :meth:`~asyncio.server.ServerConnection.send` or
 :meth:`~asyncio.server.ServerConnection.recv`.
 
 It's quite obvious why :meth:`~asyncio.server.ServerConnection.recv`
@@ -524,8 +523,8 @@ That said, when you're sending the same messages to many clients in a loop,
 applying backpressure in this way can become counterproductive. When you're
 broadcasting, you don't want to slow down everyone to the pace of the slowest
 clients; you want to drop clients that cannot keep up with the data stream.
-That's why :func:`~asyncio.connection.broadcast` doesn't wait until write
-buffers drain and therefore doesn't need to be a coroutine.
+That's why :func:`~asyncio.server.broadcast` doesn't wait until write buffers
+drain and therefore doesn't need to be a coroutine.
 
 For our Connect Four game, there's no difference in practice. The total amount
 of data sent on a connection for a game of Connect Four is so small that the

docs/project/changelog.rst

@@ -212,7 +212,7 @@ Improvements
 
 * Added platform-independent wheels.
 
-* Improved error handling in :func:`~legacy.protocol.broadcast`.
+* Improved error handling in :func:`~legacy.server.broadcast`.
 
 * Set ``server_hostname`` automatically on TLS connections when providing a
   ``sock`` argument to :func:`~sync.client.connect`.
@@ -402,7 +402,7 @@ New features
 
 * Added compatibility with Python 3.10.
 
-* Added :func:`~legacy.protocol.broadcast` to send a message to many clients.
+* Added :func:`~legacy.server.broadcast` to send a message to many clients.
 
 * Added support for reconnecting automatically by using
   :func:`~legacy.client.connect` as an asynchronous iterator.

docs/reference/asyncio/server.rst

@@ -80,4 +80,4 @@ Using a connection
 Broadcast
 ---------
 
-.. autofunction:: websockets.asyncio.connection.broadcast
+.. autofunction:: websockets.asyncio.server.broadcast

docs/reference/features.rst

@@ -35,6 +35,8 @@ Both sides
     +------------------------------------+--------+--------+--------+--------+
     | Send a message                     | ✅     | ✅     | ✅     | ✅     |
     +------------------------------------+--------+--------+--------+--------+
+    | Broadcast a message                | ✅     | ❌     | —      | ✅     |
+    +------------------------------------+--------+--------+--------+--------+
     | Receive a message                  | ✅     | ✅     | ✅     | ✅     |
     +------------------------------------+--------+--------+--------+--------+
     | Iterate over received messages     | ✅     | ✅     | —      | ✅     |

docs/reference/legacy/server.rst

@@ -89,6 +89,11 @@ Using a connection
     .. autoproperty:: close_reason
 
 
+Broadcast
+---------
+
+.. autofunction:: websockets.legacy.server.broadcast
+
 Basic authentication
 --------------------
 
@@ -106,8 +111,3 @@ websockets supports HTTP Basic Authentication according to
     .. autoattribute:: username
 
     .. automethod:: check_credentials
-
-Broadcast
----------
-
-.. autofunction:: websockets.legacy.protocol.broadcast

docs/topics/broadcast.rst

@@ -4,19 +4,19 @@ Broadcasting
 .. currentmodule:: websockets
 
 .. admonition:: If you want to send a message to all connected clients,
-    use :func:`~asyncio.connection.broadcast`.
+    use :func:`~asyncio.server.broadcast`.
     :class: tip
 
     If you want to learn about its design, continue reading this document.
 
     For the legacy :mod:`asyncio` implementation, use
-    :func:`~legacy.protocol.broadcast`.
+    :func:`~legacy.server.broadcast`.
 
 WebSocket servers often send the same message to all connected clients or to a
 subset of clients for which the message is relevant.
 
 Let's explore options for broadcasting a message, explain the design of
-:func:`~asyncio.connection.broadcast`, and discuss alternatives.
+:func:`~asyncio.server.broadcast`, and discuss alternatives.
 
 For each option, we'll provide a connection handler called ``handler()`` and a
 function or coroutine called ``broadcast()`` that sends a message to all
@@ -124,7 +124,7 @@ connections before the write buffer can fill up.
 
 Don't set extreme values of ``write_limit``, ``ping_interval``, or
 ``ping_timeout`` to ensure that this condition holds! Instead, set reasonable
-values and use the built-in :func:`~asyncio.connection.broadcast` function.
+values and use the built-in :func:`~asyncio.server.broadcast` function.
 
 The concurrent way
 ------------------
@@ -209,11 +209,11 @@ If a client gets too far behind, eventually it reaches the limit defined by
 ``ping_timeout`` and websockets terminates the connection. You can refer to the
 discussion of :doc:`keepalive <keepalive>` for details.
 
-How :func:`~asyncio.connection.broadcast` works
------------------------------------------------
+How :func:`~asyncio.server.broadcast` works
+-------------------------------------------
 
-The built-in :func:`~asyncio.connection.broadcast` function is similar to the
-naive way. The main difference is that it doesn't apply backpressure.
+The built-in :func:`~asyncio.server.broadcast` function is similar to the naive
+way. The main difference is that it doesn't apply backpressure.
 
 This provides the best performance by avoiding the overhead of scheduling and
 running one task per client.
@@ -324,7 +324,7 @@ the asynchronous iterator returned by ``subscribe()``.
 Performance considerations
 --------------------------
 
-The built-in :func:`~asyncio.connection.broadcast` function sends all messages
+The built-in :func:`~asyncio.server.broadcast` function sends all messages
 without yielding control to the event loop. So does the naive way when the
 network and clients are fast and reliable.
 
@@ -346,7 +346,7 @@ However, this isn't possible in general for two reasons:
 
 All other patterns discussed above yield control to the event loop once per
 client because messages are sent by different tasks. This makes them slower
-than the built-in :func:`~asyncio.connection.broadcast` function.
+than the built-in :func:`~asyncio.server.broadcast` function.
 
 There is no major difference between the performance of per-client queues and
 publish–subscribe.

docs/topics/logging.rst

@@ -221,7 +221,7 @@ Here's what websockets logs at each level.
 ``WARNING``
 ...........
 
-* Failures in :func:`~asyncio.connection.broadcast`
+* Failures in :func:`~asyncio.server.broadcast`
 
 ``INFO``
 ........

docs/topics/performance.rst

@@ -18,5 +18,5 @@ application.)
 broadcast
 ---------
 
-:func:`~asyncio.connection.broadcast` is the most efficient way to send a
-message to many clients.
+:func:`~asyncio.server.broadcast` is the most efficient way to send a message to
+many clients.

example/django/notifications.py

@@ -10,8 +10,7 @@
 
 from django.contrib.contenttypes.models import ContentType
 from sesame.utils import get_user
-from websockets.asyncio.connection import broadcast
-from websockets.asyncio.server import serve
+from websockets.asyncio.server import broadcast, serve
 from websockets.frames import CloseCode
 
 

example/quickstart/counter.py

@@ -3,8 +3,7 @@
 import asyncio
 import json
 import logging
-from websockets.asyncio.connection import broadcast
-from websockets.asyncio.server import serve
+from websockets.asyncio.server import broadcast, serve
 
 logging.basicConfig()
 

example/quickstart/show_time_2.py

@@ -4,8 +4,7 @@
 import datetime
 import random
 
-from websockets.asyncio.connection import broadcast
-from websockets.asyncio.server import serve
+from websockets.asyncio.server import broadcast, serve
 
 CONNECTIONS = set()
 

example/tutorial/step2/app.py

@@ -4,8 +4,7 @@
 import json
 import secrets
 
-from websockets.asyncio.connection import broadcast
-from websockets.asyncio.server import serve
+from websockets.asyncio.server import broadcast, serve
 
 from connect4 import PLAYER1, PLAYER2, Connect4
 

example/tutorial/step3/app.py

@@ -6,8 +6,7 @@
 import secrets
 import signal
 
-from websockets.asyncio.connection import broadcast
-from websockets.asyncio.server import serve
+from websockets.asyncio.server import broadcast, serve
 
 from connect4 import PLAYER1, PLAYER2, Connect4
 

experiments/broadcast/server.py

@@ -7,8 +7,7 @@
 import time
 
 from websockets import ConnectionClosed
-from websockets.asyncio.server import serve
-from websockets.asyncio.connection import broadcast
+from websockets.asyncio.server import broadcast, serve
 
 
 CLIENTS = set()

src/websockets/__init__.py

@@ -48,10 +48,10 @@
     "unix_connect",
     # .legacy.protocol
     "WebSocketCommonProtocol",
-    "broadcast",
     # .legacy.server
     "WebSocketServer",
     "WebSocketServerProtocol",
+    "broadcast",
     "serve",
     "unix_serve",
     # .server
@@ -102,10 +102,11 @@
         basic_auth_protocol_factory,
     )
     from .legacy.client import WebSocketClientProtocol, connect, unix_connect
-    from .legacy.protocol import WebSocketCommonProtocol, broadcast
+    from .legacy.protocol import WebSocketCommonProtocol
     from .legacy.server import (
         WebSocketServer,
         WebSocketServerProtocol,
+        broadcast,
         serve,
         unix_serve,
     )
@@ -164,10 +165,10 @@
             "unix_connect": ".legacy.client",
             # .legacy.protocol
             "WebSocketCommonProtocol": ".legacy.protocol",
-            "broadcast": ".legacy.protocol",
             # .legacy.server
             "WebSocketServer": ".legacy.server",
             "WebSocketServerProtocol": ".legacy.server",
+            "broadcast": ".legacy.server",
             "serve": ".legacy.server",
             "unix_serve": ".legacy.server",
             # .server

src/websockets/asyncio/connection.py

@@ -34,7 +34,7 @@
 from .messages import Assembler
 
 
-__all__ = ["Connection", "broadcast"]
+__all__ = ["Connection"]
 
 
 class Connection(asyncio.Protocol):
@@ -1011,6 +1011,12 @@ def eof_received(self) -> None:
         # Besides, that doesn't work on TLS connections.
 
 
+# broadcast() is defined in the connection module even though it's primarily
+# used by servers and documented in the server module because it works with
+# client connections too and because it's easier to test together with the
+# Connection class.
+
+
 def broadcast(
     connections: Iterable[Connection],
     message: Data,
@@ -1034,10 +1040,11 @@ def broadcast(
     ``ping_interval`` and ``ping_timeout`` low to prevent excessive memory usage
     from slow connections.
 
-    Unlike :meth:`~Connection.send`, :func:`broadcast` doesn't support sending
-    fragmented messages. Indeed, fragmentation is useful for sending large
-    messages without buffering them in memory, while :func:`broadcast` buffers
-    one copy per connection as fast as possible.
+    Unlike :meth:`~websockets.asyncio.connection.Connection.send`,
+    :func:`broadcast` doesn't support sending fragmented messages. Indeed,
+    fragmentation is useful for sending large messages without buffering them in
+    memory, while :func:`broadcast` buffers one copy per connection as fast as
+    possible.
 
     :func:`broadcast` skips connections that aren't open in order to avoid
     errors on connections where the closing handshake is in progress.
@@ -1047,6 +1054,10 @@ def broadcast(
     set ``raise_exceptions`` to :obj:`True` to record failures and raise all
     exceptions in a :pep:`654` :exc:`ExceptionGroup`.
 
+    While :func:`broadcast` makes more sense for servers, it works identically
+    with clients, if you have a use case for opening connections to many servers
+    and broadcasting a message to them.
+
     Args:
         websockets: WebSocket connections to which the message will be sent.
         message: Message to send.
@@ -1101,3 +1112,7 @@ def broadcast(
 
     if raise_exceptions and exceptions:
         raise ExceptionGroup("skipped broadcast", exceptions)
+
+
+# Pretend that broadcast is actually defined in the server module.
+broadcast.__module__ = "websockets.asyncio.server"

src/websockets/asyncio/server.py

@@ -25,10 +25,10 @@
 from ..server import ServerProtocol
 from ..typing import LoggerLike, Origin, StatusLike, Subprotocol
 from .compatibility import asyncio_timeout
-from .connection import Connection
+from .connection import Connection, broadcast
 
 
-__all__ = ["serve", "unix_serve", "ServerConnection", "WebSocketServer"]
+__all__ = ["broadcast", "serve", "unix_serve", "ServerConnection", "WebSocketServer"]
 
 
 class ServerConnection(Connection):