Web3 API
- class web3.Web3(provider)
Each Web3
instance exposes the following APIs.
Providers
- Web3.HTTPProvider
Convenience API to access
web3.providers.rpc.HTTPProvider
- Web3.IPCProvider
Convenience API to access
web3.providers.ipc.IPCProvider
Attributes
- Web3.api
Returns the current Web3 version.
>>> web3.api "4.7.0"
- Web3.client_version
Delegates to
web3_clientVersion
RPC Method
Returns the current client version.
>>> web3.client_version 'Geth/v1.4.11-stable-fed692f6/darwin/go1.7'
Encoding and Decoding Helpers
- Web3.to_hex(primitive=None, hexstr=None, text=None)
Takes a variety of inputs and returns it in its hexadecimal representation. It follows the rules for converting to hex in the JSON-RPC spec
>>> Web3.to_hex(0) '0x0' >>> Web3.to_hex(1) '0x1' >>> Web3.to_hex(0x0) '0x0' >>> Web3.to_hex(0x000F) '0xf' >>> Web3.to_hex(b'') '0x' >>> 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='') '0x' >>> 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'') 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='') b'' >>> 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) 0 >>> Web3.to_int(0x000F) 15 >>> Web3.to_int(b'\x00\x0F') 15 >>> Web3.to_int(False) 0 >>> Web3.to_int(True) 1 >>> Web3.to_int(hexstr='0x000F') 15 >>> Web3.to_int(hexstr='000F') 15
- Web3.to_json(obj)
Takes a variety of inputs and returns its JSON equivalent.
>>> Web3.to_json(3) '3' >>> Web3.to_json({'one': 1}) '{"one": 1}'
Currency Conversions
- 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')
Addresses
- 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') True
Cryptographic Hashing
- 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 thevalue
list contents. Theabi_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");
Check Encodability
- w3.is_encodable(_type, value)
Returns
True
if a value can be encoded as the given type. Otherwise returnsFalse
.>>> from web3.auto.gethdev import w3 >>> w3.is_encodable('bytes2', b'12') True >>> w3.is_encodable('bytes2', '0x1234') True >>> 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') True >>> # 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') True >>> # re-enable it >>> w3.strict_bytes_type_checking = True >>> w3.is_encodable('bytes2', b'1') False
RPC API Modules
Each Web3
instance also exposes these namespaced API modules.
- Web3.eth
See web3.eth API
- Web3.pm
These internal modules inherit from the web3.module.Module
class which give them some configurations internal to the
web3.py library.
Custom Methods
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
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()
0
>>> w3.module2.submodule1.return_one()
1
>>> w3.module2.submodule2.submodule2a.return_two()
2
- w3.attach_modules(modules)
The
attach_modules()
method can be used to attach external modules after theWeb3
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() 0 >>> w3.module2.submodule1.return_one() 1 >>> w3.module2.submodule2.submodule2a.return_two() 2