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'
- Delegates to
-
Web3.
clientVersion
¶ Warning
Deprecated: This property is deprecated in favor of
client_version()
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.
toHex
(primitive=None, hexstr=None, text=None)¶ Warning
Deprecated: This method is deprecated in favor of
to_hex()
-
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.
toText
(primitive=None, hexstr=None, text=None)¶ Warning
Deprecated: This method is deprecated in favor of
to_text()
-
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.
toBytes
(primitive=None, hexstr=None, text=None)¶ Warning
Deprecated: This method is deprecated in favor of
to_bytes()
-
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.
toInt
(primitive=None, hexstr=None, text=None)¶ Warning
Deprecated: This method is deprecated in favor of
to_int()
-
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')
-
Web3.
fromWei
(value, currency)¶ Warning
Deprecated: This method is deprecated in favor of
from_wei()
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
- Allows for both
-
Web3.
isAddress
(value)¶ Warning
Deprecated: This method is deprecated in favor of
is_address()
-
Web3.
is_checksum_address
(value)¶ Returns
True
if the value is a valid EIP55 checksummed address>>> Web3.is_checksum_address('0xd3CdA913deB6f67967B99D67aCDFa1712C293601') True >>> Web3.is_checksum_address('0xd3cda913deb6f67967b99d67acdfa1712c293601') False
-
Web3.
isChecksumAddress
(value)¶ Warning
Deprecated: This method is deprecated in favor of
is_checksum_address()
-
Web3.
to_checksum_address
(value)¶ Returns the given address with an EIP55 checksum.
>>> Web3.to_checksum_address('0xd3cda913deb6f67967b99d67acdfa1712c293601') '0xd3CdA913deB6f67967B99D67aCDFa1712C293601'
-
Web3.
toChecksumAddress
(value)¶ Warning
Deprecated: This method is deprecated in favor of
to_checksum_address()
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.
sha3
(primitive=None, hexstr=None, text=None)¶ Warning
This method has been deprecated and is an alias for
keccak()
. See new method description above for details.
-
classmethod
Web3.
solidity_keccak
(abi_types, value)¶ Returns the Keccak-256 as it would be computed by the solidity
keccak
function on the providedvalue
andabi_types
. Theabi_types
value 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");
-
classmethod
Web3.
solidityKeccak
(abi_types, value)¶ Warning
This method has been deprecated and is an alias for
solidity_keccak()
. See new method description above for details.
-
classmethod
Web3.
soliditySha3
(abi_types, value)¶ Warning
This method has been deprecated and is an alias for
solidity_keccak()
. See new method above description for details.
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', b'1') True >>> w3.is_encodable('bytes2', '0x1234') True >>> w3.is_encodable('bytes2', b'123') False
-
w3.
enable_strict_bytes_type_checking
()¶ Enables stricter bytes type checking. For more examples see Enabling Strict Checks for Bytes Types
>>> from web3.auto.gethdev import w3 >>> w3.enable_strict_bytes_type_checking() >>> w3.is_encodable('bytes2', b'12') 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
¶
-
Web3.
parity
¶ See Parity API
These internal modules inherit from the web3.module.Module
class which give them some configurations internal to the
web3.py library.
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