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

web3/contract/base_contract.py

@@ -4,6 +4,7 @@ from typing import (
     Callable,
     Collection,
     Dict,
+    Generic,
     Iterable,
     List,
     NoReturn,
@@ -58,7 +59,12 @@ from web3._utils.abi_element_identifiers import (
     FallbackFn,
     ReceiveFn,
 )
+from web3._utils.compat import (
+    Self,
+)
 from web3._utils.contracts import (
+    copy_contract_event,
+    copy_contract_function,
     decode_transaction_data,
     encode_abi,
     prepare_transaction,
@@ -98,6 +104,7 @@ from web3.exceptions import (
     InvalidEventABI,
     LogTopicError,
     MismatchedABI,
+    NoABIEventsFound,
     NoABIFound,
     NoABIFunctionsFound,
     Web3AttributeError,
@@ -117,12 +124,17 @@ from web3.types import (
     BlockIdentifier,
     EventData,
     FilterParams,
+    LogReceipt,
+    StateOverride,
+    TContractEvent,
     TContractFn,
     TxParams,
     TxReceipt,
 )
 from web3.utils.abi import (
+    _filter_by_argument_count,
     _get_any_abi_signature_with_name,
+    _mismatched_abi_error_diagnosis,
     check_if_arguments_can_be_encoded,
     get_abi_element,
     get_abi_element_info,
@@ -164,6 +176,7 @@ class BaseContractEvent:
     argument_types: Tuple[str, ...] = tuple()
     args: Any = None
     kwargs: Any = None
+    _topic: HexStr = None
 
     def __init__(self, *argument_names: str, abi: Optional[ABIEvent] = None) -> None:
         self.abi_element_identifier = type(self).__name__
@@ -187,6 +200,15 @@ class BaseContractEvent:
             return f"<Event {abi_to_signature(self.abi)}>"
         return f"<Event {get_abi_element_signature(self.abi_element_identifier)}>"
 
+    def __call__(self, *args: Any, **kwargs: Any) -> Self:
+        return copy_contract_event(self, *args, **kwargs)
+
+    @property
+    def topic(self) -> HexStr:
+        if self._topic is None:
+            self._topic = encode_hex(keccak(text=self.signature))
+        return self._topic
+
     @combomethod
     def _get_event_abi(cls) -> ABIEvent:
         if cls.abi:
@@ -253,7 +275,7 @@ class BaseContractEvent:
             yield rich_log
 
     @combomethod
-    def process_log(self, log: HexStr) -> EventData:
+    def process_log(self, log: LogReceipt) -> EventData:
         return get_event_data(self.w3.codec, self.abi, log)
 
     @combomethod
@@ -302,9 +324,7 @@ class BaseContractEvent:
         return event_filter_params
 
     @classmethod
-    def factory(
-        cls, class_name: str, **kwargs: Any
-    ) -> Union["ContractEvent", "AsyncContractEvent"]:
+    def factory(cls, class_name: str, **kwargs: Any) -> Self:
         return PropertyCheckingFactory(class_name, (cls,), kwargs)()
 
     @staticmethod
@@ -432,7 +452,7 @@ class BaseContractEvent:
             filter_builder.args[arg].match_single(value)
 
 
-class BaseContractEvents:
+class BaseContractEvents(Generic[TContractEvent]):
     """
     Class containing contract event objects
 
@@ -458,12 +478,13 @@ class BaseContractEvents:
         self,
         abi: ABI,
         w3: Union["Web3", "AsyncWeb3"],
-        contract_event_type: Union[Type["ContractEvent"], Type["AsyncContractEvent"]],
+        contract_event_type: Type[TContractEvent],
         address: Optional[ChecksumAddress] = None,
     ) -> None:
         self.abi = abi
         self.w3 = w3
         self.address = address
+        self.contract_event_type = contract_event_type
         _events: Sequence[ABIEvent] = None
 
         if self.abi:
@@ -498,6 +519,42 @@ class BaseContractEvents:
         except ABIEventNotFound:
             return False
 
+    def __getattr__(self, event_name: str) -> TContractEvent:
+        if super().__getattribute__("abi") is None:
+            raise NoABIFound(
+                "There is no ABI found for this contract.",
+            )
+        elif "_events" not in self.__dict__ or len(self._events) == 0:
+            raise NoABIEventsFound(
+                "The abi for this contract contains no event definitions. ",
+                "Are you sure you provided the correct contract abi?",
+            )
+        elif get_name_from_abi_element_identifier(event_name) not in [
+            get_name_from_abi_element_identifier(event["name"])
+            for event in self._events
+        ]:
+            raise ABIEventNotFound(
+                f"The event '{event_name}' was not found in this contract's abi. ",
+                "Are you sure you provided the correct contract abi?",
+            )
+
+        if "(" not in event_name:
+            event_name = _get_any_abi_signature_with_name(event_name, self._events)
+        else:
+            event_name = f"_{event_name}"
+
+        return super().__getattribute__(event_name)
+
+    def __getitem__(self, event_name: str) -> TContractEvent:
+        return getattr(self, event_name)
+
+    def __iter__(self) -> Iterable[TContractEvent]:
+        if not hasattr(self, "_events") or not self._events:
+            return
+
+        for event in self._events:
+            yield self[abi_to_signature(event)]
+
 
 class BaseContractFunction:
     """
@@ -713,14 +770,123 @@ class BaseContractFunction:
             return _repr + ">"
         return f"<Function {get_abi_element_signature(self.abi_element_identifier)}>"
 
+    def __call__(self, *args: Any, **kwargs: Any) -> Self:
+        # When a function is called, check arguments to obtain the correct function
+        # in the contract. self will be used if all args and kwargs are
+        # encodable to self.abi, otherwise the correct function is obtained from
+        # the contract.
+        if (
+            self.abi_element_identifier in [FallbackFn, ReceiveFn]
+            or self.abi_element_identifier == "constructor"
+        ):
+            return copy_contract_function(self, *args, **kwargs)
+
+        all_functions = cast(
+            List[ABIFunction],
+            filter_abi_by_type(
+                "function",
+                self.contract_abi,
+            ),
+        )
+        # Filter functions by name to obtain function signatures
+        function_name = get_name_from_abi_element_identifier(
+            self.abi_element_identifier
+        )
+        function_abis = [
+            function for function in all_functions if function["name"] == function_name
+        ]
+        num_args = len(args) + len(kwargs)
+        function_abis_with_arg_count = cast(
+            List[ABIFunction],
+            _filter_by_argument_count(
+                num_args,
+                function_abis,
+            ),
+        )
+
+        if not len(function_abis_with_arg_count):
+            # Build an ABI without arguments to determine if one exists
+            function_abis_with_arg_count = [
+                ABIFunction({"type": "function", "name": function_name})
+            ]
+
+        function_abi_matches = []
+        contract_function = None
+        for abi in function_abis_with_arg_count:
+            try:
+                # Search for a function ABI that matches the arguments used
+                function_abi_matches.append(
+                    cast(
+                        ABIFunction,
+                        get_abi_element(
+                            function_abis,
+                            abi_to_signature(abi),
+                            *args,
+                            abi_codec=self.w3.codec,
+                            **kwargs,
+                        ),
+                    )
+                )
+            except MismatchedABI:
+                # ignore exceptions
+                continue
+
+        if len(function_abi_matches) == 1:
+            function_abi = function_abi_matches[0]
+            if abi_to_signature(self.abi) == abi_to_signature(function_abi):
+                contract_function = self
+            else:
+                # Found a match that is not self
+                contract_function = self.__class__.factory(
+                    abi_to_signature(function_abi),
+                    w3=self.w3,
+                    contract_abi=self.contract_abi,
+                    address=self.address,
+                    abi_element_identifier=abi_to_signature(function_abi),
+                    abi=function_abi,
+                )
+        else:
+            for abi in function_abi_matches:
+                if abi_to_signature(self.abi) == abi_to_signature(abi):
+                    contract_function = self
+                    break
+            else:
+                # Raise exception if multiple found
+                raise MismatchedABI(
+                    _mismatched_abi_error_diagnosis(
+                        function_name,
+                        self.contract_abi,
+                        len(function_abi_matches),
+                        num_args,
+                        *args,
+                        abi_codec=self.w3.codec,
+                        **kwargs,
+                    )
+                )
+
+        return copy_contract_function(contract_function, *args, **kwargs)
+
     @classmethod
-    def factory(
-        cls, class_name: str, **kwargs: Any
-    ) -> Union["ContractFunction", "AsyncContractFunction"]:
+    def factory(cls, class_name: str, **kwargs: Any) -> Self:
         return PropertyCheckingFactory(class_name, (cls,), kwargs)()
 
+    def call(
+        self,
+        transaction: Optional[TxParams] = None,
+        block_identifier: Optional[BlockIdentifier] = None,
+        state_override: Optional[StateOverride] = None,
+        ccip_read_enabled: Optional[bool] = None,
+    ) -> Any:
+        """
+        Implementation of ``call`` should create a callable contract function
+        and execute it using the `eth_call` interface.
+        """
+        raise NotImplementedError(
+            "This method should be implemented in the inherited class"
+        )
+
 
-class BaseContractFunctions:
+class BaseContractFunctions(Generic[TContractFn]):
     """Class containing contract function objects"""
 
     _functions: Sequence[ABIFunction] = None
@@ -729,9 +895,7 @@ class BaseContractFunctions:
         self,
         abi: ABI,
         w3: Union["Web3", "AsyncWeb3"],
-        contract_function_class: Union[
-            Type["ContractFunction"], Type["AsyncContractFunction"]
-        ],
+        contract_function_class: Type[TContractFn],
         address: Optional[ChecksumAddress] = None,
         decode_tuples: Optional[bool] = False,
     ) -> None:
@@ -777,6 +941,46 @@ class BaseContractFunctions:
         except ABIFunctionNotFound:
             return False
 
+    def __iter__(self) -> Iterable[TContractFn]:
+        if not hasattr(self, "_functions") or not self._functions:
+            return
+
+        for func in self._functions:
+            yield self[abi_to_signature(func)]
+
+    def __getattr__(self, function_name: str) -> TContractFn:
+        if super().__getattribute__("abi") is None:
+            raise NoABIFound(
+                "There is no ABI found for this contract.",
+            )
+        elif "_functions" not in self.__dict__ or len(self._functions) == 0:
+            raise NoABIFunctionsFound(
+                "The abi for this contract contains no function definitions. ",
+                "Are you sure you provided the correct contract abi?",
+            )
+        elif get_name_from_abi_element_identifier(function_name) not in [
+            get_name_from_abi_element_identifier(function["name"])
+            for function in self._functions
+        ]:
+            raise ABIFunctionNotFound(
+                f"The function '{function_name}' was not found in this ",
+                "contract's abi.",
+            )
+
+        if "(" not in function_name:
+            function_name = _get_any_abi_signature_with_name(
+                function_name, self._functions
+            )
+        else:
+            function_name = f"_{function_name}"
+
+        return super().__getattribute__(
+            function_name,
+        )
+
+    def __getitem__(self, function_name: str) -> TContractFn:
+        return getattr(self, function_name)
+
 
 class BaseContract:
     """

web3/contract/contract.py

@@ -13,7 +13,6 @@ from typing import (
 
 from eth_typing import (
     ABI,
-    ABIFunction,
     ChecksumAddress,
 )
 from eth_utils import (
@@ -31,7 +30,6 @@ from hexbytes import (
 
 from web3._utils.abi import (
     fallback_func_abi_exists,
-    get_name_from_abi_element_identifier,
     receive_func_abi_exists,
 )
 from web3._utils.abi_element_identifiers import (
@@ -42,8 +40,6 @@ from web3._utils.compat import (
     Self,
 )
 from web3._utils.contracts import (
-    copy_contract_event,
-    copy_contract_function,
     parse_block_identifier,
 )
 from web3._utils.datatypes import (
@@ -86,12 +82,6 @@ from web3.contract.utils import (
     transact_with_contract_function,
 )
 from web3.exceptions import (
-    ABIEventNotFound,
-    ABIFunctionNotFound,
-    MismatchedABI,
-    NoABIEventsFound,
-    NoABIFound,
-    NoABIFunctionsFound,
     Web3AttributeError,
     Web3TypeError,
     Web3ValidationError,
@@ -103,12 +93,6 @@ from web3.types import (
     StateOverride,
     TxParams,
 )
-from web3.utils.abi import (
-    _filter_by_argument_count,
-    _get_any_abi_signature_with_name,
-    _mismatched_abi_error_diagnosis,
-    get_abi_element,
-)
 
 if TYPE_CHECKING:
     from ens import ENS  # noqa: F401
@@ -119,9 +103,6 @@ class ContractEvent(BaseContractEvent):
     # mypy types
     w3: "Web3"
 
-    def __call__(self, *args: Any, **kwargs: Any) -> "ContractEvent":
-        return copy_contract_event(self, *args, **kwargs)
-
     @combomethod
     def get_logs(
         self,
@@ -255,162 +236,18 @@ class ContractEvent(BaseContractEvent):
         builder.address = self.address
         return builder
 
-    @classmethod
-    def factory(cls, class_name: str, **kwargs: Any) -> Self:
-        return PropertyCheckingFactory(class_name, (cls,), kwargs)()
 
-
-class ContractEvents(BaseContractEvents):
+class ContractEvents(BaseContractEvents[ContractEvent]):
     def __init__(
         self, abi: ABI, w3: "Web3", address: Optional[ChecksumAddress] = None
     ) -> None:
         super().__init__(abi, w3, ContractEvent, address)
 
-    def __getattr__(self, event_name: str) -> "ContractEvent":
-        if super().__getattribute__("abi") is None:
-            raise NoABIFound(
-                "There is no ABI found for this contract.",
-            )
-        elif "_events" not in self.__dict__ or len(self._events) == 0:
-            raise NoABIEventsFound(
-                "The abi for this contract contains no event definitions. ",
-                "Are you sure you provided the correct contract abi?",
-            )
-        elif get_name_from_abi_element_identifier(event_name) not in [
-            get_name_from_abi_element_identifier(event["name"])
-            for event in self._events
-        ]:
-            raise ABIEventNotFound(
-                f"The event '{event_name}' was not found in this contract's abi. ",
-                "Are you sure you provided the correct contract abi?",
-            )
-
-        if "(" not in event_name:
-            event_name = _get_any_abi_signature_with_name(event_name, self._events)
-        else:
-            event_name = f"_{event_name}"
-
-        return super().__getattribute__(event_name)
-
-    def __getitem__(self, event_name: str) -> "ContractEvent":
-        return getattr(self, event_name)
-
-    def __iter__(self) -> Iterable["ContractEvent"]:
-        if not hasattr(self, "_events") or not self._events:
-            return
-
-        for event in self._events:
-            yield self[abi_to_signature(event)]
-
 
 class ContractFunction(BaseContractFunction):
     # mypy types
     w3: "Web3"
 
-    def __call__(self, *args: Any, **kwargs: Any) -> "ContractFunction":
-        # When a function is called, check arguments to obtain the correct function
-        # in the contract. self will be used if all args and kwargs are
-        # encodable to self.abi, otherwise the correct function is obtained from
-        # the contract.
-        if (
-            self.abi_element_identifier in [FallbackFn, ReceiveFn]
-            or self.abi_element_identifier == "constructor"
-        ):
-            return copy_contract_function(self, *args, **kwargs)
-
-        all_functions = cast(
-            List[ABIFunction],
-            filter_abi_by_type(
-                "function",
-                self.contract_abi,
-            ),
-        )
-        # Filter functions by name to obtain function signatures
-        function_name = get_name_from_abi_element_identifier(
-            self.abi_element_identifier
-        )
-        function_abis = [
-            function for function in all_functions if function["name"] == function_name
-        ]
-        num_args = len(args) + len(kwargs)
-        function_abis_with_arg_count = cast(
-            List[ABIFunction],
-            _filter_by_argument_count(
-                num_args,
-                function_abis,
-            ),
-        )
-
-        if not len(function_abis_with_arg_count):
-            # Build an ABI without arguments to determine if one exists
-            function_abis_with_arg_count = [
-                ABIFunction({"type": "function", "name": function_name})
-            ]
-
-        # Check that arguments in call match a function ABI
-        num_attempts = 0
-        function_abi_matches = []
-        contract_function = None
-        for abi in function_abis_with_arg_count:
-            try:
-                num_attempts += 1
-
-                # Search for a function ABI that matches the arguments used
-                function_abi_matches.append(
-                    cast(
-                        ABIFunction,
-                        get_abi_element(
-                            function_abis,
-                            abi_to_signature(abi),
-                            *args,
-                            abi_codec=self.w3.codec,
-                            **kwargs,
-                        ),
-                    )
-                )
-            except MismatchedABI:
-                # ignore exceptions
-                continue
-
-        if len(function_abi_matches) == 1:
-            function_abi = function_abi_matches[0]
-            if abi_to_signature(self.abi) == abi_to_signature(function_abi):
-                contract_function = self
-            else:
-                # Found a match that is not self
-                contract_function = ContractFunction.factory(
-                    abi_to_signature(function_abi),
-                    w3=self.w3,
-                    contract_abi=self.contract_abi,
-                    address=self.address,
-                    abi_element_identifier=abi_to_signature(function_abi),
-                    abi=function_abi,
-                )
-        else:
-            for abi in function_abi_matches:
-                if abi_to_signature(self.abi) == abi_to_signature(abi):
-                    contract_function = self
-                    break
-            else:
-                # Raise exception if multiple found
-                raise MismatchedABI(
-                    _mismatched_abi_error_diagnosis(
-                        function_name,
-                        self.contract_abi,
-                        len(function_abi_matches),
-                        num_args,
-                        *args,
-                        abi_codec=self.w3.codec,
-                        **kwargs,
-                    )
-                )
-
-        return copy_contract_function(contract_function, *args, **kwargs)
-
-    @classmethod
-    def factory(cls, class_name: str, **kwargs: Any) -> Self:
-        return PropertyCheckingFactory(class_name, (cls,), kwargs)()
-
     def call(
         self,
         transaction: Optional[TxParams] = None,
@@ -555,7 +392,7 @@ class ContractFunction(BaseContractFunction):
         return cast(ContractFunction, NonExistentReceiveFunction())
 
 
-class ContractFunctions(BaseContractFunctions):
+class ContractFunctions(BaseContractFunctions[ContractFunction]):
     def __init__(
         self,
         abi: ABI,
@@ -565,46 +402,6 @@ class ContractFunctions(BaseContractFunctions):
     ) -> None:
         super().__init__(abi, w3, ContractFunction, address, decode_tuples)
 
-    def __iter__(self) -> Iterable["ContractFunction"]:
-        if not hasattr(self, "_functions") or not self._functions:
-            return
-
-        for func in self._functions:
-            yield self[abi_to_signature(func)]
-
-    def __getattr__(self, function_name: str) -> "ContractFunction":
-        if super().__getattribute__("abi") is None:
-            raise NoABIFound(
-                "There is no ABI found for this contract.",
-            )
-        elif "_functions" not in self.__dict__ or len(self._functions) == 0:
-            raise NoABIFunctionsFound(
-                "The abi for this contract contains no function definitions. ",
-                "Are you sure you provided the correct contract abi?",
-            )
-        elif get_name_from_abi_element_identifier(function_name) not in [
-            get_name_from_abi_element_identifier(function["name"])
-            for function in self._functions
-        ]:
-            raise ABIFunctionNotFound(
-                f"The function '{function_name}' was not found in this ",
-                "contract's abi.",
-            )
-
-        if "(" not in function_name:
-            function_name = _get_any_abi_signature_with_name(
-                function_name, self._functions
-            )
-        else:
-            function_name = f"_{function_name}"
-
-        return super().__getattribute__(
-            function_name,
-        )
-
-    def __getitem__(self, function_name: str) -> "ContractFunction":
-        return getattr(self, function_name)
-
 
 class Contract(BaseContract):
     # mypy types

web3/datastructures.py

@@ -15,9 +15,9 @@ from typing import (
     Optional,
     Sequence,
     Tuple,
-    Type,
     TypeVar,
     Union,
+    ValuesView,
     cast,
 )
 
@@ -25,9 +25,6 @@ from eth_utils import (
     is_integer,
 )
 
-from web3._utils.formatters import (
-    recursive_map,
-)
 from web3.exceptions import (
     Web3AssertionError,
     Web3TypeError,
@@ -81,19 +78,18 @@ class ReadableAttributeDict(Mapping[TKey, TValue]):
         builder.text(")")
 
     @classmethod
-    def _apply_if_mapping(cls: Type[T], value: TValue) -> Union[T, TValue]:
+    def recursive(cls, value: TValue) -> Any:
+        """
+        Recursively convert mappings to ReadableAttributeDict instances and
+        process nested collections (e.g., lists, sets, and dictionaries).
+        """
         if isinstance(value, Mapping):
-            # error: Too many arguments for "object"
-            return cls(value)  # type: ignore
-        else:
-            return value
-
-    @classmethod
-    def recursive(cls, value: TValue) -> "ReadableAttributeDict[TKey, TValue]":
-        return cast(
-            "ReadableAttributeDict[TKey, TValue]",
-            recursive_map(cls._apply_if_mapping, value),
-        )
+            return cls({k: cls.recursive(v) for k, v in value.items()})
+        elif isinstance(value, Sequence) and not isinstance(value, (str, bytes)):
+            return type(value)([cls.recursive(v) for v in value])  # type: ignore
+        elif isinstance(value, set):
+            return {cls.recursive(v) for v in value}
+        return value
 
 
 class MutableAttributeDict(
@@ -342,3 +338,6 @@ class NamedElementOnion(Mapping[TKey, TValue]):
         # This leads to typing issues, so it's better to use
         # ``as_tuple_of_middleware()`` to achieve the same result.
         return iter(self._reversed_middleware())  # type: ignore
+
+    def values(self) -> ValuesView[TValue]:
+        return ValuesView(self._queue)