From 7fc958e7bec3863b0487e31e911d72f540f83e20 Mon Sep 17 00:00:00 2001 From: NIC619 Date: Thu, 19 Sep 2019 22:19:36 +0800 Subject: [PATCH] Add exception raised to docstring --- libp2p/network/connection/raw_connection.py | 13 +++++++++---- libp2p/network/swarm.py | 1 + libp2p/protocol_muxer/multiselect.py | 8 ++++---- libp2p/protocol_muxer/multiselect_client.py | 5 +++-- libp2p/protocol_muxer/multiselect_communicator.py | 6 ++++++ libp2p/security/insecure/transport.py | 3 +++ libp2p/security/secio/transport.py | 2 ++ libp2p/transport/tcp/tcp.py | 1 + 8 files changed, 29 insertions(+), 10 deletions(-) diff --git a/libp2p/network/connection/raw_connection.py b/libp2p/network/connection/raw_connection.py index 2bdb12a..144c1a8 100644 --- a/libp2p/network/connection/raw_connection.py +++ b/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() diff --git a/libp2p/network/swarm.py b/libp2p/network/swarm.py index 83df555..da32a02 100644 --- a/libp2p/network/swarm.py +++ b/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( diff --git a/libp2p/protocol_muxer/multiselect.py b/libp2p/protocol_muxer/multiselect.py index 13e6a0d..a0fa91f 100644 --- a/libp2p/protocol_muxer/multiselect.py +++ b/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): diff --git a/libp2p/protocol_muxer/multiselect_client.py b/libp2p/protocol_muxer/multiselect_client.py index 361100b..24db70a 100644 --- a/libp2p/protocol_muxer/multiselect_client.py +++ b/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 """ diff --git a/libp2p/protocol_muxer/multiselect_communicator.py b/libp2p/protocol_muxer/multiselect_communicator.py index 6dbc50f..a66a564 100644 --- a/libp2p/protocol_muxer/multiselect_communicator.py +++ b/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` diff --git a/libp2p/security/insecure/transport.py b/libp2p/security/insecure/transport.py index 5d552ac..7df0575 100644 --- a/libp2p/security/insecure/transport.py +++ b/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) diff --git a/libp2p/security/secio/transport.py b/libp2p/security/secio/transport.py index d99dc15..e1aa022 100644 --- a/libp2p/security/secio/transport.py +++ b/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: diff --git a/libp2p/transport/tcp/tcp.py b/libp2p/transport/tcp/tcp.py index db2dd74..5ee2428 100644 --- a/libp2p/transport/tcp/tcp.py +++ b/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"))