Improve documentation of exceptions.

Group and order them. Extend docstrings.

Author: aaugustin

docs/project/changelog.rst

@@ -613,7 +613,7 @@ Bug fixes
 * Aligned maximum cookie size with popular web browsers.
 
 * Ensured cancellation always propagates, even on Python versions where
-  :exc:`~asyncio.CancelledError` inherits :exc:`Exception`.
+  :exc:`~asyncio.CancelledError` inherits from :exc:`Exception`.
 
 .. _8.1:
 

docs/reference/exceptions.rst

@@ -5,16 +5,35 @@ Exceptions
 
 .. autoexception:: WebSocketException
 
+Connection closed
+-----------------
+
+:meth:`~websockets.asyncio.connection.Connection.recv`,
+:meth:`~websockets.asyncio.connection.Connection.send`, and similar methods
+raise the exceptions below when the connection is closed. This is the expected
+way to detect disconnections.
+
 .. autoexception:: ConnectionClosed
 
+.. autoexception:: ConnectionClosedOK
+
 .. autoexception:: ConnectionClosedError
 
-.. autoexception:: ConnectionClosedOK
+Connection failed
+-----------------
+
+These exceptions are raised by :func:`~websockets.asyncio.client.connect` when
+the opening handshake fails and the connection cannot be established. They are
+also reported by :func:`~websockets.asyncio.server.serve` in logs.
+
+.. autoexception:: InvalidURI
 
 .. autoexception:: InvalidHandshake
 
 .. autoexception:: SecurityError
 
+.. autoexception:: InvalidStatus
+
 .. autoexception:: InvalidHeader
 
 .. autoexception:: InvalidHeaderFormat
@@ -25,8 +44,6 @@ Exceptions
 
 .. autoexception:: InvalidUpgrade
 
-.. autoexception:: InvalidStatus
-
 .. autoexception:: NegotiationError
 
 .. autoexception:: DuplicateParameter
@@ -35,13 +52,17 @@ Exceptions
 
 .. autoexception:: InvalidParameterValue
 
-.. autoexception:: InvalidState
+Sans-I/O exceptions
+-------------------
 
-.. autoexception:: InvalidURI
+These exceptions are only raised by the Sans-I/O implementation. They are
+translated to :exc:`ConnectionClosedError` in the other implementations.
+
+.. autoexception:: ProtocolError
 
 .. autoexception:: PayloadTooBig
 
-.. autoexception:: ProtocolError
+.. autoexception:: InvalidState
 
 Legacy exceptions
 -----------------

src/websockets/exceptions.py

@@ -1,30 +1,30 @@
 """
-:mod:`websockets.exceptions` defines the following exception hierarchy:
+:mod:`websockets.exceptions` defines the following hierarchy of exceptions.
 
 * :exc:`WebSocketException`
     * :exc:`ConnectionClosed`
-        * :exc:`ConnectionClosedError`
         * :exc:`ConnectionClosedOK`
+        * :exc:`ConnectionClosedError`
+    * :exc:`InvalidURI`
     * :exc:`InvalidHandshake`
         * :exc:`SecurityError`
         * :exc:`InvalidMessage` (legacy)
+        * :exc:`InvalidStatus`
+        * :exc:`InvalidStatusCode` (legacy)
         * :exc:`InvalidHeader`
             * :exc:`InvalidHeaderFormat`
             * :exc:`InvalidHeaderValue`
             * :exc:`InvalidOrigin`
             * :exc:`InvalidUpgrade`
-        * :exc:`InvalidStatus`
-        * :exc:`InvalidStatusCode` (legacy)
         * :exc:`NegotiationError`
             * :exc:`DuplicateParameter`
             * :exc:`InvalidParameterName`
             * :exc:`InvalidParameterValue`
         * :exc:`AbortHandshake` (legacy)
         * :exc:`RedirectHandshake` (legacy)
-    * :exc:`InvalidState`
-    * :exc:`InvalidURI`
-    * :exc:`PayloadTooBig`
-    * :exc:`ProtocolError`
+    * :exc:`ProtocolError` (Sans-I/O)
+    * :exc:`PayloadTooBig` (Sans-I/O)
+    * :exc:`InvalidState` (Sans-I/O)
 
 """
 
