Raise ValueError for required or unacceptable arguments.

This improves consistency with asyncio and within websockets.

Author: aaugustin

docs/project/changelog.rst

@@ -67,6 +67,18 @@ Backwards-incompatible changes
     Aliases for deprecated API were removed from ``__all__``. As a consequence,
     they cannot be imported e.g. with ``from websockets import *`` anymore.
 
+.. admonition:: Several API raise :exc:`ValueError` instead of :exc:`TypeError`
+    for invalid arguments.
+    :class: note
+
+    :func:`~asyncio.client.connect`, :func:`~asyncio.client.unix_connect`, and
+    :func:`~asyncio.server.basic_auth` in the :mod:`asyncio` implementation as
+    well as :func:`~sync.client.connect`, :func:`~sync.client.unix_connect`,
+    :func:`~sync.server.serve`, :func:`~sync.server.unix_serve`, and
+    :func:`~sync.server.basic_auth` raise :exc:`ValueError` when a required
+    argument isn't provided or an argument is provided that is incompatible with
+    others.
+
 .. admonition:: :attr:`Frame.data <frames.Frame.data>` is now a bytes-like object.
     :class: note
 

src/websockets/asyncio/client.py

@@ -352,10 +352,10 @@ def factory() -> ClientConnection:
             kwargs.setdefault("ssl", True)
             kwargs.setdefault("server_hostname", wsuri.host)
             if kwargs.get("ssl") is None:
-                raise TypeError("ssl=None is incompatible with a wss:// URI")
+                raise ValueError("ssl=None is incompatible with a wss:// URI")
         else:
             if kwargs.get("ssl") is not None:
-                raise TypeError("ssl argument is incompatible with a ws:// URI")
+                raise ValueError("ssl argument is incompatible with a ws:// URI")
 
         if kwargs.pop("unix", False):
             _, connection = await loop.create_unix_connection(factory, **kwargs)

src/websockets/asyncio/server.py

