web3 7.5.0__py3-none-any.whl → 7.6.1__py3-none-any.whl

web3/utils/abi.py

@@ -1,6 +1,7 @@
 import functools
 from typing import (
     Any,
+    Callable,
     Dict,
     List,
     Optional,
@@ -31,6 +32,16 @@ from eth_typing import (
     HexStr,
     Primitives,
 )
+from eth_utils.abi import (
+    abi_to_signature,
+    event_abi_to_log_topic,
+    filter_abi_by_name,
+    filter_abi_by_type,
+    function_abi_to_4byte_selector,
+    get_abi_input_types,
+    get_aligned_abi_inputs,
+    get_normalized_abi_inputs,
+)
 from eth_utils.address import (
     is_binary_address,
     is_checksum_address,
@@ -47,7 +58,6 @@ from eth_utils.toolz import (
 )
 from eth_utils.types import (
     is_list_like,
-    is_text,
 )
 from hexbytes import (
     HexBytes,
@@ -55,17 +65,20 @@ from hexbytes import (
 
 from web3._utils.abi import (
     filter_by_argument_name,
+    get_abi_element_signature,
+    get_name_from_abi_element_identifier,
+)
+from web3._utils.decorators import (
+    deprecated_for,
 )
-from web3._utils.abi_element_identifiers import (
-    FallbackFn,
-    ReceiveFn,
+from web3._utils.validation import (
+    validate_abi,
 )
 from web3.exceptions import (
     ABIConstructorNotFound,
     ABIFallbackNotFound,
     ABIReceiveNotFound,
     MismatchedABI,
-    Web3TypeError,
     Web3ValidationError,
     Web3ValueError,
 )
@@ -73,15 +86,9 @@ from web3.types import (
     ABIElementIdentifier,
 )
 
-from eth_utils.abi import (  # noqa
-    abi_to_signature,
-    event_abi_to_log_topic,
-    filter_abi_by_name,
-    filter_abi_by_type,
-    function_abi_to_4byte_selector,
-    get_aligned_abi_inputs,
-    get_normalized_abi_inputs,
-)
+
+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(
@@ -98,9 +105,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 +165,121 @@ 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, elements: Sequence[ABIElement]
+) -> str:
+    """
+    Find an ABI identifier signature by element name. A signature identifier is
+    returned, "name(arg1Type,arg2Type,...)".
+
+    If multiple ABIs match the name and every one contain arguments, the first
+    result is returned. Otherwise the signature without arguments is returned.
+    Returns None if no ABI exists with the provided name.
+    """
+    element_signatures_with_name = [
+        abi_to_signature(element)
+        for element in elements
+        if element.get("name", "") == get_name_from_abi_element_identifier(element_name)
+    ]
+
+    if len(element_signatures_with_name) == 1:
+        return element_signatures_with_name[0]
+    elif len(element_signatures_with_name) > 1:
+        # Check for function signature without args
+        signature_without_args = f"{element_name}()"
+        if signature_without_args not in element_signatures_with_name:
+            # Element without arguments not found, use the first available signature
+            return element_signatures_with_name[0]
+        else:
+            return signature_without_args
+    else:
+        return None
+
+
+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 +287,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 +373,84 @@ def _get_argument_readable_type(arg: Any) -> str:
     return arg.__class__.__name__
 
 
+def _build_abi_filters(
+    abi_element_identifier: ABIElementIdentifier,
+    *args: Optional[Any],
+    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]]] = []
+
+    arg_count = 0
+    if args or kwargs:
+        arg_count = len(args) + len(kwargs)
+
+    # Filter by arg count only if the identifier contains arguments
+    if "()" not in abi_element_identifier and arg_count:
+        filters.append(functools.partial(_filter_by_argument_count, arg_count))
+
+    if arg_count > 0:
+        filters.append(
+            functools.partial(
+                filter_abi_by_name,
+                get_name_from_abi_element_identifier(abi_element_identifier),
+            )
+        )
+
+        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 "(" 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 +526,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 +548,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 +585,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 unless one match is 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 +682,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/utils/address.py

@@ -9,6 +9,9 @@ from eth_utils import (
 )
 import rlp
 
+from web3.exceptions import (
+    Web3ValidationError,
+)
 from web3.types import (
     HexStr,
     Nonce,
@@ -30,6 +33,11 @@ def get_create2_address(
     Determine the resulting `CREATE2` opcode contract address for a sender, salt and
     bytecode.
     """
+    if len(to_bytes(hexstr=salt)) != 32:
+        raise Web3ValidationError(
+            f"`salt` must be 32 bytes, {len(to_bytes(hexstr=salt))} != 32"
+        )
+
     contract_address = keccak(
         b"\xff"
         + to_bytes(hexstr=sender)

{web3-7.5.0.dist-info → web3-7.6.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: web3
-Version: 7.5.0
+Version: 7.6.1
 Summary: web3: A Python library for interacting with Ethereum
 Home-page: https://github.com/ethereum/web3.py
 Author: The Ethereum Foundation
@@ -32,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
@@ -56,8 +56,8 @@ Requires-Dist: hypothesis >=3.31.2 ; extra == 'dev'
 Requires-Dist: tox >=4.0.0 ; extra == 'dev'
 Requires-Dist: mypy ==1.10.0 ; extra == 'dev'
 Requires-Dist: pre-commit >=3.4.0 ; extra == 'dev'
-Requires-Dist: eth-tester[py-evm] <0.13.0b1,>=0.11.0b1 ; extra == 'dev'
-Requires-Dist: py-geth >=5.0.0 ; extra == 'dev'
+Requires-Dist: eth-tester[py-evm] <0.13.0b1,>=0.12.0b1 ; extra == 'dev'
+Requires-Dist: py-geth >=5.1.0 ; extra == 'dev'
 Provides-Extra: docs
 Requires-Dist: sphinx >=6.0.0 ; extra == 'docs'
 Requires-Dist: sphinx-autobuild >=2021.3.14 ; extra == 'docs'
@@ -73,11 +73,11 @@ Requires-Dist: hypothesis >=3.31.2 ; extra == 'test'
 Requires-Dist: tox >=4.0.0 ; extra == 'test'
 Requires-Dist: mypy ==1.10.0 ; extra == 'test'
 Requires-Dist: pre-commit >=3.4.0 ; extra == 'test'
-Requires-Dist: eth-tester[py-evm] <0.13.0b1,>=0.11.0b1 ; extra == 'test'
-Requires-Dist: py-geth >=5.0.0 ; extra == 'test'
+Requires-Dist: eth-tester[py-evm] <0.13.0b1,>=0.12.0b1 ; extra == 'test'
+Requires-Dist: py-geth >=5.1.0 ; extra == 'test'
 Provides-Extra: tester
-Requires-Dist: eth-tester[py-evm] <0.13.0b1,>=0.11.0b1 ; extra == 'tester'
-Requires-Dist: py-geth >=5.0.0 ; extra == 'tester'
+Requires-Dist: eth-tester[py-evm] <0.13.0b1,>=0.12.0b1 ; extra == 'tester'
+Requires-Dist: py-geth >=5.1.0 ; extra == 'tester'
 
 # web3.py