>>> Web3.to_hex(0)
'0x0'
>>> Web3.to_hex(1)
'0x1'
>>> Web3.to_hex(0x0)
'0x0'
>>> Web3.to_hex(0x000F)
'0xf'
>>> Web3.to_hex(b'')
>>> Web3.to_hex(b'\x00\x0F')
'0x000f'
>>> Web3.to_hex(False)
'0x0'
>>> Web3.to_hex(True)
'0x1'
>>> Web3.to_hex(hexstr='0x000F')
'0x000f'
>>> Web3.to_hex(hexstr='000F')
'0x000f'
>>> Web3.to_hex(text='')
>>> Web3.to_hex(text='cowmö')
'0x636f776dc3b6'
Web3.to_text(primitive=None, hexstr=None, text=None)
Takes a variety of inputs and returns its string equivalent.
Text gets decoded as UTF-8.
>>> Web3.to_text(0x636f776dc3b6)
'cowmö'
>>> Web3.to_text(b'cowm\xc3\xb6')
'cowmö'
>>> Web3.to_text(hexstr='0x636f776dc3b6')
'cowmö'
>>> Web3.to_text(hexstr='636f776dc3b6')
'cowmö'
>>> Web3.to_text(text='cowmö')
'cowmö'
Web3.to_bytes(primitive=None, hexstr=None, text=None)
Takes a variety of inputs and returns its bytes equivalent.
Text gets encoded as UTF-8.
>>> Web3.to_bytes(0)
b'\x00'
>>> Web3.to_bytes(0x000F)
b'\x0f'
>>> Web3.to_bytes(b'')
>>> Web3.to_bytes(b'\x00\x0F')
b'\x00\x0f'
>>> Web3.to_bytes(False)
b'\x00'
>>> Web3.to_bytes(True)
b'\x01'
>>> Web3.to_bytes(hexstr='0x000F')
b'\x00\x0f'
>>> Web3.to_bytes(hexstr='000F')
b'\x00\x0f'
>>> Web3.to_bytes(text='')
>>> Web3.to_bytes(text='cowmö')
b'cowm\xc3\xb6'
Web3.to_int(primitive=None, hexstr=None, text=None)
Takes a variety of inputs and returns its integer equivalent.
>>> Web3.to_int(0)
>>> Web3.to_int(0x000F)
>>> Web3.to_int(b'\x00\x0F')
>>> Web3.to_int(False)
>>> Web3.to_int(True)
>>> Web3.to_int(hexstr='0x000F')
>>> Web3.to_int(hexstr='000F')
Web3.to_json(obj)
Takes a variety of inputs and returns its JSON equivalent.
>>> Web3.to_json(3)
>>> Web3.to_json({'one': 1})
'{"one": 1}'
Web3.to_wei(value, currency)
Returns the value in the denomination specified by the currency argument
converted to wei.
>>> Web3.to_wei(1, 'ether')
1000000000000000000
Web3.from_wei(value, currency)
Returns the value in wei converted to the given currency. The value is returned
as a Decimal to ensure precision down to the wei.
>>> Web3.from_wei(1000000000000000000, 'ether')
Decimal('1')
Web3.is_address(value)
Returns True if the value is one of the recognized address formats.
Allows for both 0x prefixed and non-prefixed values.
If the address contains mixed upper and lower cased characters this function also
checks if the address checksum is valid according to EIP55
>>> Web3.is_address('0xd3CdA913deB6f67967B99D67aCDFa1712C293601')
Web3.is_checksum_address(value)
Returns True if the value is a valid EIP55 checksummed address
>>> Web3.is_checksum_address('0xd3CdA913deB6f67967B99D67aCDFa1712C293601')
>>> Web3.is_checksum_address('0xd3cda913deb6f67967b99d67acdfa1712c293601')
False
Web3.to_checksum_address(value)
Returns the given address with an EIP55 checksum.
>>> Web3.to_checksum_address('0xd3cda913deb6f67967b99d67acdfa1712c293601')
'0xd3CdA913deB6f67967B99D67aCDFa1712C293601'
classmethod Web3.keccak(primitive=None, hexstr=None, text=None)
Returns the Keccak-256 of the given value. Text is encoded to UTF-8 before
computing the hash, just like Solidity. Any of the following are
valid and equivalent:
>>> Web3.keccak(0x747874)
>>> Web3.keccak(b'\x74\x78\x74')
>>> Web3.keccak(hexstr='0x747874')
>>> Web3.keccak(hexstr='747874')
>>> Web3.keccak(text='txt')
HexBytes('0xd7278090a36507640ea6b7a0034b69b0d240766fa3f98e3722be93c613b29d2e')
classmethod Web3.solidity_keccak(abi_types, value)
Returns the Keccak-256 as it would be computed by the solidity keccak
function on a packed ABI encoding of the value list contents. The abi_types
argument should be a list of solidity type strings which correspond to each
of the provided values.
>>> Web3.solidity_keccak(['bool'], [True])
HexBytes("0x5fe7f977e71dba2ea1a68e21057beebb9be2ac30c6410aa38d4f3fbe41dcffd2")
>>> Web3.solidity_keccak(['uint8', 'uint8', 'uint8'], [97, 98, 99])
HexBytes("0x4e03657aea45a94fc7d47ba826c8d667c0d1e6e33a64a036ec44f58fa12d6c45")
>>> Web3.solidity_keccak(['uint8[]'], [[97, 98, 99]])
HexBytes("0x233002c671295529bcc50b76a2ef2b0de2dac2d93945fca745255de1a9e4017e")
>>> Web3.solidity_keccak(['address'], ["0x49EdDD3769c0712032808D86597B84ac5c2F5614"])
HexBytes("0x2ff37b5607484cd4eecf6d13292e22bd6e5401eaffcc07e279583bc742c68882")
>>> Web3.solidity_keccak(['address'], ["ethereumfoundation.eth"])
HexBytes("0x913c99ea930c78868f1535d34cd705ab85929b2eaaf70fcd09677ecd6e5d75e9")
Comparable solidity usage:
bytes32 data1 = keccak256(abi.encodePacked(true));
assert(data1 == hex"5fe7f977e71dba2ea1a68e21057beebb9be2ac30c6410aa38d4f3fbe41dcffd2");
bytes32 data2 = keccak256(abi.encodePacked(uint8(97), uint8(98), uint8(99)));
assert(data2 == hex"4e03657aea45a94fc7d47ba826c8d667c0d1e6e33a64a036ec44f58fa12d6c45");
w3.is_encodable(_type, value)
Returns True if a value can be encoded as the given type. Otherwise returns False.
>>> from web3.auto.gethdev import w3
>>> w3.is_encodable('bytes2', b'12')
>>> w3.is_encodable('bytes2', '0x1234')
>>> w3.is_encodable('bytes2', '1234') # not 0x-prefixed, no assumptions will be made
False
>>> w3.is_encodable('bytes2', b'1') # does not match specified bytes size
False
>>> w3.is_encodable('bytes2', b'123') # does not match specified bytes size
False
w3.strict_bytes_type_checking
Disable the stricter bytes type checking that is loaded by default. For more
examples, see Disabling Strict Checks for Bytes Types
>>> from web3.auto.gethdev import w3
>>> w3.is_encodable('bytes2', b'12')
>>> # not of exact size bytes2
>>> w3.is_encodable('bytes2', b'1')
False
>>> w3.strict_bytes_type_checking = False
>>> # zero-padded, so encoded to: b'1\x00'
>>> w3.is_encodable('bytes2', b'1')
>>> # re-enable it
>>> w3.strict_bytes_type_checking = True
>>> w3.is_encodable('bytes2', b'1')
False
These internal modules inherit from the web3.module.Module class which give them some configurations internal to the
web3.py library.
You may add or overwrite methods within any module using the attach_methods function.
To create a property instead, set is_property to True.
>>> w3.eth.attach_methods({
... 'example_method': Method(
... 'eth_example',
... mungers=[...],
... request_formatters=[...],
... result_formatters=[...],
... is_property=False,
... ),
... })
>>> w3.eth.example_method()
External modules can be used to introduce custom or third-party APIs to your Web3 instance. External modules are simply
classes whose methods and properties can be made available within the Web3 instance. Optionally, the external module may
make use of the parent Web3 instance by accepting it as the first argument within the __init__ function:
>>> class ExampleModule:
... def __init__(self, w3):
... self.w3 = w3
... def print_balance_of_shaq(self):
... print(self.w3.eth.get_balance('shaq.eth'))
Warning
Given the flexibility of external modules, use caution and only import modules from trusted third parties
and open source code you’ve vetted!
Configuring external modules can occur either at instantiation of the Web3 instance or by making use of the
attach_modules() method. To instantiate the Web3 instance with external modules use the external_modules
keyword argument:
>>> from web3 import Web3, HTTPProvider
>>> from external_module_library import (
... ModuleClass1,
... ModuleClass2,
... ModuleClass3,
... ModuleClass4,
... ModuleClass5,
... )
>>> w3 = Web3(
... HTTPProvider(provider_uri),
... external_modules={
... 'module1': ModuleClass1,
... 'module2': (ModuleClass2, {
... 'submodule1': ModuleClass3,
... 'submodule2': (ModuleClass4, {
... 'submodule2a': ModuleClass5, # submodule children may be nested further if necessary
... })
... })
... }
... )
# `return_zero`, in this case, is an example attribute of the `ModuleClass1` object
>>> w3.module1.return_zero()
>>> w3.module2.submodule1.return_one()
>>> w3.module2.submodule2.submodule2a.return_two()
w3.attach_modules(modules)
The attach_modules() method can be used to attach external modules after the Web3 instance has been
instantiated.
Modules are attached via a dict with module names as the keys. The values can either be the module classes
themselves, if there are no submodules, or two-item tuples with the module class as the 0th index and a similarly
built dict containing the submodule information as the 1st index. This pattern may be repeated as necessary.
>>> from web3 import Web3, HTTPProvider
>>> from external_module_library import (
... ModuleClass1,
... ModuleClass2,
... ModuleClass3,
... ModuleClass4,
... ModuleClass5,
... )
>>> w3 = Web3(HTTPProvider(provider_uri))
>>> w3.attach_modules({
... 'module1': ModuleClass1, # the module class itself may be used for a single module with no submodules
... 'module2': (ModuleClass2, { # a tuple with module class and corresponding submodule dict may be used for modules with submodules
... 'submodule1': ModuleClass3,
... 'submodule2': (ModuleClass4, { # this pattern may be repeated as necessary
... 'submodule2a': ModuleClass5,
... })
... })
... })
>>> w3.module1.return_zero()
>>> w3.module2.submodule1.return_one()
>>> w3.module2.submodule2.submodule2a.return_two()
