Move process_exception to the Sans-I/O layer.

Even though it has to do with I/O, it's mutualized between all
implementations, and it doesn't matter very much where it lives.

Author: aaugustin

docs/howto/upgrade.rst

@@ -161,7 +161,7 @@ network errors and server errors (HTTP 500, 502, 503, or 504) are considered
 retryable. You can customize this behavior with the ``process_exception``
 argument of :func:`~asyncio.client.connect`.
 
-See :func:`~asyncio.client.process_exception` for more information.
+See :func:`~client.process_exception` for more information.
 
 Here's how to revert to the behavior of the original implementation::
 

docs/reference/asyncio/client.rst

@@ -10,8 +10,6 @@ Opening a connection
 
 .. autofunction:: unix_connect
 
-.. autofunction:: process_exception
-
 Using a connection
 ------------------
 

docs/reference/sansio/client.rst

@@ -56,3 +56,5 @@ Client (`Sans-I/O`_)
     .. autoproperty:: close_reason
 
     .. autoproperty:: close_exc
+
+.. autofunction:: process_exception

docs/reference/sync/client.rst

@@ -14,8 +14,6 @@ Opening a connection
 
 .. autofunction:: unix_reconnect
 
-.. autofunction:: process_exception
-
 Using a connection
 ------------------
 

docs/reference/trio/client.rst

@@ -16,8 +16,6 @@ Opening a connection
 
 .. autofunction:: unix_connect
 
-.. autofunction:: process_exception
-
 Using a connection
 ------------------
 

src/websockets/asyncio/client.py

@@ -11,10 +11,9 @@
 from types import TracebackType
 from typing import Any, Callable, Literal, cast
 
