web3 7.0.0b8__py3-none-any.whl → 7.1.0__py3-none-any.whl

web3/contract/utils.py

@@ -16,9 +16,16 @@ from eth_abi.exceptions import (
     DecodingError,
 )
 from eth_typing import (
+    ABI,
+    ABICallable,
+    ABIFunction,
     ChecksumAddress,
     TypeStr,
 )
+from eth_utils.abi import (
+    filter_abi_by_type,
+    get_abi_output_types,
+)
 from eth_utils.toolz import (
     compose,
     curry,
@@ -28,8 +35,6 @@ from hexbytes import (
 )
 
 from web3._utils.abi import (
-    filter_by_type,
-    get_abi_output_types,
     map_abi_data,
     named_tree,
     recursive_dict_to_namedtuple,
@@ -37,8 +42,10 @@ from web3._utils.abi import (
 from web3._utils.async_transactions import (
     async_fill_transaction_defaults,
 )
+from web3._utils.compat import (
+    TypeAlias,
+)
 from web3._utils.contracts import (
-    find_matching_fn_abi,
     prepare_transaction,
 )
 from web3._utils.normalizers import (
@@ -52,14 +59,16 @@ from web3.exceptions import (
     Web3ValueError,
 )
 from web3.types import (
-    ABI,
-    ABIFunction,
+    ABIElementIdentifier,
     BlockIdentifier,
-    FunctionIdentifier,
+    RPCEndpoint,
     StateOverride,
     TContractFn,
     TxParams,
 )
+from web3.utils.abi import (
+    get_abi_element,
+)
 
 if TYPE_CHECKING:
     from web3 import (  # noqa: F401
@@ -77,8 +86,8 @@ ACCEPTABLE_EMPTY_STRINGS = ["0x", b"0x", "", b""]
 def format_contract_call_return_data_curried(
     async_w3: Union["AsyncWeb3", "Web3"],
     decode_tuples: bool,
-    fn_abi: ABIFunction,
-    function_identifier: FunctionIdentifier,
+    fn_abi: ABICallable,
+    abi_element_identifier: ABIElementIdentifier,
     normalizers: Tuple[Callable[..., Any], ...],
     output_types: Sequence[TypeStr],
     return_data: Any,
@@ -92,7 +101,7 @@ def format_contract_call_return_data_curried(
         output_data = async_w3.codec.decode(output_types, return_data)
     except DecodingError as e:
         msg = (
-            f"Could not decode contract function call to {function_identifier} "
+            f"Could not decode contract function call to {abi_element_identifier} "
             f"with return data: {str(return_data)}, output_types: {output_types}"
         )
         raise BadFunctionCallOutput(msg) from e
@@ -103,7 +112,7 @@ def format_contract_call_return_data_curried(
     )
     normalized_data = map_abi_data(_normalizers, output_types, output_data)
 
-    if decode_tuples:
+    if decode_tuples and fn_abi["type"] == "function":
         decoded = named_tree(fn_abi["outputs"], normalized_data)
         normalized_data = recursive_dict_to_namedtuple(decoded)
 
@@ -114,11 +123,11 @@ def call_contract_function(
     w3: "Web3",
     address: ChecksumAddress,
     normalizers: Tuple[Callable[..., Any], ...],
-    function_identifier: FunctionIdentifier,
+    abi_element_identifier: ABIElementIdentifier,
     transaction: TxParams,
     block_id: Optional[BlockIdentifier] = None,
     contract_abi: Optional[ABI] = None,
-    fn_abi: Optional[ABIFunction] = None,
+    abi_callable: Optional[ABICallable] = None,
     state_override: Optional[StateOverride] = None,
     ccip_read_enabled: Optional[bool] = None,
     decode_tuples: Optional[bool] = False,
@@ -132,9 +141,9 @@ def call_contract_function(
     call_transaction = prepare_transaction(
         address,
         w3,
-        fn_identifier=function_identifier,
+        abi_element_identifier=abi_element_identifier,
         contract_abi=contract_abi,
-        fn_abi=fn_abi,
+        abi_callable=abi_callable,
         transaction=transaction,
         fn_args=args,
         fn_kwargs=kwargs,
@@ -147,17 +156,27 @@ def call_contract_function(
         ccip_read_enabled=ccip_read_enabled,
     )
 
-    if fn_abi is None:
-        fn_abi = find_matching_fn_abi(
-            contract_abi, w3.codec, function_identifier, args, kwargs
+    if abi_callable is None:
+        abi_callable = cast(
+            ABIFunction,
+            get_abi_element(
+                contract_abi,
+                abi_element_identifier,
+                *args,
+                abi_codec=w3.codec,
+                **kwargs,
+            ),
         )
 
-    output_types = get_abi_output_types(fn_abi)
+    # get the output types, which only exist for function types
+    output_types = []
+    if abi_callable["type"] == "function":
+        output_types = get_abi_output_types(abi_callable)
 
     provider = w3.provider
     if hasattr(provider, "_is_batching") and provider._is_batching:
-        # request_information == ((method, params), response_formatters)
-        request_information = tuple(return_data)
+        BatchingReturnData: TypeAlias = Tuple[Tuple[RPCEndpoint, Any], Tuple[Any, ...]]
+        request_information = tuple(cast(BatchingReturnData, return_data))
         method_and_params = request_information[0]
 
         # append return data formatting to result formatters
@@ -168,8 +187,8 @@ def call_contract_function(
             format_contract_call_return_data_curried(
                 w3,
                 decode_tuples,
-                fn_abi,
-                function_identifier,
+                abi_callable,
+                abi_element_identifier,
                 normalizers,
                 output_types,
             ),
@@ -198,7 +217,7 @@ def call_contract_function(
             )
         else:
             msg = (
-                f"Could not decode contract function call to {function_identifier} "
+                f"Could not decode contract function call to {abi_element_identifier} "
                 f"with return data: {str(return_data)}, output_types: {output_types}"
             )
         raise BadFunctionCallOutput(msg) from e
@@ -209,8 +228,8 @@ def call_contract_function(
     )
     normalized_data = map_abi_data(_normalizers, output_types, output_data)
 
-    if decode_tuples:
-        decoded = named_tree(fn_abi["outputs"], normalized_data)
+    if decode_tuples and abi_callable["type"] == "function":
+        decoded = named_tree(abi_callable["outputs"], normalized_data)
         normalized_data = recursive_dict_to_namedtuple(decoded)
 
     if len(normalized_data) == 1:
@@ -222,7 +241,7 @@ def call_contract_function(
 def transact_with_contract_function(
     address: ChecksumAddress,
     w3: "Web3",
-    function_name: Optional[FunctionIdentifier] = None,
+    abi_element_identifier: Optional[ABIElementIdentifier] = None,
     transaction: Optional[TxParams] = None,
     contract_abi: Optional[ABI] = None,
     fn_abi: Optional[ABIFunction] = None,
@@ -236,10 +255,10 @@ def transact_with_contract_function(
     transact_transaction = prepare_transaction(
         address,
         w3,
-        fn_identifier=function_name,
+        abi_element_identifier=abi_element_identifier,
         contract_abi=contract_abi,
         transaction=transaction,
-        fn_abi=fn_abi,
+        abi_callable=fn_abi,
         fn_args=args,
         fn_kwargs=kwargs,
     )
@@ -251,7 +270,7 @@ def transact_with_contract_function(
 def estimate_gas_for_function(
     address: ChecksumAddress,
     w3: "Web3",
-    fn_identifier: Optional[FunctionIdentifier] = None,
+    abi_element_identifier: Optional[ABIElementIdentifier] = None,
     transaction: Optional[TxParams] = None,
     contract_abi: Optional[ABI] = None,
     fn_abi: Optional[ABIFunction] = None,
@@ -269,9 +288,9 @@ def estimate_gas_for_function(
     estimate_transaction = prepare_transaction(
         address,
         w3,
-        fn_identifier=fn_identifier,
+        abi_element_identifier=abi_element_identifier,
         contract_abi=contract_abi,
-        fn_abi=fn_abi,
+        abi_callable=fn_abi,
         transaction=transaction,
         fn_args=args,
         fn_kwargs=kwargs,
@@ -283,7 +302,7 @@ def estimate_gas_for_function(
 def build_transaction_for_function(
     address: ChecksumAddress,
     w3: "Web3",
-    function_name: Optional[FunctionIdentifier] = None,
+    abi_element_identifier: Optional[ABIElementIdentifier] = None,
     transaction: Optional[TxParams] = None,
     contract_abi: Optional[ABI] = None,
     fn_abi: Optional[ABIFunction] = None,
@@ -299,9 +318,9 @@ def build_transaction_for_function(
     prepared_transaction = prepare_transaction(
         address,
         w3,
-        fn_identifier=function_name,
+        abi_element_identifier=abi_element_identifier,
         contract_abi=contract_abi,
-        fn_abi=fn_abi,
+        abi_callable=fn_abi,
         transaction=transaction,
         fn_args=args,
         fn_kwargs=kwargs,
@@ -319,14 +338,14 @@ def find_functions_by_identifier(
     callable_check: Callable[..., Any],
     function_type: Type[TContractFn],
 ) -> List[TContractFn]:
-    fns_abi = filter_by_type("function", contract_abi)
+    fns_abi = filter_abi_by_type("function", contract_abi)
     return [
         function_type.factory(
             fn_abi["name"],
             w3=w3,
             contract_abi=contract_abi,
             address=address,
-            function_identifier=fn_abi["name"],
+            abi_element_identifier=fn_abi["name"],
             abi=fn_abi,
         )
         for fn_abi in fns_abi
@@ -353,7 +372,7 @@ async def async_call_contract_function(
     async_w3: "AsyncWeb3",
     address: ChecksumAddress,
     normalizers: Tuple[Callable[..., Any], ...],
-    function_identifier: FunctionIdentifier,
+    abi_element_identifier: ABIElementIdentifier,
     transaction: TxParams,
     block_id: Optional[BlockIdentifier] = None,
     contract_abi: Optional[ABI] = None,
@@ -371,9 +390,9 @@ async def async_call_contract_function(
     call_transaction = prepare_transaction(
         address,
         async_w3,
-        fn_identifier=function_identifier,
+        abi_element_identifier=abi_element_identifier,
         contract_abi=contract_abi,
-        fn_abi=fn_abi,
+        abi_callable=fn_abi,
         transaction=transaction,
         fn_args=args,
         fn_kwargs=kwargs,
@@ -387,18 +406,28 @@ async def async_call_contract_function(
     )
 
     if fn_abi is None:
-        fn_abi = find_matching_fn_abi(
-            contract_abi, async_w3.codec, function_identifier, args, kwargs
+        fn_abi = cast(
+            ABIFunction,
+            get_abi_element(
+                contract_abi,
+                abi_element_identifier,
+                *args,
+                abi_codec=async_w3.codec,
+                **kwargs,
+            ),
         )
 
-    output_types = get_abi_output_types(fn_abi)
+    # get the output types, which only exist for function types
+    output_types = []
+    if fn_abi["type"] == "function":
+        output_types = get_abi_output_types(fn_abi)
 
     if async_w3.provider._is_batching:
         contract_call_return_data_formatter = format_contract_call_return_data_curried(
             async_w3,
             decode_tuples,
             fn_abi,
-            function_identifier,
+            abi_element_identifier,
             normalizers,
             output_types,
         )
@@ -410,8 +439,10 @@ async def async_call_contract_function(
                 current_request_id, contract_call_return_data_formatter
             )
         else:
-            # request_information == ((method, params), response_formatters)
-            request_information = tuple(return_data)
+            BatchingReturnData: TypeAlias = Tuple[
+                Tuple[RPCEndpoint, Any], Tuple[Any, ...]
+            ]
+            request_information = tuple(cast(BatchingReturnData, return_data))
             method_and_params = request_information[0]
 
             # append return data formatter to result formatters
@@ -446,7 +477,7 @@ async def async_call_contract_function(
             )
         else:
             msg = (
-                f"Could not decode contract function call to {function_identifier} "
+                f"Could not decode contract function call to {abi_element_identifier} "
                 f"with return data: {str(return_data)}, output_types: {output_types}"
             )
         raise BadFunctionCallOutput(msg) from e
@@ -467,7 +498,7 @@ async def async_call_contract_function(
 async def async_transact_with_contract_function(
     address: ChecksumAddress,
     async_w3: "AsyncWeb3",
-    function_name: Optional[FunctionIdentifier] = None,
+    abi_element_identifier: Optional[ABIElementIdentifier] = None,
     transaction: Optional[TxParams] = None,
     contract_abi: Optional[ABI] = None,
     fn_abi: Optional[ABIFunction] = None,
@@ -481,10 +512,10 @@ async def async_transact_with_contract_function(
     transact_transaction = prepare_transaction(
         address,
         async_w3,
-        fn_identifier=function_name,
+        abi_element_identifier=abi_element_identifier,
         contract_abi=contract_abi,
         transaction=transaction,
-        fn_abi=fn_abi,
+        abi_callable=fn_abi,
         fn_args=args,
         fn_kwargs=kwargs,
     )
@@ -496,7 +527,7 @@ async def async_transact_with_contract_function(
 async def async_estimate_gas_for_function(
     address: ChecksumAddress,
     async_w3: "AsyncWeb3",
-    fn_identifier: Optional[FunctionIdentifier] = None,
+    abi_element_identifier: Optional[ABIElementIdentifier] = None,
     transaction: Optional[TxParams] = None,
     contract_abi: Optional[ABI] = None,
     fn_abi: Optional[ABIFunction] = None,
@@ -514,9 +545,9 @@ async def async_estimate_gas_for_function(
     estimate_transaction = prepare_transaction(
         address,
         async_w3,
-        fn_identifier=fn_identifier,
+        abi_element_identifier=abi_element_identifier,
         contract_abi=contract_abi,
-        fn_abi=fn_abi,
+        abi_callable=fn_abi,
         transaction=transaction,
         fn_args=args,
         fn_kwargs=kwargs,
@@ -530,7 +561,7 @@ async def async_estimate_gas_for_function(
 async def async_build_transaction_for_function(
     address: ChecksumAddress,
     async_w3: "AsyncWeb3",
-    function_name: Optional[FunctionIdentifier] = None,
+    abi_element_identifier: Optional[ABIElementIdentifier] = None,
     transaction: Optional[TxParams] = None,
     contract_abi: Optional[ABI] = None,
     fn_abi: Optional[ABIFunction] = None,
@@ -546,9 +577,9 @@ async def async_build_transaction_for_function(
     prepared_transaction = prepare_transaction(
         address,
         async_w3,
-        fn_identifier=function_name,
+        abi_element_identifier=abi_element_identifier,
         contract_abi=contract_abi,
-        fn_abi=fn_abi,
+        abi_callable=fn_abi,
         transaction=transaction,
         fn_args=args,
         fn_kwargs=kwargs,

web3/datastructures.py

@@ -182,7 +182,7 @@ class NamedElementOnion(Mapping[TKey, TValue]):
         if name is None:
             name = cast(TKey, element)
 
-        name = self._repr_if_not_hashable(name)
+        name = self._build_name(name)
 
         if name in self._queue:
             if name is element:
@@ -219,7 +219,7 @@ class NamedElementOnion(Mapping[TKey, TValue]):
             if name is None:
                 name = cast(TKey, element)
 
-            name = self._repr_if_not_hashable(name)
+            name = self._build_name(name)
 
             self._queue.move_to_end(name, last=False)
         elif layer == len(self._queue):
@@ -233,7 +233,7 @@ class NamedElementOnion(Mapping[TKey, TValue]):
         self._queue.clear()
 
     def replace(self, old: TKey, new: TKey) -> TValue:
-        old_name = self._repr_if_not_hashable(old)
+        old_name = self._build_name(old)
 
         if old_name not in self._queue:
             raise Web3ValueError(
@@ -248,15 +248,25 @@ class NamedElementOnion(Mapping[TKey, TValue]):
             self._queue[old_name] = new
         return to_be_replaced
 
-    def _repr_if_not_hashable(self, value: TKey) -> TKey:
+    @staticmethod
+    def _build_name(value: TKey) -> TKey:
         try:
             value.__hash__()
+            return value
         except TypeError:
-            value = cast(TKey, repr(value))
-        return value
+            # unhashable, unnamed elements
+            if not callable(value):
+                raise Web3TypeError(
+                    f"Expected a callable or hashable type, got {type(value)}"
+                )
+            # This will either be ``Web3Middleware`` class or the ``build`` method of a
+            # ``Web3MiddlewareBuilder``. Instantiate with empty ``Web3`` and use a
+            # unique identifier with the ``__hash__()`` as the name.
+            v = value(None)
+            return cast(TKey, f"{v.__class__}<{v.__hash__()}>")
 
     def remove(self, old: TKey) -> None:
-        old_name = self._repr_if_not_hashable(old)
+        old_name = self._build_name(old)
         if old_name not in self._queue:
             raise Web3ValueError("You can only remove something that has been added")
         del self._queue[old_name]
@@ -270,8 +280,8 @@ class NamedElementOnion(Mapping[TKey, TValue]):
         return [(val, key) for key, val in reversed(self._queue.items())]
 
     def _replace_with_new_name(self, old: TKey, new: TKey) -> None:
-        old_name = self._repr_if_not_hashable(old)
-        new_name = self._repr_if_not_hashable(new)
+        old_name = self._build_name(old)
+        new_name = self._build_name(new)
 
         self._queue[new_name] = new
         found_old = False
@@ -293,11 +303,11 @@ class NamedElementOnion(Mapping[TKey, TValue]):
         return NamedElementOnion(cast(List[Any], combined.items()))
 
     def __contains__(self, element: Any) -> bool:
-        element_name = self._repr_if_not_hashable(element)
+        element_name = self._build_name(element)
         return element_name in self._queue
 
     def __getitem__(self, element: TKey) -> TValue:
-        element_name = self._repr_if_not_hashable(element)
+        element_name = self._build_name(element)
         return self._queue[element_name]
 
     def __len__(self) -> int:

web3/eth/async_eth.py

@@ -732,8 +732,7 @@ class AsyncEth(BaseEth):
     # -- contract methods -- #
 
     @overload
-    # mypy error: Overloaded function signatures 1 and 2 overlap with incompatible return types  # noqa: E501
-    def contract(self, address: None = None, **kwargs: Any) -> Type[AsyncContract]:  # type: ignore[overload-overlap]  # noqa: E501
+    def contract(self, address: None = None, **kwargs: Any) -> Type[AsyncContract]:
         ...
 
     @overload

web3/eth/eth.py

@@ -629,8 +629,7 @@ class Eth(BaseEth):
     )
 
     @overload
-    # type error: Overloaded function signatures 1 and 2 overlap with incompatible return types  # noqa: E501
-    def contract(self, address: None = None, **kwargs: Any) -> Type[Contract]:  # type: ignore[overload-overlap]  # noqa: E501
+    def contract(self, address: None = None, **kwargs: Any) -> Type[Contract]:
         ...
 
     @overload

web3/exceptions.py

@@ -8,10 +8,6 @@ from typing import (
     Union,
 )
 
-from eth_utils import (
-    ValidationError,
-)
-
 from web3.types import (
     BlockData,
     RPCResponse,
@@ -164,7 +160,7 @@ class MismatchedABI(Web3Exception):
     """
 
 
-class ABIEventFunctionNotFound(AttributeError, MismatchedABI):
+class ABIEventNotFound(AttributeError, MismatchedABI):
     """
     Raised when an attempt is made to access an event
     that does not exist in the ABI.
@@ -178,14 +174,25 @@ class ABIFunctionNotFound(AttributeError, MismatchedABI):
     """
 
 
-class FallbackNotFound(Web3Exception):
+class ABIConstructorNotFound(Web3Exception):
+    """
+    Raised when a constructor function doesn't exist in contract.
+    """
+
+
+class ABIFallbackNotFound(Web3Exception):
+    """
+    Raised when a fallback function doesn't exist in contract.
+    """
+
+
+class ABIReceiveNotFound(Web3Exception):
     """
-    Raised when fallback function doesn't exist in contract.
+    Raised when a receive function doesn't exist in contract.
     """
 
 
-# type ignored because subclassing ValidationError which has type Any
-class Web3ValidationError(Web3Exception, ValidationError):  # type: ignore[misc]
+class Web3ValidationError(Web3Exception):
     """
     Raised when a supplied value is invalid.
     """
@@ -364,6 +371,12 @@ class MethodUnavailable(Web3RPCError):
     """
 
 
+class RequestTimedOut(Web3RPCError):
+    """
+    Raised when a request to the node times out.
+    """
+
+
 class TransactionNotFound(Web3RPCError):
     """
     Raised when a tx hash used to look up a tx in a jsonrpc call cannot be found.

web3/gas_strategies/time_based.py

@@ -5,6 +5,7 @@ from typing import (
     Iterable,
     Sequence,
     Tuple,
+    cast,
 )
 
 from eth_typing import (
@@ -35,6 +36,7 @@ from web3.exceptions import (
 from web3.types import (
     BlockNumber,
     GasPriceStrategy,
+    TxData,
     TxParams,
     Wei,
 )
@@ -84,6 +86,7 @@ def _get_raw_miner_data(
     latest = w3.eth.get_block("latest", full_transactions=True)
 
     for transaction in latest["transactions"]:
+        transaction = cast(TxData, transaction)
         yield (latest["miner"], latest["hash"], transaction["gasPrice"])
 
     block = latest
@@ -96,6 +99,7 @@ def _get_raw_miner_data(
         # block numbers to make caching the data easier to implement.
         block = w3.eth.get_block(block["parentHash"], full_transactions=True)
         for transaction in block["transactions"]:
+            transaction = cast(TxData, transaction)
             yield (block["miner"], block["hash"], transaction["gasPrice"])
 
 

web3/manager.py

@@ -37,6 +37,7 @@ from web3.exceptions import (
     BadResponseFormat,
     MethodUnavailable,
     ProviderConnectionError,
+    RequestTimedOut,
     TaskNotRunning,
     Web3RPCError,
     Web3TypeError,
@@ -89,6 +90,13 @@ if TYPE_CHECKING:
 
 
 NULL_RESPONSES = [None, HexBytes("0x"), "0x"]
+KNOWN_REQUEST_TIMEOUT_MESSAGING = {
+    # Note: It's important to be very explicit here and not too broad. We don't want
+    # to accidentally catch a message that is not for a request timeout. In the worst
+    # case, we raise something more generic like `Web3RPCError`. JSON-RPC unfortunately
+    # has not standardized error codes for request timeouts.
+    "request timed out",  # go-ethereum
+}
 METHOD_NOT_FOUND = -32601
 
 
@@ -185,6 +193,7 @@ def _validate_response(
             response, 'Response must include either "error" or "result".'
         )
     elif "error" in response:
+        web3_rpc_error: Optional[Web3RPCError] = None
         error = response["error"]
 
         # raise the error when the value is a string
@@ -195,6 +204,13 @@ def _validate_response(
                 "JSON-RPC 2.0 specification.",
             )
 
+        # errors must include a message
+        error_message = error.get("message")
+        if not isinstance(error_message, str):
+            _raise_bad_response_format(
+                response, 'error["message"] is required and must be a string value.'
+            )
+
         # errors must include an integer code
         code = error.get("code")
         if not isinstance(code, int):
@@ -202,7 +218,7 @@ def _validate_response(
                 response, 'error["code"] is required and must be an integer value.'
             )
         elif code == METHOD_NOT_FOUND:
-            exception = MethodUnavailable(
+            web3_rpc_error = MethodUnavailable(
                 repr(error),
                 rpc_response=response,
                 user_message=(
@@ -211,20 +227,26 @@ def _validate_response(
                     "currently enabled."
                 ),
             )
-            logger.error(exception.user_message)
-            logger.debug(f"RPC error response: {response}")
-            raise exception
-
-        # errors must include a message
-        error_message = error.get("message")
-        if not isinstance(error_message, str):
-            _raise_bad_response_format(
-                response, 'error["message"] is required and must be a string value.'
+        elif any(
+            # parse specific timeout messages
+            timeout_str in error_message.lower()
+            for timeout_str in KNOWN_REQUEST_TIMEOUT_MESSAGING
+        ):
+            web3_rpc_error = RequestTimedOut(
+                repr(error),
+                rpc_response=response,
+                user_message=(
+                    "The request timed out. Check the connection to your node and "
+                    "try again."
+                ),
             )
 
-        apply_error_formatters(error_formatters, response)
+        if web3_rpc_error is None:
+            # if no condition was met above, raise a more generic `Web3RPCError`
+            web3_rpc_error = Web3RPCError(repr(error), rpc_response=response)
+
+        response = apply_error_formatters(error_formatters, response)
 
-        web3_rpc_error = Web3RPCError(repr(error), rpc_response=response)
         logger.error(web3_rpc_error.user_message)
         logger.debug(f"RPC error response: {response}")
         raise web3_rpc_error