Rename WebSocketServer to Server.

The shorter name is better. Representation remains unambiguous:

<websockets.asyncio.server.Server object at 0x...>

The change isn't applied to the legacy implementation because
it has longer names for other API too.

Author: aaugustin

docs/faq/server.rst

@@ -313,8 +313,7 @@ Here's an example that terminates cleanly when it receives SIGTERM on Unix:
 How do I stop a server while keeping existing connections open?
 ---------------------------------------------------------------
 
-Call the server's :meth:`~WebSocketServer.close` method with
-``close_connections=False``.
+Call the server's :meth:`~Server.close` method with ``close_connections=False``.
 
 Here's how to adapt the example just above::
 

docs/howto/upgrade.rst

@@ -154,7 +154,7 @@ Server APIs
 | ``websockets.server.unix_serve()``                           |br| |                                                     |
 | :func:`websockets.legacy.server.unix_serve`                       |                                                     |
 +-------------------------------------------------------------------+-----------------------------------------------------+
-| ``websockets.WebSocketServer``                               |br| | :class:`websockets.asyncio.server.WebSocketServer`  |
+| ``websockets.WebSocketServer``                               |br| | :class:`websockets.asyncio.server.Server`           |
 | ``websockets.server.WebSocketServer``                        |br| |                                                     |
 | :class:`websockets.legacy.server.WebSocketServer`                 |                                                     |
 +-------------------------------------------------------------------+-----------------------------------------------------+

docs/project/changelog.rst

@@ -35,16 +35,6 @@ notice.
 Backwards-incompatible changes
 ..............................
 
-.. admonition:: The ``ssl_context`` argument of :func:`~sync.client.connect`
-    and :func:`~sync.server.serve` in the :mod:`threading` implementation is
-    renamed to ``ssl``.
-    :class: note
-
-    This aligns the API of the :mod:`threading` implementation with the
-    :mod:`asyncio` implementation.
-
-    For backwards compatibility, ``ssl_context`` is still supported.
-
 .. admonition:: Receiving the request path in the second parameter of connection
     handlers is deprecated.
     :class: note
@@ -60,6 +50,26 @@ Backwards-incompatible changes
             path = request.path  # only if handler() uses the path argument
             ...
 
+.. admonition:: The ``ssl_context`` argument of :func:`~sync.client.connect`
+    and :func:`~sync.server.serve` in the :mod:`threading` implementation is
+    renamed to ``ssl``.
+    :class: note
+
+    This aligns the API of the :mod:`threading` implementation with the
+    :mod:`asyncio` implementation.
+
+    For backwards compatibility, ``ssl_context`` is still supported.
+
+.. admonition:: The ``WebSocketServer`` class in the :mod:`threading`
+    implementation is renamed to :class:`~sync.server.Server`.
+    :class: note
+
+    This class isn't designed to be imported or instantiated directly.
+    :func:`~sync.server.serve` returns an instance. For this reason,
+    the change should be transparent.
+
+    Regardless, an alias provides backwards compatibility.
+
 New features
 ............
 

docs/reference/asyncio/server.rst

@@ -15,7 +15,7 @@ Creating a server
 Running a server
 ----------------
 
-.. autoclass:: WebSocketServer
+.. autoclass:: Server
 
     .. automethod:: close
 

docs/reference/sync/server.rst

@@ -13,7 +13,7 @@ Creating a server
 Running a server
 ----------------
 
-.. autoclass:: WebSocketServer
+.. autoclass:: Server
 
     .. automethod:: serve_forever
 

src/websockets/asyncio/server.py

@@ -28,7 +28,7 @@
 from .connection import Connection, broadcast
 
 
-__all__ = ["broadcast", "serve", "unix_serve", "ServerConnection", "WebSocketServer"]
+__all__ = ["broadcast", "serve", "unix_serve", "ServerConnection", "Server"]
 
 
 class ServerConnection(Connection):
