.. py:module:: web3
.. py:currentmodule:: web3
.. py:class:: Web3(provider)
Each Web3
instance exposes the following APIs.
.. py:attribute:: Web3.HTTPProvider Convenience API to access :py:class:`web3.providers.rpc.HTTPProvider`
.. py:attribute:: Web3.IPCProvider Convenience API to access :py:class:`web3.providers.ipc.IPCProvider`
.. py:attribute:: Web3.api Returns the current Web3 version. .. code-block:: python >>> web3.api "4.7.0"
.. py:attribute:: Web3.clientVersion * Delegates to ``web3_clientVersion`` RPC Method Returns the current client version. .. code-block:: python >>> web3.clientVersion 'Geth/v1.4.11-stable-fed692f6/darwin/go1.7'
.. py:method:: Web3.toHex(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`_ .. code-block:: python >>> Web3.toHex(0) '0x0' >>> Web3.toHex(1) '0x1' >>> Web3.toHex(0x0) '0x0' >>> Web3.toHex(0x000F) '0xf' >>> Web3.toHex(b'') '0x' >>> Web3.toHex(b'\x00\x0F') '0x000f' >>> Web3.toHex(False) '0x0' >>> Web3.toHex(True) '0x1' >>> Web3.toHex(hexstr='0x000F') '0x000f' >>> Web3.toHex(hexstr='000F') '0x000f' >>> Web3.toHex(text='') '0x' >>> Web3.toHex(text='cowmö') '0x636f776dc3b6'
.. py:method:: Web3.toText(primitive=None, hexstr=None, text=None) Takes a variety of inputs and returns its string equivalent. Text gets decoded as UTF-8. .. code-block:: python >>> Web3.toText(0x636f776dc3b6) 'cowmö' >>> Web3.toText(b'cowm\xc3\xb6') 'cowmö' >>> Web3.toText(hexstr='0x636f776dc3b6') 'cowmö' >>> Web3.toText(hexstr='636f776dc3b6') 'cowmö' >>> Web3.toText(text='cowmö') 'cowmö'
.. py:method:: Web3.toBytes(primitive=None, hexstr=None, text=None) Takes a variety of inputs and returns its bytes equivalent. Text gets encoded as UTF-8. .. code-block:: python >>> Web3.toBytes(0) b'\x00' >>> Web3.toBytes(0x000F) b'\x0f' >>> Web3.toBytes(b'') b'' >>> Web3.toBytes(b'\x00\x0F') b'\x00\x0f' >>> Web3.toBytes(False) b'\x00' >>> Web3.toBytes(True) b'\x01' >>> Web3.toBytes(hexstr='0x000F') b'\x00\x0f' >>> Web3.toBytes(hexstr='000F') b'\x00\x0f' >>> Web3.toBytes(text='') b'' >>> Web3.toBytes(text='cowmö') b'cowm\xc3\xb6'
.. py:method:: Web3.toInt(primitive=None, hexstr=None, text=None) Takes a variety of inputs and returns its integer equivalent. .. code-block:: python >>> Web3.toInt(0) 0 >>> Web3.toInt(0x000F) 15 >>> Web3.toInt(b'\x00\x0F') 15 >>> Web3.toInt(False) 0 >>> Web3.toInt(True) 1 >>> Web3.toInt(hexstr='0x000F') 15 >>> Web3.toInt(hexstr='000F') 15
.. py:method:: Web3.toJSON(obj) Takes a variety of inputs and returns its JSON equivalent. .. code-block:: python >>> Web3.toJSON(3) '3' >>> Web3.toJSON({'one': 1}) '{"one": 1}'
.. py:method:: Web3.toWei(value, currency) Returns the value in the denomination specified by the ``currency`` argument converted to wei. .. code-block:: python >>> Web3.toWei(1, 'ether') 1000000000000000000
.. py:method:: Web3.fromWei(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. .. code-block:: python >>> Web3.fromWei(1000000000000000000, 'ether') Decimal('1')
.. py:method:: Web3.isAddress(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`_ .. code-block:: python >>> Web3.isAddress('0xd3CdA913deB6f67967B99D67aCDFa1712C293601') True
.. py:method:: Web3.isChecksumAddress(value) Returns ``True`` if the value is a valid `EIP55`_ checksummed address .. code-block:: python >>> Web3.isChecksumAddress('0xd3CdA913deB6f67967B99D67aCDFa1712C293601') True >>> Web3.isChecksumAddress('0xd3cda913deb6f67967b99d67acdfa1712c293601') False
.. py:method:: Web3.toChecksumAddress(value) Returns the given address with an `EIP55`_ checksum. .. code-block:: python >>> Web3.toChecksumAddress('0xd3cda913deb6f67967b99d67acdfa1712c293601') '0xd3CdA913deB6f67967B99D67aCDFa1712C293601'
.. py: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: .. code-block:: python >>> Web3.keccak(0x747874) >>> Web3.keccak(b'\x74\x78\x74') >>> Web3.keccak(hexstr='0x747874') >>> Web3.keccak(hexstr='747874') >>> Web3.keccak(text='txt') HexBytes('0xd7278090a36507640ea6b7a0034b69b0d240766fa3f98e3722be93c613b29d2e')
.. py:classmethod:: Web3.solidityKeccak(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. .. code-block:: python >>> Web3.solidityKeccak(['bool'], [True]) HexBytes("0x5fe7f977e71dba2ea1a68e21057beebb9be2ac30c6410aa38d4f3fbe41dcffd2") >>> Web3.solidityKeccak(['uint8', 'uint8', 'uint8'], [97, 98, 99]) HexBytes("0x4e03657aea45a94fc7d47ba826c8d667c0d1e6e33a64a036ec44f58fa12d6c45") >>> Web3.solidityKeccak(['uint8[]'], [[97, 98, 99]]) HexBytes("0x233002c671295529bcc50b76a2ef2b0de2dac2d93945fca745255de1a9e4017e") >>> Web3.solidityKeccak(['address'], ["0x49EdDD3769c0712032808D86597B84ac5c2F5614"]) HexBytes("0x2ff37b5607484cd4eecf6d13292e22bd6e5401eaffcc07e279583bc742c68882") >>> Web3.solidityKeccak(['address'], ["ethereumfoundation.eth"]) HexBytes("0x913c99ea930c78868f1535d34cd705ab85929b2eaaf70fcd09677ecd6e5d75e9") Comparable solidity usage: .. code-block:: solidity 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");
.. py:classmethod:: Web3.sha3(primitive=None, hexstr=None, text=None) .. WARNING:: This method has been deprecated for :meth:`~Web3.keccak` Returns the Keccak SHA256 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: .. code-block:: python >>> Web3.sha3(0x747874) >>> Web3.sha3(b'\x74\x78\x74') >>> Web3.sha3(hexstr='0x747874') >>> Web3.sha3(hexstr='747874') >>> Web3.sha3(text='txt') HexBytes('0xd7278090a36507640ea6b7a0034b69b0d240766fa3f98e3722be93c613b29d2e')
.. py:classmethod:: Web3.soliditySha3(abi_types, value) .. WARNING:: This method has been deprecated for :meth:`~Web3.solidityKeccak` Returns the sha3 as it would be computed by the solidity ``sha3`` function on the provided ``value`` and ``abi_types``. The ``abi_types`` value should be a list of solidity type strings which correspond to each of the provided values. .. code-block:: python >>> Web3.soliditySha3(['bool'], [True]) HexBytes("0x5fe7f977e71dba2ea1a68e21057beebb9be2ac30c6410aa38d4f3fbe41dcffd2") >>> Web3.soliditySha3(['uint8', 'uint8', 'uint8'], [97, 98, 99]) HexBytes("0x4e03657aea45a94fc7d47ba826c8d667c0d1e6e33a64a036ec44f58fa12d6c45") >>> Web3.soliditySha3(['uint8[]'], [[97, 98, 99]]) HexBytes("0x233002c671295529bcc50b76a2ef2b0de2dac2d93945fca745255de1a9e4017e") >>> Web3.soliditySha3(['address'], ["0x49EdDD3769c0712032808D86597B84ac5c2F5614"]) HexBytes("0x2ff37b5607484cd4eecf6d13292e22bd6e5401eaffcc07e279583bc742c68882") >>> Web3.soliditySha3(['address'], ["ethereumfoundation.eth"]) HexBytes("0x913c99ea930c78868f1535d34cd705ab85929b2eaaf70fcd09677ecd6e5d75e9")
.. py:method:: w3.is_encodable(_type, value) Returns ``True`` if a value can be encoded as the given type. Otherwise returns ``False``. .. code-block:: python >>> 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
.. py:method:: w3.enable_strict_bytes_type_checking() Enables stricter bytes type checking. For more examples see :ref:`enable-strict-byte-check` .. doctest:: >>> 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
Each Web3
instance also exposes these namespaced API modules.
.. py:attribute:: Web3.eth See :doc:`./web3.eth`
.. py:attribute:: Web3.miner See :doc:`./web3.miner`
.. py:attribute:: Web3.pm See :doc:`./web3.pm`
.. py:attribute:: Web3.geth See :doc:`./web3.geth`
.. py:attribute:: Web3.parity See :doc:`./web3.parity`
These internal modules inherit from the web3.module.Module
class which give them some configurations internal to the
web3.py library.
External modules may be attached to the Web3
instance either at instantiation or by making use of the
attach_modules()
method. External modules need not inherit from the web3.module.Module
class. This allows for a
good deal of flexibility even in defining what a module means to the user. An external module could technically provide
any bit of functionality that the user desires. Consequently, external modules need not be RPC APIs - though this does
provide the ability to attach an RPC API library, specific to your chain of choice, to the Web3
instance.
To instantiate the Web3
instance with external modules:
>>> 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
.. py:method:: 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. .. code-block:: python >>> 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