Utils
The utils
module houses public utility functions and classes.
ABI
- web3.utils.abi.get_abi_element_info(abi: Sequence[ABIFunction | ABIConstructor | ABIFallback | ABIReceive | ABIEvent | ABIError], abi_element_identifier: str | Type[FallbackFn] | Type[ReceiveFn], *args: Sequence[Any] | None, abi_codec: Any | None = None, **kwargs: Dict[str, Any] | None) ABIElementInfo
Information about the function ABI, selector and input arguments.
Returns the ABI which matches the provided identifier, named arguments (
args
) and keyword args (kwargs
).- Parameters:
abi (ABI) – Contract ABI.
abi_element_identifier (ABIElementIdentifier) – Find an element ABI with matching identifier.
args (Optional[Sequence[Any]]) – Find a function ABI with matching args.
abi_codec (Optional[Any]) – Codec used for encoding and decoding. Default with strict_bytes_type_checking enabled.
kwargs (Optional[Dict[str, Any]]) – Find an element ABI with matching kwargs.
- Returns:
Element information including the ABI, selector and args.
- Return type:
ABIElementInfo
>>> from web3.utils.abi import get_abi_element_info >>> abi = [ ... { ... "constant": False, ... "inputs": [ ... {"name": "a", "type": "uint256"}, ... {"name": "b", "type": "uint256"}, ... ], ... "name": "multiply", ... "outputs": [{"name": "result", "type": "uint256"}], ... "payable": False, ... "stateMutability": "nonpayable", ... "type": "function", ... } ... ] >>> fn_info = get_abi_element_info(abi, "multiply", *[7, 3]) >>> fn_info["abi"] {'constant': False, 'inputs': [{'name': 'a', 'type': 'uint256'}, {'name': 'b', 'type': 'uint256'}], 'name': 'multiply', 'outputs': [{'name': 'result', 'type': 'uint256'}], 'payable': False, 'stateMutability': 'nonpayable', 'type': 'function'} >>> fn_info["selector"] '0x165c4a16' >>> fn_info["arguments"] (7, 3)
- web3.utils.abi.get_abi_element(abi: Sequence[ABIFunction | ABIConstructor | ABIFallback | ABIReceive | ABIEvent | ABIError], abi_element_identifier: str | Type[FallbackFn] | Type[ReceiveFn], *args: Any | None, abi_codec: Any | None = None, **kwargs: Any | None) ABIFunction | ABIConstructor | ABIFallback | ABIReceive | ABIEvent | ABIError
Return the interface for an
ABIElement
from theabi
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
ABIElementIdentifier
value may be a function name, signature, or aFallbackFn
orReceiveFn
. 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 the eth-abi Codecs Doc.
- Parameters:
abi (ABI) – Contract ABI.
abi_element_identifier (ABIElementIdentifier) – Find an element ABI with matching identifier. The identifier may be a function name, signature, or
FallbackFn
orReceiveFn
. A function signature is in the formname(arg1Type,arg2Type,...)
.args (Optional[Sequence[Any]]) – Find an element ABI with matching args.
abi_codec (Optional[Any]) – Codec used for encoding and decoding. Default with strict_bytes_type_checking enabled.
kwargs (Optional[Dict[str, Any]]) – Find an element ABI with matching kwargs.
- Returns:
ABI element for the specific ABI element.
- Return type:
ABIElement
>>> from web3.utils.abi import get_abi_element >>> abi = [ ... { ... "constant": False, ... "inputs": [ ... {"name": "a", "type": "uint256"}, ... {"name": "b", "type": "uint256"}, ... ], ... "name": "multiply", ... "outputs": [{"name": "result", "type": "uint256"}], ... "payable": False, ... "stateMutability": "nonpayable", ... "type": "function", ... } ... ] >>> get_abi_element(abi, "multiply", *[7, 3]) {'constant': False, 'inputs': [{'name': 'a', 'type': 'uint256'}, {'name': 'b', 'type': 'uint256'}], 'name': 'multiply', 'outputs': [{'name': 'result', 'type': 'uint256'}], 'payable': False, 'stateMutability': 'nonpayable', 'type': 'function'}
- web3.utils.abi.check_if_arguments_can_be_encoded(abi_element: ABIFunction | ABIConstructor | ABIFallback | ABIReceive | ABIEvent | ABIError, *args: Sequence[Any] | None, abi_codec: Any | None = None, **kwargs: Dict[str, Any] | None) bool
Check if the provided arguments can be encoded with the element ABI.
- Parameters:
abi_element (ABIElement) – The ABI element.
args (Optional[Sequence[Any]]) – Positional arguments.
abi_codec (Optional[Any]) – Codec used for encoding and decoding. Default with strict_bytes_type_checking enabled.
kwargs (Optional[Dict[str, Any]]) – Keyword arguments.
- Returns:
True if the arguments can be encoded, False otherwise.
- Return type:
bool
>>> from web3.utils.abi import check_if_arguments_can_be_encoded >>> abi = { ... "constant": False, ... "inputs": [ ... {"name": "a", "type": "uint256"}, ... {"name": "b", "type": "uint256"}, ... ], ... "name": "multiply", ... "outputs": [{"name": "result", "type": "uint256"}], ... "payable": False, ... "stateMutability": "nonpayable", ... "type": "function", ... } >>> check_if_arguments_can_be_encoded(abi, *[7, 3], **{}) True
- web3.utils.abi.get_event_abi(abi: Sequence[ABIFunction | ABIConstructor | ABIFallback | ABIReceive | ABIEvent | ABIError], event_name: str, argument_names: Sequence[str] | None = 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.
- Parameters:
abi (ABI) – Contract ABI.
event_name (str) – Find an event abi with matching event name.
argument_names (Optional[Sequence[str]]) – Find an event abi with matching arguments.
- Returns:
ABI for the event interface.
- Return type:
ABIEvent
>>> from web3.utils import get_event_abi >>> abi = [ ... {"type": "function", "name": "myFunction", "inputs": [], "outputs": []}, ... {"type": "function", "name": "myFunction2", "inputs": [], "outputs": []}, ... {"type": "event", "name": "MyEvent", "inputs": []} ... ] >>> get_event_abi(abi, 'MyEvent') {'type': 'event', 'name': 'MyEvent', 'inputs': []}
- web3.utils.abi.get_event_log_topics(event_abi: ABIEvent, topics: Sequence[HexBytes]) Sequence[HexBytes]
Return topics for an event ABI.
- Parameters:
event_abi (ABIEvent) – Event ABI.
topics (Sequence[HexBytes]) – Transaction topics from a LogReceipt.
- Returns:
Event topics for the event ABI.
- Return type:
Sequence[HexBytes]
>>> from web3.utils import get_event_log_topics >>> abi = { ... 'type': 'event', ... 'anonymous': False, ... 'name': 'MyEvent', ... 'inputs': [ ... { ... 'name': 's', ... 'type': 'uint256' ... } ... ] ... } >>> keccak_signature = b'l+Ff\xba\x8d\xa5\xa9W\x17b\x1d\x87\x9aw\xder_=\x81g\t\xb9\xcb\xe9\xf0Y\xb8\xf8u\xe2\x84' # noqa: E501 >>> get_event_log_topics(abi, [keccak_signature, '0x1', '0x2']) ['0x1', '0x2']
- web3.utils.abi.log_topic_to_bytes(log_topic: bytes | int | bool | HexStr | str) bytes
Return topic signature as bytes.
- Parameters:
log_topic (Union[Primitives, HexStr, str]) – Event topic from a LogReceipt.
- Returns:
Topic signature as bytes.
- Return type:
bytes
>>> from web3.utils import log_topic_to_bytes >>> log_topic_to_bytes('0xa12fd1') b'\xa1/\xd1'
Address
- utils.get_create_address(sender, nonce)
Return the checksummed contract address generated by using the
CREATE
opcode by a sender address with a given nonce.
Caching
- class utils.SimpleCache
The main cache class being used internally by web3.py. In some cases, it may prove useful to set your own cache size and pass in your own instance of this class where supported.
Exception Handling
- utils.handle_offchain_lookup(offchain_lookup_payload, transaction)
Handle
OffchainLookup
reverts on contract function calls manually. For an example, see CCIP Read support for offchain lookup within the examples section.
- utils.async_handle_offchain_lookup(offchain_lookup_payload, transaction)
The async version of the
handle_offchain_lookup()
utility method described above.