@@ -60,7 +60,7 @@ class ServerConnection(Connection):
     def __init__(
         self,
         protocol: ServerProtocol,
-        server: WebSocketServer,
+        server: Server,
         *,
         ping_interval: float | None = 20,
         ping_timeout: float | None = 20,
@@ -223,11 +223,11 @@ def connection_lost(self, exc: Exception | None) -> None:
                 self.request_rcvd.set_result(None)
 
 
-class WebSocketServer:
+class Server:
     """
     WebSocket server returned by :func:`serve`.
 
-    This class mirrors the API of :class:`~asyncio.Server`.
+    This class mirrors the API of :class:`asyncio.Server`.
 
     It keeps track of WebSocket connections in order to close them properly
     when shutting down.
@@ -299,16 +299,16 @@ def __init__(
 
     def wrap(self, server: asyncio.Server) -> None:
         """
-        Attach to a given :class:`~asyncio.Server`.
+        Attach to a given :class:`asyncio.Server`.
 
         Since :meth:`~asyncio.loop.create_server` doesn't support injecting a
         custom ``Server`` class, the easiest solution that doesn't rely on
         private :mod:`asyncio` APIs is to:
 
-        - instantiate a :class:`WebSocketServer`
+        - instantiate a :class:`Server`
         - give the protocol factory a reference to that instance
         - call :meth:`~asyncio.loop.create_server` with the factory
-        - attach the resulting :class:`~asyncio.Server` with this method
+        - attach the resulting :class:`asyncio.Server` with this method
 
         """
         self.server = server
@@ -378,7 +378,7 @@ def close(self, close_connections: bool = True) -> None:
         """
         Close the server.
 
-        * Close the underlying :class:`~asyncio.Server`.
+        * Close the underlying :class:`asyncio.Server`.
         * When ``close_connections`` is :obj:`True`, which is the default,
           close existing connections. Specifically:
 
@@ -402,7 +402,7 @@ async def _close(self, close_connections: bool) -> None:
         Implementation of :meth:`close`.
 
         This calls :meth:`~asyncio.Server.close` on the underlying
-        :class:`~asyncio.Server` object to stop accepting new connections and
+        :class:`asyncio.Server` object to stop accepting new connections and
         then closes open connections with close code 1001.
 
         """
@@ -516,7 +516,7 @@ def sockets(self) -> Iterable[socket.socket]:
         """
         return self.server.sockets
 
-    async def __aenter__(self) -> WebSocketServer:  # pragma: no cover
+    async def __aenter__(self) -> Server:  # pragma: no cover
         return self
 
     async def __aexit__(
@@ -543,8 +543,8 @@ class serve:
     Once the handler completes, either normally or with an exception, the server
     performs the closing handshake and closes the connection.
 
-    This coroutine returns a :class:`WebSocketServer` whose API mirrors
-    :class:`~asyncio.Server`. Treat it as an asynchronous context manager to
+    This coroutine returns a :class:`Server` whose API mirrors
+    :class:`asyncio.Server`. Treat it as an asynchronous context manager to
     ensure that the server will be closed::
 
         def handler(websocket):
@@ -556,8 +556,8 @@ def handler(websocket):
         async with websockets.asyncio.server.serve(handler, host, port):
             await stop
 
-    Alternatively, call :meth:`~WebSocketServer.serve_forever` to serve requests
-    and cancel it to stop the server::
+    Alternatively, call :meth:`~Server.serve_forever` to serve requests and
+    cancel it to stop the server::
 
         server = await websockets.asyncio.server.serve(handler, host, port)
         await server.serve_forever()
@@ -638,8 +638,8 @@ def handler(websocket):
       socket and customize it.
 
     * You can set ``start_serving`` to ``False`` to start accepting connections
-      only after you call :meth:`~WebSocketServer.start_serving()` or
-      :meth:`~WebSocketServer.serve_forever()`.
+      only after you call :meth:`~Server.start_serving()` or
+      :meth:`~Server.serve_forever()`.
 
     """
 
@@ -704,7 +704,7 @@ def __init__(
         if create_connection is None:
             create_connection = ServerConnection
 
-        self.server = WebSocketServer(
+        self.server = Server(
             handler,
             process_request=process_request,
             process_response=process_response,
@@ -773,7 +773,7 @@ def protocol_select_subprotocol(
 
     # async with serve(...) as ...: ...
 
-    async def __aenter__(self) -> WebSocketServer:
+    async def __aenter__(self) -> Server:
         return await self
 
     async def __aexit__(
@@ -787,11 +787,11 @@ async def __aexit__(
 
     # ... = await serve(...)
 
-    def __await__(self) -> Generator[Any, None, WebSocketServer]:
+    def __await__(self) -> Generator[Any, None, Server]:
         # Create a suitable iterator by calling __await__ on a coroutine.
         return self.__await_impl__().__await__()
 
-    async def __await_impl__(self) -> WebSocketServer:
+    async def __await_impl__(self) -> Server:
         server = await self._create_server
         self.server.wrap(server)
         return self.server
@@ -805,7 +805,7 @@ def unix_serve(
     handler: Callable[[ServerConnection], Awaitable[None]],
     path: str | None = None,
     **kwargs: Any,
-) -> Awaitable[WebSocketServer]:
+) -> Awaitable[Server]:
     """
     Create a WebSocket server listening on a Unix socket.
 

src/websockets/sync/server.py

@@ -24,7 +24,7 @@
 from .utils import Deadline
 
 
-__all__ = ["serve", "unix_serve", "ServerConnection", "WebSocketServer"]
+__all__ = ["serve", "unix_serve", "ServerConnection", "Server"]
 
 
 class ServerConnection(Connection):
@@ -196,7 +196,7 @@ def recv_events(self) -> None:
             self.request_rcvd.set()
 
 
-class WebSocketServer:
+class Server:
     """
     WebSocket server returned by :func:`serve`.
 
@@ -283,7 +283,7 @@ def fileno(self) -> int:
         """
         return self.socket.fileno()
 
-    def __enter__(self) -> WebSocketServer:
+    def __enter__(self) -> Server:
         return self
 
     def __exit__(
@@ -295,6 +295,16 @@ def __exit__(
         self.shutdown()
 
 
+def __getattr__(name: str) -> Any:
+    if name == "WebSocketServer":
+        warnings.warn(
+            "WebSocketServer was renamed to Server",
+            DeprecationWarning,
+        )
+        return Server
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
 def serve(
     handler: Callable[[ServerConnection], None],
     host: str | None = None,
@@ -340,7 +350,7 @@ def serve(
     # Escape hatch for advanced customization
     create_connection: type[ServerConnection] | None = None,
     **kwargs: Any,
-) -> WebSocketServer:
+) -> Server:
     """
     Create a WebSocket server listening on ``host`` and ``port``.
 
@@ -353,10 +363,10 @@ def serve(
     Once the handler completes, either normally or with an exception, the server
     performs the closing handshake and closes the connection.
 
-    This function returns a :class:`WebSocketServer` whose API mirrors
+    This function returns a :class:`Server` whose API mirrors
     :class:`~socketserver.BaseServer`. Treat it as a context manager to ensure
-    that it will be closed and call :meth:`~WebSocketServer.serve_forever` to
-    serve requests::
+    that it will be closed and call :meth:`~Server.serve_forever` to serve
+    requests::
 
         def handler(websocket):
             ...
@@ -552,14 +562,14 @@ def protocol_select_subprotocol(
 
     # Initialize server
 
-    return WebSocketServer(sock, conn_handler, logger)
+    return Server(sock, conn_handler, logger)
 
 
 def unix_serve(
     handler: Callable[[ServerConnection], None],
     path: str | None = None,
     **kwargs: Any,
-) -> WebSocketServer:
+) -> Server:
     """
     Create a WebSocket server listening on a Unix socket.
 

tests/asyncio/client.py

@@ -1,7 +1,7 @@
 import contextlib
 
 from websockets.asyncio.client import *
-from websockets.asyncio.server import WebSocketServer
+from websockets.asyncio.server import Server
 
 from .server import get_server_host_port
 
@@ -17,7 +17,7 @@ async def run_client(wsuri_or_server, secure=None, resource_name="/", **kwargs):
     if isinstance(wsuri_or_server, str):
         wsuri = wsuri_or_server
     else:
-        assert isinstance(wsuri_or_server, WebSocketServer)
+        assert isinstance(wsuri_or_server, Server)
         if secure is None:
             secure = "ssl" in kwargs
         protocol = "wss" if secure else "ws"

tests/asyncio/test_server.py

@@ -535,7 +535,7 @@ async def test_unsupported_compression(self):
 
 class WebSocketServerTests(unittest.IsolatedAsyncioTestCase):
     async def test_logger(self):
-        """WebSocketServer accepts a logger argument."""
+        """Server accepts a logger argument."""
         logger = logging.getLogger("test")
         async with run_server(logger=logger) as server:
             self.assertIs(server.logger, logger)

tests/sync/client.py

@@ -1,7 +1,7 @@
 import contextlib
 
 from websockets.sync.client import *
-from websockets.sync.server import WebSocketServer
+from websockets.sync.server import Server
 
 
 __all__ = [
@@ -15,7 +15,7 @@ def run_client(wsuri_or_server, secure=None, resource_name="/", **kwargs):
     if isinstance(wsuri_or_server, str):
         wsuri = wsuri_or_server
     else:
-        assert isinstance(wsuri_or_server, WebSocketServer)
+        assert isinstance(wsuri_or_server, Server)
         if secure is None:
             # Backwards compatibility: ssl used to be called ssl_context.
             secure = "ssl" in kwargs or "ssl_context" in kwargs

tests/sync/test_server.py

@@ -383,18 +383,18 @@ def test_unsupported_compression(self):
 
 class WebSocketServerTests(unittest.TestCase):
     def test_logger(self):
-        """WebSocketServer accepts a logger argument."""
+        """Server accepts a logger argument."""
         logger = logging.getLogger("test")
         with run_server(logger=logger) as server:
             self.assertIs(server.logger, logger)
 
     def test_fileno(self):
-        """WebSocketServer provides a fileno attribute."""
+        """Server provides a fileno attribute."""
         with run_server() as server:
             self.assertIsInstance(server.fileno(), int)
 
     def test_shutdown(self):
-        """WebSocketServer provides a shutdown method."""
+        """Server provides a shutdown method."""
         with run_server() as server:
             server.shutdown()
             # Check that the server socket is closed.
@@ -409,3 +409,8 @@ def test_ssl_context_argument(self):
             with run_server(ssl_context=SERVER_CONTEXT) as server:
                 with run_client(server, ssl=CLIENT_CONTEXT):
                     pass
+
+    def test_web_socket_server_class(self):
+        with self.assertDeprecationWarning("WebSocketServer was renamed to Server"):
+            from websockets.sync.server import WebSocketServer
+        self.assertIs(WebSocketServer, Server)