@@ -40,29 +40,29 @@
 __all__ = [
     "WebSocketException",
     "ConnectionClosed",
-    "ConnectionClosedError",
     "ConnectionClosedOK",
+    "ConnectionClosedError",
+    "InvalidURI",
     "InvalidHandshake",
     "SecurityError",
     "InvalidMessage",
+    "InvalidStatus",
+    "InvalidStatusCode",
     "InvalidHeader",
     "InvalidHeaderFormat",
     "InvalidHeaderValue",
     "InvalidOrigin",
     "InvalidUpgrade",
-    "InvalidStatus",
-    "InvalidStatusCode",
     "NegotiationError",
     "DuplicateParameter",
     "InvalidParameterName",
     "InvalidParameterValue",
     "AbortHandshake",
     "RedirectHandshake",
-    "InvalidState",
-    "InvalidURI",
-    "PayloadTooBig",
     "ProtocolError",
     "WebSocketProtocolError",
+    "PayloadTooBig",
+    "InvalidState",
 ]
 
 
@@ -139,6 +139,16 @@ def reason(self) -> str:
         return self.rcvd.reason
 
 
+class ConnectionClosedOK(ConnectionClosed):
+    """
+    Like :exc:`ConnectionClosed`, when the connection terminated properly.
+
+    A close code with code 1000 (OK) or 1001 (going away) or without a code was
+    received and sent.
+
+    """
+
+
 class ConnectionClosedError(ConnectionClosed):
     """
     Like :exc:`ConnectionClosed`, when the connection terminated with an error.
@@ -149,19 +159,23 @@ class ConnectionClosedError(ConnectionClosed):
     """
 
 
-class ConnectionClosedOK(ConnectionClosed):
+class InvalidURI(WebSocketException):
     """
-    Like :exc:`ConnectionClosed`, when the connection terminated properly.
-
-    A close code with code 1000 (OK) or 1001 (going away) or without a code was
-    received and sent.
+    Raised when connecting to a URI that isn't a valid WebSocket URI.
 
     """
 
+    def __init__(self, uri: str, msg: str) -> None:
+        self.uri = uri
+        self.msg = msg
+
+    def __str__(self) -> str:
+        return f"{self.uri} isn't a valid URI: {self.msg}"
+
 
 class InvalidHandshake(WebSocketException):
     """
-    Raised during the handshake when the WebSocket connection fails.
+    Base class for exceptions raised when the opening handshake fails.
 
     """
 
@@ -170,10 +184,27 @@ class SecurityError(InvalidHandshake):
     """
     Raised when a handshake request or response breaks a security rule.
 
-    Security limits are hard coded.
+    Security limits can be configured with :doc:`environment variables
+    <../reference/variables>`.
+
+    """
+
+
+class InvalidStatus(InvalidHandshake):
+    """
+    Raised when a handshake response rejects the WebSocket upgrade.
 
     """
 
+    def __init__(self, response: http11.Response) -> None:
+        self.response = response
+
+    def __str__(self) -> str:
+        return (
+            "server rejected WebSocket connection: "
+            f"HTTP {self.response.status_code:d}"
+        )
+
 
 class InvalidHeader(InvalidHandshake):
     """
@@ -210,7 +241,7 @@ class InvalidHeaderValue(InvalidHeader):
     """
     Raised when an HTTP header has a wrong value.
 
-    The format of the header is correct but a value isn't acceptable.
+    The format of the header is correct but the value isn't acceptable.
 
     """
 
@@ -232,25 +263,9 @@ class InvalidUpgrade(InvalidHeader):
     """
 
 
-class InvalidStatus(InvalidHandshake):
-    """
-    Raised when a handshake response rejects the WebSocket upgrade.
-
-    """
-
-    def __init__(self, response: http11.Response) -> None:
-        self.response = response
-
-    def __str__(self) -> str:
-        return (
-            "server rejected WebSocket connection: "
-            f"HTTP {self.response.status_code:d}"
-        )
-
-
 class NegotiationError(InvalidHandshake):
     """
-    Raised when negotiating an extension fails.
+    Raised when negotiating an extension or a subprotocol fails.
 
     """
 
