Add close_code and close_reason to new implementations.

Also add state to threading implementation.

Fix #1537.

Author: aaugustin

docs/reference/asyncio/client.rst

@@ -57,3 +57,10 @@ Using a connection
     .. autoattribute:: response
 
     .. autoproperty:: subprotocol
+
+    The following attributes are available after the closing handshake,
+    once the WebSocket connection is closed:
+
+    .. autoproperty:: close_code
+
+    .. autoproperty:: close_reason

docs/reference/asyncio/common.rst

@@ -45,3 +45,10 @@ Both sides (new :mod:`asyncio`)
     .. autoattribute:: response
 
     .. autoproperty:: subprotocol
+
+    The following attributes are available after the closing handshake,
+    once the WebSocket connection is closed:
+
+    .. autoproperty:: close_code
+
+    .. autoproperty:: close_reason

docs/reference/asyncio/server.rst

@@ -79,6 +79,13 @@ Using a connection
 
     .. autoproperty:: subprotocol
 
+    The following attributes are available after the closing handshake,
+    once the WebSocket connection is closed:
+
+    .. autoproperty:: close_code
+
+    .. autoproperty:: close_reason
+
 Broadcast
 ---------
 

docs/reference/sync/client.rst

@@ -39,6 +39,8 @@ Using a connection
 
     .. autoproperty:: remote_address
 
+    .. autoproperty:: state
+
     The following attributes are available after the opening handshake,
     once the WebSocket connection is open:
 
@@ -47,3 +49,10 @@ Using a connection
     .. autoattribute:: response
 
     .. autoproperty:: subprotocol
+
+    The following attributes are available after the closing handshake,
+    once the WebSocket connection is closed:
+
+    .. autoproperty:: close_code
+
+    .. autoproperty:: close_reason

docs/reference/sync/common.rst

@@ -31,6 +31,8 @@ Both sides (:mod:`threading`)
 
     .. autoproperty:: remote_address
 
+    .. autoproperty:: state
+
     The following attributes are available after the opening handshake,
     once the WebSocket connection is open:
 
@@ -39,3 +41,10 @@ Both sides (:mod:`threading`)
     .. autoattribute:: response
 
     .. autoproperty:: subprotocol
+
+    The following attributes are available after the closing handshake,
+    once the WebSocket connection is closed:
+
+    .. autoproperty:: close_code
+
+    .. autoproperty:: close_reason

docs/reference/sync/server.rst

@@ -52,6 +52,8 @@ Using a connection
 
     .. autoproperty:: remote_address
 
+    .. autoproperty:: state
+
     The following attributes are available after the opening handshake,
     once the WebSocket connection is open:
 
@@ -61,6 +63,13 @@ Using a connection
 
     .. autoproperty:: subprotocol
 
+    The following attributes are available after the closing handshake,
+    once the WebSocket connection is closed:
+
+    .. autoproperty:: close_code
+
+    .. autoproperty:: close_reason
+
 HTTP Basic Authentication
 -------------------------
 

src/websockets/asyncio/connection.py

@@ -185,6 +185,30 @@ def subprotocol(self) -> Subprotocol | None:
         """
         return self.protocol.subprotocol
 
+    @property
+    def close_code(self) -> int | None:
+        """
+        State of the WebSocket connection, defined in :rfc:`6455`.
+
+        This attribute is provided for completeness. Typical applications
+        shouldn't check its value. Instead, they should inspect attributes
+        of :exc:`~websockets.exceptions.ConnectionClosed` exceptions.
+
+        """
+        return self.protocol.close_code
+
+    @property
+    def close_reason(self) -> str | None:
+        """
+        State of the WebSocket connection, defined in :rfc:`6455`.
+
+        This attribute is provided for completeness. Typical applications
+        shouldn't check its value. Instead, they should inspect attributes
+        of :exc:`~websockets.exceptions.ConnectionClosed` exceptions.
+
+        """
+        return self.protocol.close_reason
+
     # Public methods
 
     async def __aenter__(self) -> Connection:

src/websockets/protocol.py

@@ -159,7 +159,12 @@ def state(self) -> State:
         """
         State of the WebSocket connection.
 
-        Defined in 4.1, 4.2, 7.1.3, and 7.1.4 of :rfc:`6455`.
+        Defined in 4.1_, 4.2_, 7.1.3_, and 7.1.4_ of :rfc:`6455`.
+
+        .. _4.1: https://datatracker.ietf.org/doc/html/rfc6455#section-4.1
+        .. _4.2: https://datatracker.ietf.org/doc/html/rfc6455#section-4.2
+        .. _7.1.3: https://datatracker.ietf.org/doc/html/rfc6455#section-7.1.3
+        .. _7.1.4: https://datatracker.ietf.org/doc/html/rfc6455#section-7.1.4
 
         """
         return self._state
@@ -173,10 +178,11 @@ def state(self, state: State) -> None:
     @property
     def close_code(self) -> int | None:
         """
