Add type hints and include mypy in build

This fully type hints the wsproto codebase and uses mypy to ensure the
type hints are added and correct. This has identified some potential
bugs, see 582d052

The additional linting disable is because the mypy TYPE_CHECKING is
not understood by pylint.

Author: pgjones

.prospector.yml

@@ -1,5 +1,6 @@
 pylint:
   disable:
+    - cyclic-import
     - unused-argument
     - useless-object-inheritance
 

setup.cfg

@@ -25,7 +25,7 @@ combine_as_imports=True
 force_grid_wrap=0
 include_trailing_comma=True
 known_first_party=wsproto, test
-known_third_party=h11, pytest
+known_third_party=h11, pytest, _pytest
 line_length=88
 multi_line_output=3
 no_lines_before=LOCALFOLDER

test/helpers.py

@@ -1,21 +1,27 @@
+from typing import Optional, Union
+
 from wsproto.extensions import Extension
 
 
 class FakeExtension(Extension):
     name = "fake"
 
-    def __init__(self, offer_response=None, accept_response=None):
+    def __init__(
+        self,
+        offer_response: Optional[Union[bool, str]] = None,
+        accept_response: Optional[Union[bool, str]] = None,
+    ) -> None:
         self.offer_response = offer_response
-        self.accepted_offer = None
-        self.offered = None
+        self.accepted_offer: Optional[str] = None
+        self.offered: Optional[str] = None
         self.accept_response = accept_response
 
-    def offer(self):
+    def offer(self) -> Union[bool, str]:
         return self.offer_response
 
-    def finalize(self, offer):
+    def finalize(self, offer: str) -> None:
         self.accepted_offer = offer
 
-    def accept(self, offer):
+    def accept(self, offer: str) -> Union[bool, str]:
         self.offered = offer
         return self.accept_response

test/test_client.py

@@ -1,13 +1,22 @@
 # These tests test the behaviours expected of wsproto in when the
 # connection is a client.
+from typing import List, Optional, Tuple
 
 import h11
 import pytest
 
 from wsproto import WSConnection
 from wsproto.connection import CLIENT
-from wsproto.events import AcceptConnection, RejectConnection, RejectData, Request
+from wsproto.events import (
+    AcceptConnection,
+    Event,
+    RejectConnection,
+    RejectData,
+    Request,
+)
+from wsproto.extensions import Extension
 from wsproto.frame_protocol import CloseReason