-from ..client import ClientProtocol, backoff
+from ..client import ClientProtocol, backoff, process_exception
 from ..datastructures import Headers, HeadersLike
 from ..exceptions import (
-    InvalidMessage,
     InvalidProxyMessage,
     InvalidProxyStatus,
     InvalidStatus,
@@ -128,50 +127,6 @@ def process_event(self, event: Event) -> None:
             super().process_event(event)
 
 
-def process_exception(exc: Exception) -> Exception | None:
-    """
-    Determine whether a connection error is retryable or fatal.
-
-    When reconnecting automatically with ``async for ... in connect(...)``, if a
-    connection attempt fails, :func:`process_exception` is called to determine
-    whether to retry connecting or to raise the exception.
-
-    This function defines the default behavior, which is to retry on:
-
-    * :exc:`EOFError`, :exc:`OSError`, :exc:`asyncio.TimeoutError`: network
-      errors;
-    * :exc:`~websockets.exceptions.InvalidStatus` when the status code is 500,
-      502, 503, or 504: server or proxy errors.
-
-    All other exceptions are considered fatal.
-
-    You can change this behavior with the ``process_exception`` argument of
-    :func:`connect`.
-
-    Return :obj:`None` if the exception is retryable i.e. when the error could
-    be transient and trying to reconnect with the same parameters could succeed.
-    The exception will be logged at the ``INFO`` level.
-
-    Return an exception, either ``exc`` or a new exception, if the exception is
-    fatal i.e. when trying to reconnect will most likely produce the same error.
-    That exception will be raised, breaking out of the retry loop.
-
-    """
-    # This catches python-socks' ProxyConnectionError and ProxyTimeoutError.
-    if isinstance(exc, (OSError, TimeoutError)):
-        return None
-    if isinstance(exc, InvalidMessage) and isinstance(exc.__cause__, EOFError):
-        return None
-    if isinstance(exc, InvalidStatus) and exc.response.status_code in [
-        500,  # Internal Server Error
-        502,  # Bad Gateway
-        503,  # Service Unavailable
-        504,  # Gateway Timeout
-    ]:
-        return None
-    return exc
-
-
 # This is spelled in lower case because it's exposed as a callable in the API.
 class connect:
     """
@@ -224,7 +179,8 @@ class connect:
             <../../topics/proxies>` for details.
         process_exception: When reconnecting automatically, tell whether an
             error is transient or fatal. The default behavior is defined by
-            :func:`process_exception`. Refer to its documentation for details.
+            :func:`~websockets.client.process_exception`. Refer to its
+            documentation for details.
         open_timeout: Timeout for opening the connection in seconds.
             :obj:`None` disables the timeout.
         ping_interval: Interval between keepalive pings in seconds.

src/websockets/client.py

@@ -357,6 +357,55 @@ def __init__(self, *args: Any, **kwargs: Any) -> None:
         super().__init__(*args, **kwargs)
 
 
+def process_exception(exc: Exception) -> Exception | None:
+    """
+    Determine whether a connection error is retryable or fatal.
+
+    When reconnecting automatically with ``async for ... in connect(...)``
+    (:mod:`asyncio`, :mod:`trio`) or ``for ... in reconnect(...)``
+    (:mod:`threading`), whenever a connection attempt fails,
+    :func:`process_exception` determines whether to retry connecting or to raise
+    the exception.
+
+    This function defines the default behavior, which is to retry on:
+
+    * :exc:`OSError` and :exc:`asyncio.TimeoutError`: network errors;
+    * :exc:`~websockets.exceptions.InvalidMessage` when it stems from an
+      :exc:`EOFError`: also network errors;
+    * :exc:`~websockets.exceptions.InvalidStatus` when the status code is 500,
+      502, 503, or 504: server or proxy errors.
+
+    All other exceptions are considered fatal.
+
+    You can change this behavior with the ``process_exception`` argument of
+    :func:`~websockets.asyncio.client.connect` (:mod:`asyncio`),
+    :func:`~websockets.trio.client.connect` (:mod:`trio`), or
+    :func:`~websockets.sync.client.reconnect` (:mod:`threading`).
+
+    Return :obj:`None` if the exception is retryable i.e. when the error could
+    be transient and trying to reconnect with the same parameters could succeed.
+    The exception will be logged at the ``INFO`` level.
+
+    Return an exception, either ``exc`` or a new exception, if the exception is
+    fatal i.e. when trying to reconnect will most likely produce the same error.
+    That exception will be raised, breaking out of the retry loop.
+
+    """
+    # This catches python-socks' ProxyConnectionError and ProxyTimeoutError.
+    if isinstance(exc, (OSError, TimeoutError)):
+        return None
+    if isinstance(exc, InvalidMessage) and isinstance(exc.__cause__, EOFError):
+        return None
+    if isinstance(exc, InvalidStatus) and exc.response.status_code in [
+        500,  # Internal Server Error
+        502,  # Bad Gateway
+        503,  # Service Unavailable
+        504,  # Gateway Timeout
+    ]:
+        return None
+    return exc
+
+
 BACKOFF_INITIAL_DELAY = float(os.environ.get("WEBSOCKETS_BACKOFF_INITIAL_DELAY", "5"))
 BACKOFF_MIN_DELAY = float(os.environ.get("WEBSOCKETS_BACKOFF_MIN_DELAY", "3.1"))
 BACKOFF_MAX_DELAY = float(os.environ.get("WEBSOCKETS_BACKOFF_MAX_DELAY", "90.0"))

src/websockets/sync/client.py

@@ -13,8 +13,7 @@
 from types import TracebackType
 from typing import Any, Callable, Literal, TypeVar, cast, overload
 
-from ..asyncio.client import process_exception
-from ..client import ClientProtocol, backoff
+from ..client import ClientProtocol, backoff, process_exception
 from ..datastructures import Headers, HeadersLike
 from ..exceptions import (
     InvalidProxyMessage,

src/websockets/trio/client.py

@@ -11,8 +11,7 @@
 
 import trio
 
-from ..asyncio.client import process_exception
-from ..client import ClientProtocol, backoff
+from ..client import ClientProtocol, backoff, process_exception
 from ..datastructures import Headers, HeadersLike
 from ..exceptions import (
     InvalidProxyMessage,
@@ -195,7 +194,8 @@ class connect:
             ``proxy_server_hostname`` overrides the host name from ``proxy``.
         process_exception: When reconnecting automatically, tell whether an
             error is transient or fatal. The default behavior is defined by
-            :func:`process_exception`. Refer to its documentation for details.
+            :func:`~websockets.client.process_exception`. Refer to its
+            documentation for details.
         open_timeout: Timeout for opening the connection in seconds.
             :obj:`None` disables the timeout.
         ping_interval: Interval between keepalive pings in seconds.

tests/test_client.py

@@ -6,7 +6,7 @@
 from unittest.mock import patch
 
 from websockets.client import *
-from websockets.client import backoff
+from websockets.client import backoff, process_exception
 from websockets.datastructures import Headers
 from websockets.exceptions import (
     InvalidHandshake,
@@ -684,6 +684,32 @@ def test_client_connection_class(self):
         self.assertIsInstance(client, ClientProtocol)
 
 
+class ProcessExceptionTests(unittest.TestCase):
+    def test_process_exception_retryable(self):
+        """process_exception(exc) returns None on retriable errors."""
+        connection_closed_exc = InvalidMessage("did not receive a valid HTTP response")
+        connection_closed_exc.__cause__ = EOFError(
+            "connection closed while reading HTTP status line"
+        )
+        for exc in [
+            ConnectionRefusedError(61, "Connection refused"),
+            TimeoutError("timed out while waiting for handshake response"),
+            connection_closed_exc,
+            InvalidStatus(Response(503, "Service Unavailable", Headers(), b"")),
+        ]:
+            with self.subTest(exc=exc):
+                self.assertIsNone(process_exception(exc))
+
+    def test_process_exception_fatal(self):
+        """process_exception(exc) returns exc on fatal errors."""
+        for exc in [
+            InvalidStatus(Response(410, "Gone", Headers(), b"")),
+            AssertionError("unexpected error"),
+        ]:
+            with self.subTest(exc=exc):
+                self.assertIs(process_exception(exc), exc)
+
+
 class BackoffTests(unittest.TestCase):
     def test_backoff(self):
         """backoff() yields a random delay, then exponentially increasing delays."""