Utils

The utils module houses public utility functions and classes.

ABI

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)

Return the interface for an ABIElement which matches the provided identifier and arguments.

The ABI which matches the provided identifier, named arguments (args) and keyword args (kwargs) will be returned.

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.
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'}

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

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.

utils.get_create2_address(sender, salt, init_code): Return the checksummed contract address generated by using the CREATE2 opcode by a sender address with a given salt and contract bytecode. See EIP-1014.

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.