-        `WebSocket close code`_.
+        WebSocket close code received from the remote endpoint.
+
+        Defined in 7.1.5_ of :rfc:`6455`.
 
-        .. _WebSocket close code:
-            https://datatracker.ietf.org/doc/html/rfc6455#section-7.1.5
+        .. _7.1.5: https://datatracker.ietf.org/doc/html/rfc6455#section-7.1.5
 
         :obj:`None` if the connection isn't closed yet.
 
@@ -191,10 +197,11 @@ def close_code(self) -> int | None:
     @property
     def close_reason(self) -> str | None:
         """
-        `WebSocket close reason`_.
+        WebSocket close reason  received from the remote endpoint.
+
+        Defined in 7.1.6_ of :rfc:`6455`.
 
-        .. _WebSocket close reason:
-            https://datatracker.ietf.org/doc/html/rfc6455#section-7.1.6
+        .. _7.1.6: https://datatracker.ietf.org/doc/html/rfc6455#section-7.1.6
 
         :obj:`None` if the connection isn't closed yet.
 

src/websockets/sync/connection.py

@@ -140,6 +140,19 @@ def remote_address(self) -> Any:
         """
         return self.socket.getpeername()
 
+    @property
+    def state(self) -> State:
+        """
+        State of the WebSocket connection, defined in :rfc:`6455`.
+
+        This attribute is provided for completeness. Typical applications
+        shouldn't check its value. Instead, they should call :meth:`~recv` or
+        :meth:`send` and handle :exc:`~websockets.exceptions.ConnectionClosed`
+        exceptions.
+
+        """
+        return self.protocol.state
+
     @property
     def subprotocol(self) -> Subprotocol | None:
         """
@@ -150,6 +163,30 @@ def subprotocol(self) -> Subprotocol | None:
         """
         return self.protocol.subprotocol
 
+    @property
+    def close_code(self) -> int | None:
+        """
+        State of the WebSocket connection, defined in :rfc:`6455`.
+
+        This attribute is provided for completeness. Typical applications
+        shouldn't check its value. Instead, they should inspect attributes
+        of :exc:`~websockets.exceptions.ConnectionClosed` exceptions.
+
+        """
+        return self.protocol.close_code
+
+    @property
+    def close_reason(self) -> str | None:
+        """
+        State of the WebSocket connection, defined in :rfc:`6455`.
+
+        This attribute is provided for completeness. Typical applications
+        shouldn't check its value. Instead, they should inspect attributes
+        of :exc:`~websockets.exceptions.ConnectionClosed` exceptions.
+
+        """
+        return self.protocol.close_reason
+
     # Public methods
 
     def __enter__(self) -> Connection:

tests/asyncio/test_connection.py

@@ -1139,7 +1139,7 @@ async def test_remote_address(self, get_extra_info):
 
     async def test_state(self):
         """Connection has a state attribute."""
-        self.assertEqual(self.connection.state, State.OPEN)
+        self.assertIs(self.connection.state, State.OPEN)
 
     async def test_request(self):
         """Connection has a request attribute."""
@@ -1153,6 +1153,14 @@ async def test_subprotocol(self):
         """Connection has a subprotocol attribute."""
         self.assertIsNone(self.connection.subprotocol)
 
+    async def test_close_code(self):
+        """Connection has a close_code attribute."""
+        self.assertIsNone(self.connection.close_code)
+
+    async def test_close_reason(self):
+        """Connection has a close_reason attribute."""
+        self.assertIsNone(self.connection.close_reason)
+
     # Test reporting of network errors.
 
     async def test_writing_in_data_received_fails(self):

tests/sync/test_connection.py

@@ -15,7 +15,7 @@
     ConnectionClosedOK,
 )
 from websockets.frames import CloseCode, Frame, Opcode
-from websockets.protocol import CLIENT, SERVER, Protocol
+from websockets.protocol import CLIENT, SERVER, Protocol, State
 from websockets.sync.connection import *
 
 from ..protocol import RecordingProtocol
@@ -808,6 +808,10 @@ def test_remote_address(self, getpeername):
         self.assertEqual(self.connection.remote_address, ("peer", 1234))
         getpeername.assert_called_with()
 
+    def test_state(self):
+        """Connection has a state attribute."""
+        self.assertIs(self.connection.state, State.OPEN)
+
     def test_request(self):
         """Connection has a request attribute."""
         self.assertIsNone(self.connection.request)
@@ -820,6 +824,14 @@ def test_subprotocol(self):
         """Connection has a subprotocol attribute."""
         self.assertIsNone(self.connection.subprotocol)
 
+    def test_close_code(self):
+        """Connection has a close_code attribute."""
+        self.assertIsNone(self.connection.close_code)
+
+    def test_close_reason(self):
+        """Connection has a close_reason attribute."""
+        self.assertIsNone(self.connection.close_reason)
+
     # Test reporting of network errors.
 
     @unittest.skipUnless(sys.platform == "darwin", "works only on BSD")