+from wsproto.typing import Headers
 from wsproto.utilities import (
     generate_accept_token,
     normed_header_dict,
@@ -16,15 +25,14 @@
 from .helpers import FakeExtension
 
 
-def _make_connection_request(request):
-    # type: (Request) -> h11.Request
+def _make_connection_request(request: Request) -> h11.Request:
     client = WSConnection(CLIENT)
     server = h11.Connection(h11.SERVER)
     server.receive_data(client.send(request))
     return server.next_event()
 
 
-def test_connection_request():
+def test_connection_request() -> None:
     request = _make_connection_request(Request(host="localhost", target="/"))
 
     assert request.http_version == b"1.1"
@@ -38,7 +46,7 @@ def test_connection_request():
     assert b"sec-websocket-key" in headers
 
 
-def test_connection_request_additional_headers():
+def test_connection_request_additional_headers() -> None:
     request = _make_connection_request(
         Request(
             host="localhost",
@@ -52,40 +60,40 @@ def test_connection_request_additional_headers():
     assert headers[b"x-bar"] == b"Foo"
 
 
-def test_connection_request_simple_extension():
+def test_connection_request_simple_extension() -> None:
     extension = FakeExtension(offer_response=True)
     request = _make_connection_request(
-        Request(host="localhost", target="/", extensions=[extension])
+        Request(host="localhost", target="/", extensions=[extension])  # type: ignore
     )
 
     headers = normed_header_dict(request.headers)
     assert headers[b"sec-websocket-extensions"] == extension.name.encode("ascii")
 
 
-def test_connection_request_simple_extension_no_offer():
+def test_connection_request_simple_extension_no_offer() -> None:
     extension = FakeExtension(offer_response=False)
     request = _make_connection_request(
-        Request(host="localhost", target="/", extensions=[extension])
+        Request(host="localhost", target="/", extensions=[extension])  # type: ignore
     )
 
     headers = normed_header_dict(request.headers)
     assert b"sec-websocket-extensions" not in headers
 
 
-def test_connection_request_parametrised_extension():
+def test_connection_request_parametrised_extension() -> None:
     extension = FakeExtension(offer_response="parameter1=value1; parameter2=value2")
     request = _make_connection_request(
-        Request(host="localhost", target="/", extensions=[extension])
+        Request(host="localhost", target="/", extensions=[extension])  # type: ignore
     )
 
     headers = normed_header_dict(request.headers)
     assert headers[b"sec-websocket-extensions"] == b"%s; %s" % (
         extension.name.encode("ascii"),
-        extension.offer_response.encode("ascii"),
+        extension.offer_response.encode("ascii"),  # type: ignore
     )
 
 
-def test_connection_request_subprotocols():
+def test_connection_request_subprotocols() -> None:
     request = _make_connection_request(
         Request(host="localhost", target="/", subprotocols=["one", "two"])
     )
@@ -95,12 +103,12 @@ def test_connection_request_subprotocols():
 
 
 def _make_handshake(
-    response_status,
-    response_headers,
-    subprotocols=None,
-    extensions=None,
-    auto_accept_key=True,
-):
+    response_status: int,
+    response_headers: Headers,
+    subprotocols: Optional[List[str]] = None,
+    extensions: Optional[List[Extension]] = None,
+    auto_accept_key: bool = True,
+) -> List[Event]:
     client = WSConnection(CLIENT)
     server = h11.Connection(h11.SERVER)
     server.receive_data(
@@ -130,22 +138,22 @@ def _make_handshake(
     return list(client.events())
 
 
-def test_handshake():
+def test_handshake() -> None:
     events = _make_handshake(
         101, [(b"connection", b"Upgrade"), (b"upgrade", b"WebSocket")]
     )
     assert events == [AcceptConnection()]
 
 
-def test_broken_handshake():
+def test_broken_handshake() -> None:
     events = _make_handshake(
         102, [(b"connection", b"Upgrade"), (b"upgrade", b"WebSocket")]
     )
     assert isinstance(events[0], RejectConnection)
     assert events[0].status_code == 102
 
 
-def test_handshake_extra_accept_headers():
+def test_handshake_extra_accept_headers() -> None:
     events = _make_handshake(
         101,
         [(b"connection", b"Upgrade"), (b"upgrade", b"WebSocket"), (b"X-Foo", b"bar")],
@@ -154,20 +162,20 @@ def test_handshake_extra_accept_headers():
 
 
 @pytest.mark.parametrize("extra_headers", [[], [(b"connection", b"Keep-Alive")]])
-def test_handshake_response_broken_connection_header(extra_headers):
+def test_handshake_response_broken_connection_header(extra_headers: Headers) -> None:
     with pytest.raises(RemoteProtocolError) as excinfo:
         events = _make_handshake(101, [(b"upgrade", b"WebSocket")] + extra_headers)
     assert str(excinfo.value) == "Missing header, 'Connection: Upgrade'"
 
 
 @pytest.mark.parametrize("extra_headers", [[], [(b"upgrade", b"h2")]])
-def test_handshake_response_broken_upgrade_header(extra_headers):
+def test_handshake_response_broken_upgrade_header(extra_headers: Headers) -> None:
     with pytest.raises(RemoteProtocolError) as excinfo:
         events = _make_handshake(101, [(b"connection", b"Upgrade")] + extra_headers)
     assert str(excinfo.value) == "Missing header, 'Upgrade: WebSocket'"
 
 
-def test_handshake_response_missing_websocket_key_header():
+def test_handshake_response_missing_websocket_key_header() -> None:
     with pytest.raises(RemoteProtocolError) as excinfo:
         events = _make_handshake(
             101,
@@ -177,7 +185,7 @@ def test_handshake_response_missing_websocket_key_header():
     assert str(excinfo.value) == "Bad accept token"
 
 
-def test_handshake_with_subprotocol():
+def test_handshake_with_subprotocol() -> None:
     events = _make_handshake(
         101,
         [
@@ -190,7 +198,7 @@ def test_handshake_with_subprotocol():
     assert events == [AcceptConnection(subprotocol="one")]
 
 
-def test_handshake_bad_subprotocol():
+def test_handshake_bad_subprotocol() -> None:
     with pytest.raises(RemoteProtocolError) as excinfo:
         events = _make_handshake(
             101,
@@ -203,7 +211,7 @@ def test_handshake_bad_subprotocol():
     assert str(excinfo.value) == "unrecognized subprotocol new"
 
 
-def test_handshake_with_extension():
+def test_handshake_with_extension() -> None:
     extension = FakeExtension(offer_response=True)
     events = _make_handshake(
         101,
@@ -217,7 +225,7 @@ def test_handshake_with_extension():
     assert events == [AcceptConnection(extensions=[extension])]
 
 
-def test_handshake_bad_extension():
+def test_handshake_bad_extension() -> None:
     with pytest.raises(RemoteProtocolError) as excinfo:
         events = _make_handshake(
             101,
@@ -230,15 +238,17 @@ def test_handshake_bad_extension():
     assert str(excinfo.value) == "unrecognized extension bad"
 
 
-def test_protocol_error():
+def test_protocol_error() -> None:
     client = WSConnection(CLIENT)
     client.send(Request(host="localhost", target="/"))
     with pytest.raises(RemoteProtocolError) as excinfo:
         client.receive_data(b"broken nonsense\r\n\r\n")
     assert str(excinfo.value) == "Bad HTTP message"
 
 
-def _make_handshake_rejection(status_code, body=None):
+def _make_handshake_rejection(
+    status_code: int, body: Optional[bytes] = None
+) -> List[Event]:
     client = WSConnection(CLIENT)
     server = h11.Connection(h11.SERVER)
     server.receive_data(client.send(Request(host="localhost", target="/")))
@@ -255,7 +265,7 @@ def _make_handshake_rejection(status_code, body=None):
     return list(client.events())
 
 
-def test_handshake_rejection():
+def test_handshake_rejection() -> None:
     events = _make_handshake_rejection(400)
     assert events == [
         RejectConnection(
@@ -265,7 +275,7 @@ def test_handshake_rejection():
     ]
 
 
-def test_handshake_rejection_with_body():
+def test_handshake_rejection_with_body() -> None:
     events = _make_handshake_rejection(400, b"Hello")
     assert events == [
         RejectConnection(

test/test_connection.py

@@ -21,7 +21,7 @@
 
 @pytest.mark.parametrize("client_sends", [True, False])
 @pytest.mark.parametrize("final", [True, False])
-def test_send_message(client_sends, final):
+def test_send_message(client_sends: bool, final: bool) -> None:
     client = Connection(CLIENT)
     server = Connection(SERVER)
 
@@ -33,7 +33,9 @@ def test_send_message(client_sends, final):
         remote = client
 
     data = b"x" * 23
-    remote.receive_data(local.send(BytesMessage(data=data, message_finished=final)))
+    remote.receive_data(
+        local.send(BytesMessage(data=data, message_finished=final))  # type: ignore
+    )
     event = next(remote.events())
     assert isinstance(event, BytesMessage)
     assert event.data == data
@@ -45,7 +47,7 @@ def test_send_message(client_sends, final):
     "code, reason",
     [(CloseReason.NORMAL_CLOSURE, "bye"), (CloseReason.GOING_AWAY, "👋👋")],
 )
-def test_closure(client_sends, code, reason):
+def test_closure(client_sends: bool, code: CloseReason, reason: str) -> None:
     client = Connection(CLIENT)
     server = Connection(SERVER)
 
@@ -75,7 +77,7 @@ def test_closure(client_sends, code, reason):
     assert local.state is ConnectionState.CLOSED
 
 
-def test_abnormal_closure():
+def test_abnormal_closure() -> None:
     client = Connection(CLIENT)
     client.receive_data(None)
     event = next(client.events())
@@ -84,15 +86,15 @@ def test_abnormal_closure():
     assert client.state is ConnectionState.CLOSED
 
 
-def test_close_whilst_closing():
+def test_close_whilst_closing() -> None:
     client = Connection(CLIENT)
     client.send(CloseConnection(code=CloseReason.NORMAL_CLOSURE))
     with pytest.raises(LocalProtocolError):
         client.send(CloseConnection(code=CloseReason.NORMAL_CLOSURE))
 
 
 @pytest.mark.parametrize("client_sends", [True, False])
-def test_ping_pong(client_sends):
+def test_ping_pong(client_sends: bool) -> None:
     client = Connection(CLIENT)
     server = Connection(SERVER)
 
@@ -115,7 +117,7 @@ def test_ping_pong(client_sends):
     assert event.payload == payload
 
 
-def test_unsolicited_pong():
+def test_unsolicited_pong() -> None:
     client = Connection(CLIENT)
     server = Connection(SERVER)
 
@@ -127,20 +129,22 @@ def test_unsolicited_pong():
 
 
 @pytest.mark.parametrize("split_message", [True, False])
-def test_data(split_message):
+def test_data(split_message: bool) -> None:
     client = Connection(CLIENT)
     server = Connection(SERVER)
 
     data = "ƒñö®∂😎"
     server.receive_data(
-        client.send(TextMessage(data=data, message_finished=not split_message))
+        client.send(
+            TextMessage(data=data, message_finished=not split_message)  # type: ignore
+        )
     )
     event = next(server.events())
     assert isinstance(event, TextMessage)
     assert event.message_finished is not split_message
 
 
-def test_frame_protocol_gets_fed_garbage():
+def test_frame_protocol_gets_fed_garbage() -> None:
     client = Connection(CLIENT)
 
     payload = b"x" * 23
@@ -152,13 +156,13 @@ def test_frame_protocol_gets_fed_garbage():
     assert event.code == CloseReason.PROTOCOL_ERROR
 
 
-def test_send_invalid_event():
+def test_send_invalid_event() -> None:
     client = Connection(CLIENT)
     with pytest.raises(LocalProtocolError):
         client.send(Request(target="/", host="wsproto"))
 
 
-def test_receive_data_when_closed():
+def test_receive_data_when_closed() -> None:
     client = Connection(CLIENT)
     client._state = ConnectionState.CLOSED
     with pytest.raises(LocalProtocolError):