web3.py — Python Library for Ethereum Blockchain Interaction

Introduction

web3.py is a Python library for interacting with the Ethereum blockchain. It provides a Pythonic interface to JSON-RPC endpoints for querying blocks, sending transactions, deploying and calling smart contracts, and subscribing to on-chain events. It is the standard Ethereum library for the Python ecosystem, comparable to ethers.js in JavaScript.

What web3.py Does

• Connects to Ethereum nodes via HTTP, WebSocket, or IPC providers
• Reads blockchain state: blocks, transactions, balances, logs, and contract storage
• Sends raw or signed transactions for ETH transfers and contract interactions
• Compiles and interacts with smart contracts using ABI-based contract objects
• Supports middleware for transaction signing, gas estimation, POA chains, and caching

Architecture Overview

web3.py wraps Ethereum JSON-RPC calls in a Python API organized into modules: w3.eth for chain data, w3.net for network info, and w3.geth / w3.parity for client-specific extensions. A provider layer handles the transport (HTTP, WS, IPC), and a middleware pipeline lets users inject signing, gas estimation, and response processing between the application and the node. Contract objects use ABI definitions to encode/decode function calls and event logs.

Self-Hosting & Configuration

• Install: pip install web3 (or pip install web3[tester] for local testing with eth-tester)
• Connect to a node: w3 = Web3(Web3.HTTPProvider("https://your-rpc-url"))
• For local development, use Ganache or Anvil as a local Ethereum node
• Configure middleware: w3.middleware_onion.inject(middleware, layer=0) for custom processing
• Set default account and gas parameters: w3.eth.default_account, w3.eth.gas_price

Key Features

• Full JSON-RPC coverage for Ethereum execution and consensus layer APIs
• Contract abstraction with ABI-based method calling, event filtering, and log decoding
• Middleware architecture for pluggable transaction signing, gas strategies, and POA support
• ENS (Ethereum Name Service) resolution built in for human-readable addresses
• Async API support via AsyncWeb3 and AsyncHTTPProvider for non-blocking applications

Comparison with Similar Tools

• ethers.js — JavaScript equivalent with similar API surface; web3.py is the Python counterpart
• web3.js — the original JavaScript Ethereum library; web3.py offers a more Pythonic interface
• Brownie — Python smart contract framework that uses web3.py internally; web3.py is the lower-level library
• ape — modern Python framework for smart contracts with plugin architecture; web3.py focuses on node interaction without framework opinions
• alloy — Rust Ethereum library; web3.py serves the Python ecosystem where Rust is not practical

FAQ

Q: Do I need to run my own Ethereum node? A: No. You can use public RPC endpoints (Infura, Alchemy, Ankr) or local development nodes like Anvil or Ganache.

Q: Can web3.py interact with Layer 2 chains like Arbitrum or Optimism? A: Yes. Point the provider to the L2's RPC endpoint. Most EVM-compatible chains work with web3.py out of the box.

Q: How do I sign transactions without exposing private keys? A: Use w3.eth.account.sign_transaction() locally, then send the signed raw transaction. Never pass private keys to remote nodes.

Q: Does web3.py support smart contract events and logs? A: Yes. Use contract.events.EventName.create_filter() or w3.eth.get_logs() to query historical and real-time events.

Sources

• https://github.com/ethereum/web3.py
• https://web3py.readthedocs.io/