Review exceptions returned by ClientSession[RPC]

Author: fjarri

docs/api.rst

@@ -13,6 +13,9 @@ Clients
 .. autoclass:: ClientSession()
    :members:
 
+.. autoclass:: ClientSessionRPC()
+   :members:
+
 
 Providers
 ---------
@@ -46,14 +49,22 @@ Errors
 ------
 
 .. autoclass:: pons.ABIDecodingError
-
-.. autoclass:: pons.RemoteError
+   :show-inheritance:
 
 .. autoclass:: pons.Unreachable
+   :show-inheritance:
 
 .. autoclass:: pons.ProtocolError
+   :show-inheritance:
+
+.. autoclass:: pons.HTTPError
+   :show-inheritance:
 
 .. autoclass:: pons.TransactionFailed
+   :show-inheritance:
+
+.. autoclass:: pons.BadResponseFormat
+   :show-inheritance:
 
 .. autoclass:: pons.ProviderError()
    :show-inheritance:

pons/__init__.py

@@ -8,10 +8,9 @@
     ContractError,
     ContractLegacyError,
     ContractPanic,
-    ProviderError,
-    RemoteError,
     TransactionFailed,
 )
+from ._client_rpc import BadResponseFormat, ClientSessionRPC, ProviderError
 from ._compiler import EVMVersion, compile_contract_file
 from ._contract import (
     BaseBoundMethodCall,
@@ -49,14 +48,15 @@
 from ._http_provider_server import HTTPProviderServer
 from ._local_provider import LocalProvider, SnapshotID
 from ._multicall import BoundMultiMethodCall, BoundMultiMethodValueCall, Multicall
-from ._provider import HTTPProvider, ProtocolError, Provider, Unreachable
+from ._provider import HTTPError, HTTPProvider, ProtocolError, Provider, Unreachable
 from ._signer import AccountSigner, Signer
 from ._utils import get_create2_address, get_create_address
 
 __all__ = [
     "ABI_JSON",
     "ABIDecodingError",
     "AccountSigner",
+    "BadResponseFormat",
     "BaseBoundMethodCall",
     "BoundConstructor",
     "BoundConstructorCall",
@@ -68,6 +68,7 @@
     "BoundMultiMethodValueCall",
     "Client",
     "ClientSession",
+    "ClientSessionRPC",
     "CompiledContract",
     "Constructor",
     "ConstructorCall",
@@ -86,6 +87,7 @@
     "FallbackProvider",
     "FallbackStrategy",
     "FallbackStrategyFactory",
+    "HTTPError",
     "HTTPProvider",
     "HTTPProviderServer",
     "LocalProvider",
@@ -99,7 +101,6 @@
     "Provider",
     "ProviderError",
     "Receive",
-    "RemoteError",
     "Signer",
     "SnapshotID",
     "TransactionFailed",

pons/_client.py

@@ -21,7 +21,7 @@
     unstructure,
 )
 
-from ._client_rpc import BadResponseFormat, ClientSessionRPC, ProviderError, RemoteError
+from ._client_rpc import BadResponseFormat, ClientSessionRPC, ProviderError
 from ._contract import (
     BaseBoundMethodCall,
     BoundConstructorCall,
@@ -61,10 +61,10 @@ async def session(self) -> AsyncIterator["ClientSession"]:
             # TODO (#58): incorporate cached values from the session back into the client
 
 
-class TransactionFailed(RemoteError):
+class TransactionFailed(Exception):
     """
-    Raised if the transaction was submitted successfully,
-    but the final receipt indicates a failure.
+    Raised for invalid transactions that are not contract executions
+    (e.g. transfers or contract deployments).
     """
 
 
@@ -121,7 +121,7 @@ def from_int(cls, val: int) -> "ContractPanicReason":
             return cls.UNKNOWN
 
 
-class ContractPanic(RemoteError):
+class ContractPanic(Exception):
     """A panic raised in a contract call."""
 
     Reason = ContractPanicReason
@@ -138,7 +138,7 @@ def __init__(self, reason: ContractPanicReason):
         self.reason = reason
 
 
-class ContractLegacyError(RemoteError):
+class ContractLegacyError(Exception):
     """A raised Solidity legacy error (from ``require()`` or ``revert()``)."""
 
     message: str
@@ -149,7 +149,7 @@ def __init__(self, message: str):
         self.message = message
 
 
-class ContractError(RemoteError):
+class ContractError(Exception):
     """A raised Solidity error (from ``revert SomeError(...)``)."""
 
     error: Error
@@ -186,7 +186,19 @@ def decode_contract_error(
 
 
 class ClientSession:
-    """An open session to the provider."""
+    """
+    An open session to the provider.
+
+    The methods of this class may raise the following exceptions:
+    :py:class:`ProviderError`,
+    :py:class:`ContractLegacyError`,
+    :py:class:`ContractError`,
+    :py:class:`ContractPanic`,
+    :py:class:`TransactionFailed`,
+    :py:class:`Unreachable`,
+    :py:class:`BadResponseFormat`,
+    a provider-specific derived class of :py:class:`ProtocolError`.
+    """
 
     def __init__(self, provider_session: ProviderSession):
         self._provider_session = provider_session

pons/_client_rpc.py

@@ -47,20 +47,17 @@ class LogFilter:
     provider_path: tuple[int, ...]
 
 
-class RemoteError(Exception):
-    """
-    A base of all errors occurring on the provider's side.
-    Encompasses both errors returned via HTTP status codes
-    and the ones returned via the JSON response.
-    """
-
-
-class BadResponseFormat(RemoteError):
+class BadResponseFormat(Exception):
     """Raised if the RPC provider returned an unexpectedly formatted response."""
 
 
-class ProviderError(RemoteError):
-    """A general problem with fulfilling the request at the provider's side."""
+class ProviderError(Exception):
+    """
+    A general problem with fulfilling the request at the provider's side.
+
+    This means the provider sent a correct response with an error code
+    and possibly some associated data.
+    """
 
     raw_code: int
     """The error code returned by the server."""
@@ -144,6 +141,16 @@ async def rpc_call_at_pin(
 
 
 class ClientSessionRPC:
+    """
+    The hub for methods which directly correspond to Ethereum RPC calls.
+
+    The methods of this class may raise the following exceptions:
+    :py:class:`ProviderError`,
+    :py:class:`Unreachable`,
+    :py:class:`BadResponseFormat`,
+    a provider-specific derived class of :py:class:`ProtocolError`.
+    """
+
     def __init__(self, provider_session: ProviderSession):
         self._provider_session = provider_session
 

pons/_provider.py

@@ -21,11 +21,27 @@ class Unreachable(Exception):
     """Raised when there is a problem connecting to the provider."""
 
 
-class ProtocolError(Exception):
-    """A protocol-specific error."""
+class ProtocolError(ABC, Exception):
+    """
+    A protocol-specific error, indicating that the provider returned an error status
+    with no additional information allowing to categorize the error further.
+
+    See the provider-specifc derived class for this exception for more details.
+    """
 
 
 class HTTPError(ProtocolError):
+    """
+    Raised when the provider returns a response with a status code other than 200,
+    and no ``"error"`` field in the associated JSON data.
+    """
+
+    status: HTTPStatus
+    """The HTTP status of the response."""
+
+    message: str
+    """The response body."""
+
     def __init__(self, status_code: int, message: str):
         try:
             status = HTTPStatus(status_code)