@@ -300,41 +315,42 @@ def __str__(self) -> str:
             return f"invalid value for parameter {self.name}: {self.value}"
 
 
-class InvalidState(WebSocketException, AssertionError):
+class ProtocolError(WebSocketException):
     """
-    Raised when an operation is forbidden in the current state.
+    Raised when receiving or sending a frame that breaks the protocol.
 
-    This exception is an implementation detail.
+    The Sans-I/O implementation raises this exception when:
 
-    It should never be raised in normal circumstances.
+    * receiving or sending a frame that contains invalid data;
+    * receiving or sending an invalid sequence of frames.
 
     """
 
 
-class InvalidURI(WebSocketException):
+class PayloadTooBig(WebSocketException):
     """
-    Raised when connecting to a URI that isn't a valid WebSocket URI.
+    Raised when parsing a frame with a payload that exceeds the maximum size.
 
-    """
-
-    def __init__(self, uri: str, msg: str) -> None:
-        self.uri = uri
-        self.msg = msg
-
-    def __str__(self) -> str:
-        return f"{self.uri} isn't a valid URI: {self.msg}"
+    The Sans-I/O layer uses this exception internally. It doesn't bubble up to
+    the I/O layer.
 
+    The :meth:`~websockets.extensions.Extension.decode` method of extensions
+    must raise :exc:`PayloadTooBig` if decoding a frame would exceed the limit.
 
-class PayloadTooBig(WebSocketException):
     """
-    Raised when receiving a frame with a payload exceeding the maximum size.
 
+
+class InvalidState(WebSocketException, AssertionError):
     """
+    Raised when sending a frame is forbidden in the current state.
 
+    Specifically, the Sans-I/O layer raises this exception when:
 
-class ProtocolError(WebSocketException):
-    """
-    Raised when a frame breaks the protocol.
+    * sending a data frame to a connection in a state other
+      :attr:`~websockets.protocol.State.OPEN`;
+    * sending a control frame to a connection in a state other than
+      :attr:`~websockets.protocol.State.OPEN` or
+      :attr:`~websockets.protocol.State.CLOSING`.
 
     """
 

tests/test_exceptions.py

@@ -79,6 +79,10 @@ def test_str(self):
                 ),
                 "no close frame received or sent",
             ),
+            (
+                InvalidURI("|", "not at all!"),
+                "| isn't a valid URI: not at all!",
+            ),
             (
                 InvalidHandshake("invalid request"),
                 "invalid request",
@@ -87,6 +91,10 @@ def test_str(self):
                 SecurityError("redirect from WSS to WS"),
                 "redirect from WSS to WS",
             ),
+            (
+                InvalidStatus(Response(401, "Unauthorized", Headers())),
+                "server rejected WebSocket connection: HTTP 401",
+            ),
             (
                 InvalidHeader("Name"),
                 "missing Name header",
@@ -123,10 +131,6 @@ def test_str(self):
                 InvalidUpgrade("Connection", "websocket"),
                 "invalid Connection header: websocket",
             ),
-            (
-                InvalidStatus(Response(401, "Unauthorized", Headers())),
-                "server rejected WebSocket connection: HTTP 401",
-            ),
             (
                 NegotiationError("unsupported subprotocol: spam"),
                 "unsupported subprotocol: spam",
@@ -152,20 +156,16 @@ def test_str(self):
                 "invalid value for parameter a: |",
             ),
             (
-                InvalidState("WebSocket connection isn't established yet"),
-                "WebSocket connection isn't established yet",
-            ),
-            (
-                InvalidURI("|", "not at all!"),
-                "| isn't a valid URI: not at all!",
+                ProtocolError("invalid opcode: 7"),
+                "invalid opcode: 7",
             ),
             (
                 PayloadTooBig("payload length exceeds limit: 2 > 1 bytes"),
                 "payload length exceeds limit: 2 > 1 bytes",
             ),
             (
-                ProtocolError("invalid opcode: 7"),
-                "invalid opcode: 7",
+                InvalidState("WebSocket connection isn't established yet"),
+                "WebSocket connection isn't established yet",
             ),
         ]:
             with self.subTest(exception=exception):