Add exception raised to docstring

libp2p/network/connection/raw_connection.py

@@ -24,10 +24,13 @@ class RawConnection(IRawConnection):
         self._drain_lock = asyncio.Lock()
 
     async def write(self, data: bytes) -> None:
+        """
+        Raise `RawConnError` if the underlying connection breaks
+        """
         try:
             self.writer.write(data)
-        except ConnectionResetError:
-            raise RawConnError()
+        except ConnectionResetError as error:
+            raise RawConnError(error)
         # Reference: https://github.com/ethereum/lahja/blob/93610b2eb46969ff1797e0748c7ac2595e130aef/lahja/asyncio/endpoint.py#L99-L102  # noqa: E501
         # Use a lock to serialize drain() calls. Circumvents this bug:
         # https://bugs.python.org/issue29930
@@ -41,11 +44,13 @@ class RawConnection(IRawConnection):
         """
         Read up to ``n`` bytes from the underlying stream.
         This call is delegated directly to the underlying ``self.reader``.
+
+        Raise `RawConnError` if the underlying connection breaks
         """
         try:
             return await self.reader.read(n)
-        except ConnectionResetError:
-            raise RawConnError()
+        except ConnectionResetError as error:
+            raise RawConnError(error)
 
     async def close(self) -> None:
         self.writer.close()

libp2p/network/swarm.py

@@ -173,6 +173,7 @@ class Swarm(INetwork):
         """
         :param peer_id: peer_id of destination
         :param protocol_id: protocol id
+        :raises SwarmException: raised when an error occurs
         :return: net stream instance
         """
         logger.debug(

libp2p/protocol_muxer/multiselect.py

@@ -37,7 +37,7 @@ class Multiselect(IMultiselectMuxer):
         Negotiate performs protocol selection
         :param stream: stream to negotiate on
         :return: selected protocol name, handler function
-        :raise Exception: negotiation failed exception
+        :raise MultiselectError: raised when negotiation failed
         """
 
         # Perform handshake to ensure multiselect protocol IDs match
@@ -49,7 +49,7 @@ class Multiselect(IMultiselectMuxer):
             try:
                 command = await communicator.read()
             except MultiselectCommunicatorError as error:
-                raise MultiselectError(str(error))
+                raise MultiselectError(error)
 
             # Command is ls or a protocol
             if command == "ls":
@@ -76,7 +76,7 @@ class Multiselect(IMultiselectMuxer):
         """
         Perform handshake to agree on multiselect protocol
         :param communicator: communicator to use
-        :raise Exception: error in handshake
+        :raise MultiselectError: raised when handshake failed
         """
 
         # TODO: Use format used by go repo for messages
@@ -91,7 +91,7 @@ class Multiselect(IMultiselectMuxer):
         try:
             handshake_contents = await communicator.read()
         except MultiselectCommunicatorError as error:
-            raise MultiselectError(str(error))
+            raise MultiselectError(error)
 
         # Confirm that the protocols are the same
         if not validate_handshake(handshake_contents):

libp2p/protocol_muxer/multiselect_client.py

@@ -21,7 +21,7 @@ class MultiselectClient(IMultiselectClient):
         Ensure that the client and multiselect
         are both using the same multiselect protocol
         :param stream: stream to communicate with multiselect over
-        :raise Exception: multiselect protocol ID mismatch
+        :raise MultiselectClientError: raised when handshake failed
         """
 
         # TODO: Use format used by go repo for messages
@@ -54,6 +54,7 @@ class MultiselectClient(IMultiselectClient):
         :param protocol: protocol to select
         :param stream: stream to communicate with multiselect over
         :return: selected protocol
+        :raise MultiselectClientError: raised when protocol negotiation failed
         """
         # Perform handshake to ensure multiselect protocol IDs match
         await self.handshake(communicator)
@@ -77,7 +78,7 @@ class MultiselectClient(IMultiselectClient):
         Try to select the given protocol or raise exception if fails
         :param communicator: communicator to use to communicate with counterparty
         :param protocol: protocol to select
-        :raise Exception: error in protocol selection
+        :raise MultiselectClientError: raised when protocol negotiation failed
         :return: selected protocol
         """
 

libp2p/protocol_muxer/multiselect_communicator.py

@@ -14,6 +14,9 @@ class MultiselectCommunicator(IMultiselectCommunicator):
         self.read_writer = read_writer
 
     async def write(self, msg_str: str) -> None:
+        """
+        :raise MultiselectCommunicatorError: raised when failed to write to underlying reader
+        """
         msg_bytes = encode_delim(msg_str.encode())
         try:
             await self.read_writer.write(msg_bytes)
@@ -23,6 +26,9 @@ class MultiselectCommunicator(IMultiselectCommunicator):
             )
 
     async def read(self) -> str:
+        """
+        :raise MultiselectCommunicatorError: raised when failed to read from underlying reader
+        """
         try:
             data = await read_delim(self.read_writer)
         # `IOException` includes `IncompleteReadError` and `StreamError`

libp2p/security/insecure/transport.py

@@ -45,6 +45,9 @@ class InsecureSession(BaseSession):
         await self.conn.close()
 
     async def run_handshake(self) -> None:
+        """
+        Raise `HandshakeFailure` when handshake failed
+        """
         msg = make_exchange_message(self.local_private_key.get_public_key())
         msg_bytes = msg.SerializeToString()
         encoded_msg_bytes = encode_fixedint_prefixed(msg_bytes)

libp2p/security/secio/transport.py

@@ -400,6 +400,8 @@ async def create_secure_session(
     Attempt the initial `secio` handshake with the remote peer.
     If successful, return an object that provides secure communication to the
     ``remote_peer``.
+    Raise `SecioException` when `conn` closed.
+    Raise `InconsistentNonce` when handshake failed
     """
     msg_io = MsgIOReadWriter(conn)
     try:

libp2p/transport/tcp/tcp.py

@@ -63,6 +63,7 @@ class TCP(ITransport):
         dial a transport to peer listening on multiaddr
         :param maddr: multiaddr of peer
         :return: `RawConnection` if successful
+        :raise OpenConnectionError: raised when failed to open connection
         """
         self.host = maddr.value_for_protocol("ip4")
         self.port = int(maddr.value_for_protocol("tcp"))