@@ -890,10 +890,12 @@ def basic_auth(
             whether they're valid.
     Raises:
         TypeError: If ``credentials`` or ``check_credentials`` is wrong.
+        ValueError: If ``credentials`` and ``check_credentials`` are both
+            provided or both not provided.
 
     """
     if (credentials is None) == (check_credentials is None):
-        raise TypeError("provide either credentials or check_credentials")
+        raise ValueError("provide either credentials or check_credentials")
 
     if credentials is not None:
         if is_credentials(credentials):

src/websockets/sync/client.py

@@ -221,17 +221,17 @@ def connect(
 
     wsuri = parse_uri(uri)
     if not wsuri.secure and ssl is not None:
-        raise TypeError("ssl argument is incompatible with a ws:// URI")
+        raise ValueError("ssl argument is incompatible with a ws:// URI")
 
     # Private APIs for unix_connect()
     unix: bool = kwargs.pop("unix", False)
     path: str | None = kwargs.pop("path", None)
 
     if unix:
         if path is None and sock is None:
-            raise TypeError("missing path argument")
+            raise ValueError("missing path argument")
         elif path is not None and sock is not None:
-            raise TypeError("path and sock arguments are incompatible")
+            raise ValueError("path and sock arguments are incompatible")
 
     if subprotocols is not None:
         validate_subprotocols(subprotocols)

src/websockets/sync/server.py

@@ -477,14 +477,14 @@ def handler(websocket):
     if sock is None:
         if unix:
             if path is None:
-                raise TypeError("missing path argument")
+                raise ValueError("missing path argument")
             kwargs.setdefault("family", socket.AF_UNIX)
             sock = socket.create_server(path, **kwargs)
         else:
             sock = socket.create_server((host, port), **kwargs)
     else:
         if path is not None:
-            raise TypeError("path and sock arguments are incompatible")
+            raise ValueError("path and sock arguments are incompatible")
 
     # Initialize TLS wrapper
 
@@ -667,10 +667,12 @@ def basic_auth(
             whether they're valid.
     Raises:
         TypeError: If ``credentials`` or ``check_credentials`` is wrong.
+        ValueError: If ``credentials`` and ``check_credentials`` are both
+            provided or both not provided.
 
     """
     if (credentials is None) == (check_credentials is None):
-        raise TypeError("provide either credentials or check_credentials")
+        raise ValueError("provide either credentials or check_credentials")
 
     if credentials is not None:
         if is_credentials(credentials):

tests/asyncio/test_client.py

@@ -607,7 +607,7 @@ async def test_set_server_hostname(self):
 class ClientUsageErrorsTests(unittest.IsolatedAsyncioTestCase):
     async def test_ssl_without_secure_uri(self):
         """Client rejects ssl when URI isn't secure."""
-        with self.assertRaises(TypeError) as raised:
+        with self.assertRaises(ValueError) as raised:
             await connect("ws://localhost/", ssl=CLIENT_CONTEXT)
         self.assertEqual(
             str(raised.exception),
@@ -616,7 +616,7 @@ async def test_ssl_without_secure_uri(self):
 
     async def test_secure_uri_without_ssl(self):
         """Client rejects no ssl when URI is secure."""
-        with self.assertRaises(TypeError) as raised:
+        with self.assertRaises(ValueError) as raised:
             await connect("wss://localhost/", ssl=None)
         self.assertEqual(
             str(raised.exception),

tests/asyncio/test_server.py

@@ -717,7 +717,7 @@ async def check_credentials(username, password):
 
     async def test_without_credentials_or_check_credentials(self):
         """basic_auth requires either credentials or check_credentials."""
-        with self.assertRaises(TypeError) as raised:
+        with self.assertRaises(ValueError) as raised:
             basic_auth()
         self.assertEqual(
             str(raised.exception),
@@ -726,7 +726,7 @@ async def test_without_credentials_or_check_credentials(self):
 
     async def test_with_credentials_and_check_credentials(self):
         """basic_auth requires only one of credentials and check_credentials."""
-        with self.assertRaises(TypeError) as raised:
+        with self.assertRaises(ValueError) as raised:
             basic_auth(
                 credentials=("hello", "iloveyou"),
                 check_credentials=lambda: False,  # pragma: no cover

tests/sync/test_client.py

@@ -311,7 +311,7 @@ def test_set_server_hostname(self):
 class ClientUsageErrorsTests(unittest.TestCase):
     def test_ssl_without_secure_uri(self):
         """Client rejects ssl when URI isn't secure."""
-        with self.assertRaises(TypeError) as raised:
+        with self.assertRaises(ValueError) as raised:
             connect("ws://localhost/", ssl=CLIENT_CONTEXT)
         self.assertEqual(
             str(raised.exception),
@@ -320,7 +320,7 @@ def test_ssl_without_secure_uri(self):
 
     def test_unix_without_path_or_sock(self):
         """Unix client requires path when sock isn't provided."""
-        with self.assertRaises(TypeError) as raised:
+        with self.assertRaises(ValueError) as raised:
             unix_connect()
         self.assertEqual(
             str(raised.exception),
@@ -331,7 +331,7 @@ def test_unix_with_path_and_sock(self):
         """Unix client rejects path when sock is provided."""
         sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
         self.addCleanup(sock.close)
-        with self.assertRaises(TypeError) as raised:
+        with self.assertRaises(ValueError) as raised:
             unix_connect(path="/", sock=sock)
         self.assertEqual(
             str(raised.exception),

tests/sync/test_server.py

@@ -361,7 +361,7 @@ def test_connection(self):
 class ServerUsageErrorsTests(unittest.TestCase):
     def test_unix_without_path_or_sock(self):
         """Unix server requires path when sock isn't provided."""
-        with self.assertRaises(TypeError) as raised:
+        with self.assertRaises(ValueError) as raised:
             unix_serve(handler)
         self.assertEqual(
             str(raised.exception),
@@ -372,7 +372,7 @@ def test_unix_with_path_and_sock(self):
         """Unix server rejects path when sock is provided."""
         sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
         self.addCleanup(sock.close)
-        with self.assertRaises(TypeError) as raised:
+        with self.assertRaises(ValueError) as raised:
             unix_serve(handler, path="/", sock=sock)
         self.assertEqual(
             str(raised.exception),
@@ -504,7 +504,7 @@ def check_credentials(username, password):
 
     def test_without_credentials_or_check_credentials(self):
         """basic_auth requires either credentials or check_credentials."""
-        with self.assertRaises(TypeError) as raised:
+        with self.assertRaises(ValueError) as raised:
             basic_auth()
         self.assertEqual(
             str(raised.exception),
@@ -513,7 +513,7 @@ def test_without_credentials_or_check_credentials(self):
 
     def test_with_credentials_and_check_credentials(self):
         """basic_auth requires only one of credentials and check_credentials."""
-        with self.assertRaises(TypeError) as raised:
+        with self.assertRaises(ValueError) as raised:
             basic_auth(
                 credentials=("hello", "iloveyou"),
                 check_credentials=lambda: False,  # pragma: no cover