web3 7.0.0b2__py3-none-any.whl → 7.7.0__py3-none-any.whl

web3/contract/contract.py

@@ -1,4 +1,3 @@
-import copy
 from typing import (
     TYPE_CHECKING,
     Any,
@@ -13,10 +12,15 @@ from typing import (
 )
 
 from eth_typing import (
+    ABI,
+    ABIFunction,
     ChecksumAddress,
 )
 from eth_utils import (
+    abi_to_signature,
     combomethod,
+    filter_abi_by_type,
+    get_abi_input_names,
 )
 from eth_utils.toolz import (
     partial,
@@ -27,13 +31,19 @@ from hexbytes import (
 
 from web3._utils.abi import (
     fallback_func_abi_exists,
-    filter_by_type,
+    get_name_from_abi_element_identifier,
     receive_func_abi_exists,
 )
+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,
     parse_block_identifier,
 )
 from web3._utils.datatypes import (
@@ -46,10 +56,6 @@ from web3._utils.events import (
 from web3._utils.filters import (
     LogFilter,
 )
-from web3._utils.function_identifiers import (
-    FallbackFn,
-    ReceiveFn,
-)
 from web3._utils.normalizers import (
     normalize_abi,
     normalize_address,
@@ -73,25 +79,35 @@ from web3.contract.utils import (
     build_transaction_for_function,
     call_contract_function,
     estimate_gas_for_function,
+    find_events_by_identifier,
     find_functions_by_identifier,
+    get_event_by_identifier,
     get_function_by_identifier,
     transact_with_contract_function,
 )
 from web3.exceptions import (
+    ABIEventNotFound,
     ABIFunctionNotFound,
+    MismatchedABI,
+    NoABIEventsFound,
     NoABIFound,
     NoABIFunctionsFound,
+    Web3AttributeError,
+    Web3TypeError,
     Web3ValidationError,
+    Web3ValueError,
 )
 from web3.types import (
-    ABI,
     BlockIdentifier,
     EventData,
     StateOverride,
     TxParams,
 )
-from web3.utils import (
-    get_abi_input_names,
+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:
@@ -103,15 +119,19 @@ 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,
         argument_filters: Optional[Dict[str, Any]] = None,
-        fromBlock: Optional[BlockIdentifier] = None,
-        toBlock: Optional[BlockIdentifier] = None,
+        from_block: Optional[BlockIdentifier] = None,
+        to_block: Optional[BlockIdentifier] = None,
         block_hash: Optional[HexBytes] = None,
     ) -> Iterable[EventData]:
-        """Get events for this contract instance using eth_getLogs API.
+        """
+        Get events for this contract instance using eth_getLogs API.
 
         This is a stateless method, as opposed to create_filter.
         It can be safely called against nodes which do not provide
@@ -127,10 +147,10 @@ class ContractEvent(BaseContractEvent):
 
         .. code-block:: python
 
-            from = max(mycontract.web3.eth.block_number - 10, 1)
-            to = mycontract.web3.eth.block_number
+            from = max(my_contract.web3.eth.block_number - 10, 1)
+            to = my_contract.web3.eth.block_number
 
-            events = mycontract.events.Transfer.get_logs(fromBlock=from, toBlock=to)
+            events = my_contract.events.Transfer.get_logs(from_block=from, to_block=to)
 
             for e in events:
                 print(e["args"]["from"],
@@ -160,14 +180,13 @@ class ContractEvent(BaseContractEvent):
 
         :param argument_filters: Filter by argument values. Indexed arguments are
           filtered by the node while non-indexed arguments are filtered by the library.
-        :param fromBlock: block number or "latest", defaults to "latest"
-        :param toBlock: block number or "latest". Defaults to "latest"
+        :param from_block: block number or "latest", defaults to "latest"
+        :param to_block: block number or "latest". Defaults to "latest"
         :param block_hash: block hash. block_hash cannot be set at the
-          same time as fromBlock or toBlock
+          same time as ``from_block`` or ``to_block``
         :yield: Tuple of :class:`AttributeDict` instances
         """
         event_abi = self._get_event_abi()
-
         # validate ``argument_filters`` if present
         if argument_filters is not None:
             event_arg_names = get_abi_input_names(event_abi)
@@ -178,7 +197,7 @@ class ContractEvent(BaseContractEvent):
                 )
 
         _filter_params = self._get_event_filter_params(
-            event_abi, argument_filters, fromBlock, toBlock, block_hash
+            event_abi, argument_filters, from_block, to_block, block_hash
         )
         # call JSON-RPC API
         logs = self.w3.eth.get_logs(_filter_params)
@@ -201,41 +220,45 @@ class ContractEvent(BaseContractEvent):
         self,
         *,  # PEP 3102
         argument_filters: Optional[Dict[str, Any]] = None,
-        fromBlock: Optional[BlockIdentifier] = None,
-        toBlock: BlockIdentifier = "latest",
+        from_block: Optional[BlockIdentifier] = None,
+        to_block: BlockIdentifier = "latest",
         address: Optional[ChecksumAddress] = None,
         topics: Optional[Sequence[Any]] = None,
     ) -> LogFilter:
         """
         Create filter object that tracks logs emitted by this contract event.
         """
-        filter_builder = EventFilterBuilder(self._get_event_abi(), self.w3.codec)
+        abi = self._get_event_abi()
+        filter_builder = EventFilterBuilder(abi, self.w3.codec)
         self._set_up_filter_builder(
             argument_filters,
-            fromBlock,
-            toBlock,
+            from_block,
+            to_block,
             address,
             topics,
             filter_builder,
         )
         log_filter = filter_builder.deploy(self.w3)
-        log_filter.log_entry_formatter = get_event_data(
-            self.w3.codec, self._get_event_abi()
-        )
+        log_filter.log_entry_formatter = get_event_data(self.w3.codec, abi)
         log_filter.builder = filter_builder
 
         return log_filter
 
     @combomethod
     def build_filter(self) -> EventFilterBuilder:
+        abi = self._get_event_abi()
         builder = EventFilterBuilder(
-            self._get_event_abi(),
+            abi,
             self.w3.codec,
-            formatter=get_event_data(self.w3.codec, self._get_event_abi()),
+            formatter=get_event_data(self.w3.codec, abi),
         )
         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):
     def __init__(
@@ -243,33 +266,155 @@ class ContractEvents(BaseContractEvents):
     ) -> 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":
-        clone = copy.copy(self)
-        if args is None:
-            clone.args = tuple()
-        else:
-            clone.args = args
+        # 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 kwargs is None:
-            clone.kwargs = {}
+        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:
-            clone.kwargs = kwargs
-        clone._set_function_info()
-        return clone
+            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)(kwargs.get("abi"))
+        return PropertyCheckingFactory(class_name, (cls,), kwargs)()
 
     def call(
         self,
         transaction: Optional[TxParams] = None,
-        block_identifier: BlockIdentifier = None,
+        block_identifier: Optional[BlockIdentifier] = None,
         state_override: Optional[StateOverride] = None,
         ccip_read_enabled: Optional[bool] = None,
     ) -> Any:
@@ -294,9 +439,9 @@ class ContractFunction(BaseContractFunction):
             addr = contract.functions.owner().call()
 
         :param transaction: Dictionary of transaction info for web3 interface
-        :param block_identifier: TODO
-        :param state_override TODO
-        :param ccip_read_enabled TODO
+        :param block_identifier: Block number or string "latest", "pending", "earliest"
+        :param state_override: Dictionary of state override values
+        :param ccip_read_enabled: Enable CCIP read operations for the call
         :return: ``Caller`` object that has contract public functions
             and variables exposed as Python methods
         """
@@ -304,11 +449,13 @@ class ContractFunction(BaseContractFunction):
 
         block_id = parse_block_identifier(self.w3, block_identifier)
 
+        abi_element_identifier = abi_to_signature(self.abi)
+
         return call_contract_function(
             self.w3,
             self.address,
             self._return_data_normalizers,
-            self.function_identifier,
+            abi_element_identifier,
             call_transaction,
             block_id,
             self.contract_abi,
@@ -316,21 +463,23 @@ class ContractFunction(BaseContractFunction):
             state_override,
             ccip_read_enabled,
             self.decode_tuples,
-            *self.args,
-            **self.kwargs,
+            *self.args or (),
+            **self.kwargs or {},
         )
 
     def transact(self, transaction: Optional[TxParams] = None) -> HexBytes:
         setup_transaction = self._transact(transaction)
+        abi_element_identifier = abi_to_signature(self.abi)
+
         return transact_with_contract_function(
             self.address,
             self.w3,
-            self.function_identifier,
+            abi_element_identifier,
             setup_transaction,
             self.contract_abi,
             self.abi,
-            *self.args,
-            **self.kwargs,
+            *self.args or (),
+            **self.kwargs or {},
         )
 
     def estimate_gas(
@@ -340,30 +489,33 @@ class ContractFunction(BaseContractFunction):
         state_override: Optional[StateOverride] = None,
     ) -> int:
         setup_transaction = self._estimate_gas(transaction)
+        abi_element_identifier = abi_to_signature(self.abi)
         return estimate_gas_for_function(
             self.address,
             self.w3,
-            self.function_identifier,
+            abi_element_identifier,
             setup_transaction,
             self.contract_abi,
             self.abi,
             block_identifier,
             state_override,
-            *self.args,
-            **self.kwargs,
+            *self.args or (),
+            **self.kwargs or {},
         )
 
     def build_transaction(self, transaction: Optional[TxParams] = None) -> TxParams:
         built_transaction = self._build_transaction(transaction)
+        abi_element_identifier = abi_to_signature(self.abi)
+
         return build_transaction_for_function(
             self.address,
             self.w3,
-            self.function_identifier,
+            abi_element_identifier,
             built_transaction,
             self.contract_abi,
             self.abi,
-            *self.args,
-            **self.kwargs,
+            *self.args or (),
+            **self.kwargs or {},
         )
 
     @staticmethod
@@ -373,12 +525,14 @@ class ContractFunction(BaseContractFunction):
         address: Optional[ChecksumAddress] = None,
     ) -> "ContractFunction":
         if abi and fallback_func_abi_exists(abi):
+            fallback_abi = filter_abi_by_type("fallback", abi)[0]
             return ContractFunction.factory(
                 "fallback",
                 w3=w3,
                 contract_abi=abi,
                 address=address,
-                function_identifier=FallbackFn,
+                abi_element_identifier=FallbackFn,
+                abi=fallback_abi,
             )()
         return cast(ContractFunction, NonExistentFallbackFunction())
 
@@ -389,12 +543,14 @@ class ContractFunction(BaseContractFunction):
         address: Optional[ChecksumAddress] = None,
     ) -> "ContractFunction":
         if abi and receive_func_abi_exists(abi):
+            receive_abi = filter_abi_by_type("receive", abi)[0]
             return ContractFunction.factory(
                 "receive",
                 w3=w3,
                 contract_abi=abi,
                 address=address,
-                function_identifier=ReceiveFn,
+                abi_element_identifier=ReceiveFn,
+                abi=receive_abi,
             )()
         return cast(ContractFunction, NonExistentReceiveFunction())
 
@@ -409,23 +565,45 @@ 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 self.abi is None:
+        if super().__getattribute__("abi") is None:
             raise NoABIFound(
                 "There is no ABI found for this contract.",
             )
-        if "_functions" not in self.__dict__:
+        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 function_name not in self.__dict__["_functions"]:
+        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.",
-                " Are you sure you provided the correct contract abi?",
+                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:
-            return super().__getattribute__(function_name)
+            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):
@@ -438,20 +616,23 @@ class Contract(BaseContract):
     events: ContractEvents = None
 
     def __init__(self, address: Optional[ChecksumAddress] = None) -> None:
-        """Create a new smart contract proxy object.
-        :param address: Contract address as 0x hex string"""
+        """
+        Create a new smart contract proxy object.
+        :param address: Contract address as 0x hex string
+        """
         _w3 = self.w3
         if _w3 is None:
-            raise AttributeError(
+            raise Web3AttributeError(
                 "The `Contract` class has not been initialized.  Please use the "
                 "`web3.contract` interface to create your contract class."
             )
 
         if address:
-            self.address = normalize_address(cast("ENS", _w3.ens), address)
+            # invoke ``w3._ens`` over ``w3.ens`` to avoid premature instantiation
+            self.address = normalize_address(cast("ENS", _w3._ens), address)
 
         if not self.address:
-            raise TypeError(
+            raise Web3TypeError(
                 "The address argument is required to instantiate a contract."
             )
 
@@ -459,7 +640,11 @@ class Contract(BaseContract):
             self.abi, _w3, self.address, decode_tuples=self.decode_tuples
         )
         self.caller = ContractCaller(
-            self.abi, _w3, self.address, decode_tuples=self.decode_tuples
+            self.abi,
+            _w3,
+            self.address,
+            decode_tuples=self.decode_tuples,
+            contract_functions=self.functions,
         )
         self.events = ContractEvents(self.abi, _w3, self.address)
         self.fallback = Contract.get_fallback_function(
@@ -483,7 +668,8 @@ class Contract(BaseContract):
 
         normalizers = {
             "abi": normalize_abi,
-            "address": partial(normalize_address, w3.ens),
+            # invoke ``w3._ens`` over ``w3.ens`` to avoid premature instantiation
+            "address": partial(normalize_address, w3._ens),
             "bytecode": normalize_bytecode,
             "bytecode_runtime": normalize_bytecode,
         }
@@ -497,6 +683,16 @@ class Contract(BaseContract):
                 normalizers=normalizers,
             ),
         )
+
+        if contract.abi:
+            for abi in contract.abi:
+                abi_name = abi.get("name")
+                if abi_name in ["abi", "address"]:
+                    raise Web3AttributeError(
+                        f"Contract contains a reserved word `{abi_name}` "
+                        f"and could not be instantiated."
+                    )
+
         contract.functions = ContractFunctions(
             contract.abi, contract.w3, decode_tuples=contract.decode_tuples
         )
@@ -505,6 +701,7 @@ class Contract(BaseContract):
             contract.w3,
             contract.address,
             decode_tuples=contract.decode_tuples,
+            contract_functions=contract.functions,
         )
         contract.events = ContractEvents(contract.abi, contract.w3)
         contract.fallback = Contract.get_fallback_function(
@@ -528,7 +725,7 @@ class Contract(BaseContract):
         :return: a contract constructor object
         """
         if cls.bytecode is None:
-            raise ValueError(
+            raise Web3ValueError(
                 "Cannot call constructor on a contract that does not have "
                 "'bytecode' associated with it"
             )
@@ -556,6 +753,24 @@ class Contract(BaseContract):
     ) -> "ContractFunction":
         return get_function_by_identifier(fns, identifier)
 
+    @combomethod
+    def find_events_by_identifier(
+        cls,
+        contract_abi: ABI,
+        w3: "Web3",
+        address: ChecksumAddress,
+        callable_check: Callable[..., Any],
+    ) -> List["ContractEvent"]:
+        return find_events_by_identifier(
+            contract_abi, w3, address, callable_check, ContractEvent
+        )
+
+    @combomethod
+    def get_event_by_identifier(
+        self, events: Sequence["ContractEvent"], identifier: str
+    ) -> "ContractEvent":
+        return get_event_by_identifier(events, identifier)
+
 
 class ContractCaller(BaseContractCaller):
     # mypy types
@@ -570,6 +785,7 @@ class ContractCaller(BaseContractCaller):
         block_identifier: BlockIdentifier = None,
         ccip_read_enabled: Optional[bool] = None,
         decode_tuples: Optional[bool] = False,
+        contract_functions: Optional[ContractFunctions] = None,
     ) -> None:
         super().__init__(abi, w3, address, decode_tuples=decode_tuples)
 
@@ -577,17 +793,13 @@ class ContractCaller(BaseContractCaller):
             if transaction is None:
                 transaction = {}
 
-            self._functions = filter_by_type("function", self.abi)
-            for func in self._functions:
-                fn = ContractFunction.factory(
-                    func["name"],
-                    w3=w3,
-                    contract_abi=self.abi,
-                    address=self.address,
-                    function_identifier=func["name"],
-                    decode_tuples=decode_tuples,
+            if contract_functions is None:
+                contract_functions = ContractFunctions(
+                    abi, w3, address=address, decode_tuples=decode_tuples
                 )
 
+            self._functions = contract_functions._functions
+            for fn in contract_functions.__iter__():
                 caller_method = partial(
                     self.call_function,
                     fn,
@@ -595,8 +807,7 @@ class ContractCaller(BaseContractCaller):
                     block_identifier=block_identifier,
                     ccip_read_enabled=ccip_read_enabled,
                 )
-
-                setattr(self, func["name"], caller_method)
+                setattr(self, str(fn.abi_element_identifier), caller_method)
 
     def __call__(
         self,