Skip to content
This repository was archived by the owner on Aug 4, 2023. It is now read-only.

Latest commit

 

History

History
341 lines (233 loc) · 11.5 KB

overview.rst

File metadata and controls

341 lines (233 loc) · 11.5 KB

Overview

The purpose of this page is to give you a sense of everything web3.py can do and to serve as a quick reference guide. You'll find a summary of each feature with links to learn more. You may also be interested in the :ref:`Examples <examples>` page, which demonstrates some of these features in greater detail.

Configuration

After installing web3.py (via pip install web3), you'll need to specify async or sync web3, the provider, and any middleware you want to use beyond the defaults.

Providers

Providers are how web3.py connects to the blockchain. The library comes with the following built-in providers:

  • Web3.IPCProvider for connecting to ipc socket based JSON-RPC servers.
  • Web3.HTTPProvider for connecting to http and https based JSON-RPC servers.
  • Web3.WebsocketProvider for connecting to ws and wss websocket based JSON-RPC servers.
  • AsyncWeb3.AsyncHTTPProvider for connecting to http and https based JSON-RPC servers.

Synchronous Provider Examples:

>>> from web3 import Web3

# IPCProvider:
>>> w3 = Web3(Web3.IPCProvider('./path/to/geth.ipc'))

# HTTPProvider:
>>> w3 = Web3(Web3.HTTPProvider('http://127.0.0.1:8545'))

# WebsocketProvider:
>>> w3 = Web3(Web3.WebsocketProvider('ws://127.0.0.1:8546'))

>>> w3.is_connected()
True

Asynchronous Provider Example:

Note

The AsyncHTTPProvider is still under active development. Not all JSON-RPC methods and middleware are available yet. The list of available methods and middleware can be seen on the :class:`~web3.providers.async_rpc.AsyncHTTPProvider` docs

>>> from web3 import AsyncWeb3

>>> w3 = AsyncWeb3(AsyncWeb3.AsyncHTTPProvider('http://127.0.0.1:8545'))

>>> await w3.is_connected()
True

For more information, (e.g., connecting to remote nodes, provider auto-detection, using a test provider) see the :ref:`Providers <providers>` documentation.

Middleware

Your web3.py instance may be further configured via middleware.

web3.py middleware is described using an onion metaphor, where each layer of middleware may affect both the incoming request and outgoing response from your provider. The documentation includes a :ref:`visualization <Modifying_Middleware>` of this idea.

Several middleware are :ref:`included by default <default_middleware>`. You may add to (:meth:`add <Web3.middleware_onion.add>`, :meth:`inject <Web3.middleware_onion.inject>`, :meth:`replace <Web3.middleware_onion.replace>`) or disable (:meth:`remove <Web3.middleware_onion.remove>`, :meth:`clear <Web3.middleware_onion.clear>`) any of these middleware.

Your Keys

Private keys are required to approve any transaction made on your behalf. The manner in which your key is secured will determine how you create and send transactions in web3.py.

A local node, like Geth, may manage your keys for you. You can reference those keys using the :attr:`web3.eth.accounts <web3.eth.Eth.accounts>` property.

A hosted node, like Infura, will have no knowledge of your keys. In this case, you'll need to have your private key available locally for signing transactions.

Full documentation on the distinction between keys can be found :ref:`here <eth-account>`.

Base API

The :ref:`Web3 <web3_base>` class includes a number of convenient utility functions:

Encoding and Decoding Helpers

Address Helpers

Currency Conversions

Cryptographic Hashing

web3.eth API

The most commonly used APIs for interacting with Ethereum can be found under the web3.eth namespace. As a reminder, the :ref:`Examples <examples>` page will demonstrate how to use several of these methods.

Fetching Data

Viewing account balances (:meth:`get_balance <web3.eth.Eth.get_balance>`), transactions (:meth:`get_transaction <web3.eth.Eth.get_transaction>`), and block data (:meth:`get_block <web3.eth.Eth.get_block>`) are some of the most common starting points in web3.py.

API

Making Transactions

The most common use cases will be satisfied with :meth:`send_transaction <web3.eth.Eth.send_transaction>` or the combination of :meth:`sign_transaction <web3.eth.Eth.sign_transaction>` and :meth:`send_raw_transaction <web3.eth.Eth.send_raw_transaction>`.

Note

If interacting with a smart contract, a dedicated API exists. See the next section, :ref:`Contracts <overview_contracts>`.

API

Contracts

The two most common use cases involving smart contracts are deploying and executing functions on a deployed contract.

Deployment requires that the contract already be compiled, with its bytecode and ABI available. This compilation step can be done within Remix or one of the many contract development frameworks, such as Brownie.

Once the contract object is instantiated, calling transact on the :meth:`constructor <web3.contract.Contract.constructor>` method will deploy an instance of the contract:

>>> ExampleContract = w3.eth.contract(abi=abi, bytecode=bytecode)
>>> tx_hash = ExampleContract.constructor().transact()
>>> tx_receipt = w3.eth.wait_for_transaction_receipt(tx_hash)
>>> tx_receipt.contractAddress
'0x8a22225eD7eD460D7ee3842bce2402B9deaD23D3'

Once loaded into a Contract object, the functions of a deployed contract are available on the functions namespace:

>>> deployed_contract = w3.eth.contract(address=tx_receipt.contractAddress, abi=abi)
>>> deployed_contract.functions.myFunction(42).transact()

If you want to read data from a contract (or see the result of transaction locally, without executing it on the network), you can use the :meth:`ContractFunction.call <web3.contract.ContractFunction.call>` method, or the more concise :attr:`ContractCaller <web3.contract.ContractCaller>` syntax:

# Using ContractFunction.call
>>> deployed_contract.functions.getMyValue().call()
42

# Using ContractCaller
>>> deployed_contract.caller().getMyValue()
42

For more, see the full :ref:`Contracts` documentation.

API

Logs and Filters

If you want to react to new blocks being mined or specific events being emitted by a contract, you can leverage web3.py filters.

# Use case: filter for new blocks
>>> new_filter = web3.eth.filter('latest')

# Use case: filter for contract event "MyEvent"
>>> new_filter = deployed_contract.events.MyEvent.create_filter(fromBlock='latest')

# retrieve filter results:
>>> new_filter.get_all_entries()
>>> new_filter.get_new_entries()

More complex patterns for creating filters and polling for logs can be found in the :ref:`Filtering <filtering>` documentation.

API

Net API

Some basic network properties are available on the web3.net object:

ethPM

ethPM allows you to package up your contracts for reuse or use contracts from another trusted registry. See the full details :ref:`here <ethpm>`.

ENS

Ethereum Name Service (ENS) provides the infrastructure for human-readable addresses. As an example, instead of 0xfB6916095ca1df60bB79Ce92cE3Ea74c37c5d359, you can send funds to ethereumfoundation.eth. web3.py has support for ENS, documented :ref:`here <ens_overview>`.