web3 7.4.0__py3-none-any.whl → 7.6.0__py3-none-any.whl

web3/providers/eth_tester/defaults.py

@@ -246,6 +246,7 @@ API_ENDPOINTS = {
         "chainId": static_return(131277322940537),  # from fixture generation file
         "feeHistory": call_eth_tester("get_fee_history"),
         "maxPriorityFeePerGas": static_return(10**9),
+        "blobBaseFee": static_return(10**9),
         "gasPrice": static_return(10**9),  # must be >= base fee post-London
         "accounts": call_eth_tester("get_accounts"),
         "blockNumber": compose(

web3/types.py

@@ -36,8 +36,14 @@ from web3._utils.compat import (
 )
 
 if TYPE_CHECKING:
-    from web3.contract.async_contract import AsyncContractFunction  # noqa: F401
-    from web3.contract.contract import ContractFunction  # noqa: F401
+    from web3.contract.async_contract import (  # noqa: F401
+        AsyncContractEvent,
+        AsyncContractFunction,
+    )
+    from web3.contract.contract import (  # noqa: F401
+        ContractEvent,
+        ContractFunction,
+    )
     from web3.main import (  # noqa: F401
         AsyncWeb3,
         Web3,
@@ -469,6 +475,84 @@ class TxPoolStatus(TypedDict, total=False):
     queued: int
 
 
+#
+# debug types
+#
+class TraceConfig(TypedDict, total=False):
+    disableStorage: bool
+    disableStack: bool
+    enableMemory: bool
+    enableReturnData: bool
+    tracer: str
+    tracerConfig: Dict[str, Any]
+    timeout: int
+
+
+class CallTraceLog(TypedDict):
+    address: ChecksumAddress
+    data: HexBytes
+    topics: Sequence[HexBytes]
+    position: int
+
+
+# syntax b/c "from" keyword not allowed w/ class construction
+CallTrace = TypedDict(
+    "CallTrace",
+    {
+        "type": str,
+        "from": ChecksumAddress,
+        "to": ChecksumAddress,
+        "value": Wei,
+        "gas": int,
+        "gasUsed": int,
+        "input": HexBytes,
+        "output": HexBytes,
+        "error": str,
+        "revertReason": str,
+        "calls": Sequence["CallTrace"],
+        "logs": Sequence[CallTraceLog],
+    },
+    total=False,
+)
+
+
+class TraceData(TypedDict, total=False):
+    balance: int
+    nonce: int
+    code: str
+    storage: Dict[str, str]
+
+
+class DiffModeTrace(TypedDict):
+    post: Dict[ChecksumAddress, TraceData]
+    pre: Dict[ChecksumAddress, TraceData]
+
+
+PrestateTrace = Dict[ChecksumAddress, TraceData]
+
+
+# 4byte tracer returns something like:
+# { '0x27dc297e-128' : 1 }
+# which is: { 4byte signature - calldata size : # of occurrences of key }
+FourByteTrace = Dict[str, int]
+
+
+class StructLog(TypedDict):
+    pc: int
+    op: str
+    gas: int
+    gasCost: int
+    depth: int
+    stack: List[HexStr]
+
+
+class OpcodeTrace(TypedDict, total=False):
+    gas: int
+    failed: bool
+    returnValue: str
+    structLogs: List[StructLog]
+
+
 #
 # web3.geth types
 #
@@ -483,6 +567,7 @@ class GethWallet(TypedDict):
 # Contract types
 
 TContractFn = TypeVar("TContractFn", "ContractFunction", "AsyncContractFunction")
+TContractEvent = TypeVar("TContractEvent", "ContractEvent", "AsyncContractEvent")
 
 
 # Tracing types

web3/utils/abi.py

@@ -1,6 +1,7 @@
 import functools
 from typing import (
     Any,
+    Callable,
     Dict,
     List,
     Optional,
@@ -47,7 +48,6 @@ from eth_utils.toolz import (
 )
 from eth_utils.types import (
     is_list_like,
-    is_text,
 )
 from hexbytes import (
     HexBytes,
@@ -55,17 +55,21 @@ from hexbytes import (
 
 from web3._utils.abi import (
     filter_by_argument_name,
+    filter_by_argument_type,
+    get_abi_element_signature,
+    get_name_from_abi_element_identifier,
 )
-from web3._utils.abi_element_identifiers import (
-    FallbackFn,
-    ReceiveFn,
+from web3._utils.decorators import (
+    deprecated_for,
+)
+from web3._utils.validation import (
+    validate_abi,
 )
 from web3.exceptions import (
     ABIConstructorNotFound,
     ABIFallbackNotFound,
     ABIReceiveNotFound,
     MismatchedABI,
-    Web3TypeError,
     Web3ValidationError,
     Web3ValueError,
 )
@@ -81,9 +85,14 @@ from eth_utils.abi import (  # noqa
     function_abi_to_4byte_selector,
     get_aligned_abi_inputs,
     get_normalized_abi_inputs,
+    get_abi_input_types,
 )
 
 
+def _filter_by_signature(signature: str, contract_abi: ABI) -> List[ABIElement]:
+    return [abi for abi in contract_abi if abi_to_signature(abi) == signature]
+
+
 def _filter_by_argument_count(
     num_arguments: int, contract_abi: ABI
 ) -> List[ABIElement]:
@@ -98,9 +107,9 @@ def _filter_by_argument_count(
 
 def _filter_by_encodability(
     abi_codec: codec.ABIEncoder,
+    args: Sequence[Any],
+    kwargs: Dict[str, Any],
     contract_abi: ABI,
-    *args: Optional[Sequence[Any]],
-    **kwargs: Optional[Dict[str, Any]],
 ) -> List[ABICallable]:
     return [
         cast(ABICallable, function_abi)
@@ -158,13 +167,118 @@ def _get_fallback_function_abi(contract_abi: ABI) -> ABIFallback:
         raise ABIFallbackNotFound("No fallback function was found in the contract ABI.")
 
 
+def _get_any_abi_signature_with_name(element_name: str, contract_abi: ABI) -> str:
+    """
+    Find an ABI identifier signature by element name. A signature identifier is
+    returned, "name(arg1Type,arg2Type,...)".
+
+    This function forces one result to be returned even if multiple are found.
+    If multiple ABIs are found and all contain arguments, the first result is returned.
+    Otherwise when one of the ABIs has zero arguments, that signature is returned.
+    """
+    try:
+        # search for function abis with the same name
+        function_abi = get_abi_element(
+            contract_abi, get_name_from_abi_element_identifier(element_name)
+        )
+        return abi_to_signature(function_abi)
+    except MismatchedABI:
+        # If all matching functions have arguments, cannot determine which one
+        # to use. Instead of an exception, return the first matching function.
+        function_abis = filter_abi_by_name(element_name, contract_abi)
+        if len(function_abis) > 0 and all(
+            len(get_abi_input_types(fn)) > 0 for fn in function_abis
+        ):
+            return abi_to_signature(function_abis[0])
+
+        # Use signature for function that does not take arguments
+        return str(get_abi_element_signature(element_name))
+
+
+def _build_abi_input_error(
+    abi: ABI,
+    num_args: int,
+    *args: Any,
+    abi_codec: ABICodec,
+    **kwargs: Any,
+) -> str:
+    """
+    Build a string representation of the ABI input error.
+    """
+    errors: Dict[str, str] = dict(
+        {
+            "zero_args": "",
+            "invalid_args": "",
+            "encoding": "",
+            "unexpected_args": "",
+        }
+    )
+
+    for abi_element in abi:
+        abi_element_input_types = get_abi_input_types(abi_element)
+        abi_signature = abi_to_signature(abi_element)
+        abi_element_name = get_name_from_abi_element_identifier(abi_signature)
+        types: Tuple[str, ...] = tuple()
+        aligned_args: Tuple[Any, ...] = tuple()
+
+        if len(abi_element_input_types) == num_args:
+            if num_args == 0:
+                if not errors["zero_args"]:
+                    errors["zero_args"] += (
+                        "The provided identifier matches multiple elements.\n"
+                        f"If you meant to call `{abi_element_name}()`, "
+                        "please specify the full signature.\n"
+                    )
+
+                errors["zero_args"] += (
+                    f" - signature: {abi_to_signature(abi_element)}, "
+                    f"type: {abi_element['type']}\n"
+                )
+            else:
+                try:
+                    arguments = get_normalized_abi_inputs(abi_element, *args, **kwargs)
+                    types, aligned_args = get_aligned_abi_inputs(abi_element, arguments)
+                except TypeError as e:
+                    errors["invalid_args"] += (
+                        f"Signature: {abi_signature}, type: {abi_element['type']}\n"
+                        f"Arguments do not match types in `{abi_signature}`.\n"
+                        f"Error: {e}\n"
+                    )
+
+            argument_errors = ""
+            for position, (_type, arg) in enumerate(zip(types, aligned_args), start=1):
+                if abi_codec.is_encodable(_type, arg):
+                    argument_errors += f"Argument {position} value `{arg}` is valid.\n"
+                else:
+                    argument_errors += (
+                        f"Argument {position} value `{arg}` is not compatible with "
+                        f"type `{_type}`.\n"
+                    )
+
+            if argument_errors != "":
+                errors["encoding"] += (
+                    f"Signature: {abi_signature}, type: {abi_element['type']}\n"
+                    + argument_errors
+                )
+
+        else:
+            errors["unexpected_args"] += (
+                f"Signature: {abi_signature}, type: {abi_element['type']}\n"
+                f"Expected {len(abi_element_input_types)} argument(s) but received "
+                f"{num_args} argument(s).\n"
+            )
+
+    return "".join(errors.values())
+
+
 def _mismatched_abi_error_diagnosis(
     abi_element_identifier: ABIElementIdentifier,
-    matching_function_signatures: Sequence[str],
-    arg_count_matches: int,
-    encoding_matches: int,
-    *args: Optional[Sequence[Any]],
-    **kwargs: Optional[Dict[str, Any]],
+    abi: ABI,
+    num_matches: int = 0,
+    num_args: int = 0,
+    *args: Optional[Any],
+    abi_codec: Optional[Any] = None,
+    **kwargs: Optional[Any],
 ) -> str:
     """
     Raise a ``MismatchedABI`` when a function ABI lookup results in an error.
@@ -172,32 +286,59 @@ def _mismatched_abi_error_diagnosis(
     An error may result from multiple functions matching the provided signature and
     arguments or no functions are identified.
     """
-    diagnosis = "\n"
-    if arg_count_matches == 0:
-        diagnosis += "Function invocation failed due to improper number of arguments."
-    elif encoding_matches == 0:
-        diagnosis += "Function invocation failed due to no matching argument types."
-    elif encoding_matches > 1:
-        diagnosis += (
-            "Ambiguous argument encoding. "
-            "Provided arguments can be encoded to multiple functions "
-            "matching this call."
-        )
+    name = get_name_from_abi_element_identifier(abi_element_identifier)
+    abis_matching_names = filter_abi_by_name(name, abi)
+    abis_matching_arg_count = [
+        abi_to_signature(abi)
+        for abi in _filter_by_argument_count(num_args, abis_matching_names)
+    ]
+    num_abis_matching_arg_count = len(abis_matching_arg_count)
 
-    collapsed_args = _extract_argument_types(*args)
-    collapsed_kwargs = dict(
-        {(k, _extract_argument_types([v])) for k, v in kwargs.items()}
-    )
+    if abi_codec is None:
+        abi_codec = ABICodec(default_registry)
 
-    return (
-        f"\nCould not identify the intended function with name "
-        f"`{abi_element_identifier}`, positional arguments with type(s) "
-        f"`({collapsed_args})` and keyword arguments with type(s) "
-        f"`{collapsed_kwargs}`."
-        f"\nFound {len(matching_function_signatures)} function(s) with the name "
-        f"`{abi_element_identifier}`: {matching_function_signatures}{diagnosis}"
+    error = "ABI Not Found!\n"
+    if num_matches == 0 and num_abis_matching_arg_count == 0:
+        error += f"No element named `{name}` with {num_args} argument(s).\n"
+    elif num_matches > 1 or num_abis_matching_arg_count > 1:
+        error += (
+            f"Found multiple elements named `{name}` that accept {num_args} "
+            "argument(s).\n"
+        )
+    elif num_abis_matching_arg_count == 1:
+        error += (
+            f"Found {num_abis_matching_arg_count} element(s) named `{name}` that "
+            f"accept {num_args} argument(s).\n"
+            "The provided arguments are not valid.\n"
+        )
+    elif num_matches == 0:
+        error += (
+            f"Unable to find an element named `{name}` that matches the provided "
+            "identifier and argument types.\n"
+        )
+    arg_types = _extract_argument_types(*args)
+    kwarg_types = dict({(k, _extract_argument_types([v])) for k, v in kwargs.items()})
+    error += (
+        f"Provided argument types: ({arg_types})\n"
+        f"Provided keyword argument types: {kwarg_types}\n\n"
     )
 
+    if abis_matching_names:
+        error += (
+            f"Tried to find a matching ABI element named `{name}`, but encountered "
+            "the following problems:\n"
+        )
+
+        error += _build_abi_input_error(
+            abis_matching_names,
+            num_args,
+            *args,
+            abi_codec=abi_codec,
+            **kwargs,
+        )
+
+    return f"\n{error}"
+
 
 def _extract_argument_types(*args: Sequence[Any]) -> str:
     """
@@ -231,6 +372,102 @@ def _get_argument_readable_type(arg: Any) -> str:
     return arg.__class__.__name__
 
 
+def _build_abi_filters(
+    abi_element_identifier: ABIElementIdentifier,
+    *args: Optional[Any],
+    abi_type: Optional[str] = None,
+    argument_names: Optional[Sequence[str]] = None,
+    argument_types: Optional[Sequence[str]] = None,
+    abi_codec: Optional[Any] = None,
+    **kwargs: Optional[Any],
+) -> List[Callable[..., Sequence[ABIElement]]]:
+    """
+    Build a list of ABI filters to find an ABI element within a contract ABI. Each
+    filter is a partial function that takes a contract ABI and returns a filtered list.
+    Each parameter is checked before applying the relevant filter.
+
+    When the ``abi_element_identifier`` is a function name or signature and no arguments
+    are provided, the returned filters include the function name or signature.
+
+    A function ABI may take arguments and keyword arguments. When the ``args`` and
+    ``kwargs`` values are passed, several filters are combined together. Available
+    filters include the function name, argument count, argument name, argument type,
+    and argument encodability.
+
+    ``constructor``, ``fallback``, and ``receive`` ABI elements are handled only with a
+    filter by type.
+    """
+    if not isinstance(abi_element_identifier, str):
+        abi_element_identifier = get_abi_element_signature(abi_element_identifier)
+
+    if abi_element_identifier in ["constructor", "fallback", "receive"]:
+        return [functools.partial(filter_abi_by_type, abi_element_identifier)]
+
+    filters: List[Callable[..., Sequence[ABIElement]]] = []
+
+    if abi_type:
+        filters.append(functools.partial(filter_abi_by_type, abi_type))
+
+    arg_count = 0
+    if argument_names:
+        arg_count = len(argument_names)
+    elif args or kwargs:
+        arg_count = len(args) + len(kwargs)
+
+    if arg_count > 0:
+        filters.append(
+            functools.partial(
+                filter_abi_by_name,
+                get_name_from_abi_element_identifier(abi_element_identifier),
+            )
+        )
+        filters.append(functools.partial(_filter_by_argument_count, arg_count))
+
+        if args or kwargs:
+            if abi_codec is None:
+                abi_codec = ABICodec(default_registry)
+
+            filters.append(
+                functools.partial(
+                    _filter_by_encodability,
+                    abi_codec,
+                    args,
+                    kwargs,
+                )
+            )
+
+        if argument_names:
+            filters.append(functools.partial(filter_by_argument_name, argument_names))
+
+            if argument_types:
+                if arg_count != len(argument_types):
+                    raise Web3ValidationError(
+                        "The number of argument names and types must match."
+                    )
+
+                filters.append(
+                    functools.partial(filter_by_argument_type, argument_types)
+                )
+
+        if "(" in abi_element_identifier:
+            filters.append(
+                functools.partial(_filter_by_signature, abi_element_identifier)
+            )
+    else:
+        filters.append(
+            functools.partial(
+                filter_abi_by_name,
+                get_name_from_abi_element_identifier(abi_element_identifier),
+            )
+        )
+        if "(" in abi_element_identifier:
+            filters.append(
+                functools.partial(_filter_by_signature, abi_element_identifier)
+            )
+
+    return filters
+
+
 def get_abi_element_info(
     abi: ABI,
     abi_element_identifier: ABIElementIdentifier,
@@ -306,16 +543,21 @@ def get_abi_element_info(
 def get_abi_element(
     abi: ABI,
     abi_element_identifier: ABIElementIdentifier,
-    *args: Optional[Sequence[Any]],
+    *args: Optional[Any],
     abi_codec: Optional[Any] = None,
-    **kwargs: Optional[Dict[str, Any]],
+    **kwargs: Optional[Any],
 ) -> ABIElement:
     """
-    Return the interface for an ``ABIElement`` which matches the provided identifier
-    and arguments.
+    Return the interface for an ``ABIElement`` from the ``abi`` that matches the
+    provided identifier and arguments.
+
+    ``abi`` may be a list of all ABI elements in a contract or a subset of elements.
+    Passing only functions or events can be useful when names are not deterministic.
+    For example, if names overlap between functions and events.
 
-    The ABI which matches the provided identifier, named arguments (``args``) and
-    keyword args (``kwargs``) will be returned.
+    The ``ABIElementIdentifier`` value may be a function name, signature, or a
+    ``FallbackFn`` or ``ReceiveFn``. When named arguments (``args``) and/or keyword args
+    (``kwargs``) are provided, they are included in the search filters.
 
     The `abi_codec` may be overridden if custom encoding and decoding is required. The
     default is used if no codec is provided. More details about customizations are in
@@ -323,7 +565,9 @@ def get_abi_element(
 
     :param abi: Contract ABI.
     :type abi: `ABI`
-    :param abi_element_identifier: Find an element ABI with matching identifier.
+    :param abi_element_identifier: Find an element ABI with matching identifier. The \
+    identifier may be a function name, signature, or ``FallbackFn`` or ``ReceiveFn``. \
+    A function signature is in the form ``name(arg1Type,arg2Type,...)``.
     :type abi_element_identifier: `ABIElementIdentifier`
     :param args: Find an element ABI with matching args.
     :type args: `Optional[Sequence[Any]]`
@@ -358,55 +602,38 @@ def get_abi_element(
 'type': 'uint256'}], 'payable': False, 'stateMutability': 'nonpayable', \
 'type': 'function'}
     """
+    validate_abi(abi)
+
     if abi_codec is None:
         abi_codec = ABICodec(default_registry)
 
-    if abi_element_identifier is FallbackFn or abi_element_identifier == "fallback":
-        return _get_fallback_function_abi(abi)
-
-    if abi_element_identifier is ReceiveFn or abi_element_identifier == "receive":
-        return _get_receive_function_abi(abi)
-
-    if abi_element_identifier is None or not is_text(abi_element_identifier):
-        raise Web3TypeError("Unsupported function identifier")
-
-    filtered_abis_by_name: Sequence[ABIElement]
-    if abi_element_identifier == "constructor":
-        filtered_abis_by_name = [_get_constructor_function_abi(abi)]
-    else:
-        filtered_abis_by_name = filter_abi_by_name(
-            cast(str, abi_element_identifier), abi
-        )
-
-    arg_count = len(args) + len(kwargs)
-    filtered_abis_by_arg_count = _filter_by_argument_count(
-        arg_count, filtered_abis_by_name
-    )
-
-    if not args and not kwargs and len(filtered_abis_by_arg_count) == 1:
-        return filtered_abis_by_arg_count[0]
-
-    elements_with_encodable_args = _filter_by_encodability(
-        abi_codec, filtered_abis_by_arg_count, *args, **kwargs
+    abi_element_matches: Sequence[ABIElement] = pipe(
+        abi,
+        *_build_abi_filters(
+            abi_element_identifier,
+            *args,
+            abi_codec=abi_codec,
+            **kwargs,
+        ),
     )
 
-    if len(elements_with_encodable_args) != 1:
-        matching_function_signatures = [
-            abi_to_signature(func) for func in filtered_abis_by_name
-        ]
+    num_matches = len(abi_element_matches)
 
+    # Raise MismatchedABI when more than one found
+    if num_matches != 1:
         error_diagnosis = _mismatched_abi_error_diagnosis(
             abi_element_identifier,
-            matching_function_signatures,
-            len(filtered_abis_by_arg_count),
-            len(elements_with_encodable_args),
+            abi,
+            num_matches,
+            len(args) + len(kwargs),
             *args,
+            abi_codec=abi_codec,
             **kwargs,
         )
 
         raise MismatchedABI(error_diagnosis)
 
-    return elements_with_encodable_args[0]
+    return abi_element_matches[0]
 
 
 def check_if_arguments_can_be_encoded(
@@ -472,12 +699,17 @@ def check_if_arguments_can_be_encoded(
     )
 
 
+@deprecated_for("get_abi_element")
 def get_event_abi(
     abi: ABI,
     event_name: str,
     argument_names: Optional[Sequence[str]] = None,
 ) -> ABIEvent:
     """
+    .. warning::
+        This function is deprecated. It is unable to distinguish between
+        overloaded events. Use ``get_abi_element`` instead.
+
     Find the event interface with the given name and/or arguments.
 
     :param abi: Contract ABI.

{web3-7.4.0.dist-info → web3-7.6.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: web3
-Version: 7.4.0
+Version: 7.6.0
 Summary: web3: A Python library for interacting with Ethereum
 Home-page: https://github.com/ethereum/web3.py
 Author: The Ethereum Foundation
@@ -17,6 +17,7 @@ Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Requires-Python: >=3.8, <4
 Description-Content-Type: text/markdown
 License-File: LICENSE
@@ -31,7 +32,7 @@ Requires-Dist: pydantic >=2.4.0
 Requires-Dist: requests >=2.23.0
 Requires-Dist: typing-extensions >=4.0.1
 Requires-Dist: types-requests >=2.0.0
-Requires-Dist: websockets >=10.0.0
+Requires-Dist: websockets <14.0.0,>=10.0.0
 Requires-Dist: pyunormalize >=15.0.0
 Requires-Dist: pywin32 >=223 ; platform_system == "Windows"
 Provides-Extra: dev