eth-typing: Common type annotations for ethereum python packages

6.0.0 · active · verified Thu Apr 09

eth-typing provides common type annotations for various Ethereum Python packages, offering a standardized set of types for improved type hinting and code clarity across the Ethereum ecosystem. It is actively maintained with frequent releases, currently at version 6.0.0, supporting modern Python versions. [1, 2, 5]

Common errors

```
ModuleNotFoundError: No module named 'eth_typing'
```
cause The 'eth-typing' library is not installed in your Python environment, or there's an issue with the installation, often due to missing C++ build tools on Windows.

fix Run `pip install eth-typing` to install the library. On Windows, if this fails, you may need to install 'Microsoft C++ Build Tools' for Python to compile certain dependencies.
```
ImportError: cannot import name 'X' from 'eth_typing'
```
cause The specific type 'X' you are trying to import from 'eth_typing' has either been renamed, moved to a different submodule, or removed in the installed version of the library (e.g., due to API changes between major versions). For example, `ContractName` was moved in a past update.

fix Check the `eth-typing` documentation (for version 6.0.0 or your installed version) to find the correct import path or the new name for the type. You might need to import from a submodule like `eth_typing.evm` or `eth_typing.abi`, or use an updated type name. If migrating from older versions, pin `eth-typing` to a compatible version or update your code to match the new API.
```
ERROR: <package_name> has requirement eth-typing<X,>=Y, but you'll have eth-typing Z which is incompatible.
```
cause This error indicates a dependency conflict where another installed library (`<package_name>`) requires a different version range of `eth-typing` than what is currently installed or being attempted to install, leading to an incompatible package environment.

fix Upgrade the conflicting packages to compatible versions using `pip install --upgrade <package_name> eth-typing` or explicitly specify compatible versions for all conflicting libraries in your `requirements.txt` file (e.g., `eth-typing==Z`, `eth-utils==A`). Consider using a virtual environment to manage dependencies for different projects.
```
Web3.py only accepts checksum addresses. The software that gave you this non-checksum address should be considered unsafe, please file it as a bug on their platform. Try using an ENS name instead. Or, if you must accept lower safety, use Web3.toChecksumAddress(lower_case_address).
```
cause You are attempting to use an Ethereum address string that is not a checksummed address (as defined by EIP-55) with `web3.py`. `web3.py` (which relies on `eth-typing` for address types) enforces checksumming to prevent common typos and increase safety.

fix Convert the non-checksummed address to a checksummed address using `Web3.toChecksumAddress()` before passing it to `web3.py` functions. Example: `from web3 import Web3; w3 = Web3(Web3.HTTPProvider('http://localhost:8545')); checksum_address = w3.toChecksumAddress('0x06012c8cf97bead5deae237070f9587f8e7a266d')`.

Warnings

breaking Version 6.0.0 drops support for Python 3.8 and 3.9. Users on these Python versions should remain on `eth-typing<6` or upgrade their Python environment. [10]
Fix: Upgrade Python to 3.10+ or pin `eth-typing` version to `<6.0.0`.
deprecated Several ABI-related TypedDict attributes (e.g., `constant`, `payable` in function types) are deprecated in favor of `stateMutability`. Additionally, specific function types (`ABIFunction`, `ABIConstructor`, etc.) should be used instead of the general `ABIElement` for clarity. [1, 9]
Fix: Review ABI definitions and update them to use `stateMutability` and more specific ABI element types as recommended by the documentation.
gotcha Many fields in `eth-typing`'s `TypedDict` definitions (especially in `eth_typing.abi`) use `typing.NotRequired`. This means type checkers will not enforce their presence. Developers expecting all fields to be mandatory might face unexpected `KeyError`s at runtime if not handled defensively. [1]
Fix: Be aware of `NotRequired` fields in `TypedDicts`. Explicitly check for key existence or provide default values when accessing such fields. Type checkers will warn if you access a `NotRequired` field without a check if `strict` mode is enabled.

Install

pip install eth-typing Install stable version

Imports

TypeStr
```
from eth_typing import TypeStr
```
HexStr
```
from eth_typing.encoding import HexStr
```
Address
wrong:
```
from eth_typing import Address
```
correct:
```
from eth_typing.evm import Address
```
Specific EVM-related types are found in submodules like `eth_typing.evm`.
ChecksumAddress
wrong:
```
from eth_typing.evm import HexAddress
```
correct:
```
from eth_typing.evm import ChecksumAddress
```
Use `ChecksumAddress` for ERC-55 formatted addresses, `HexAddress` for general hex-encoded addresses. [9]
ABI
wrong:
```
from eth_typing import ABI
```
correct:
```
from eth_typing.abi import ABI
```
ABI-related types are located in the `eth_typing.abi` submodule. [1, 9]

Quickstart

Demonstrates importing and using `Address`, `ChecksumAddress`, and `HexStr` for type hinting. This example simplifies address processing as `eth-typing` focuses solely on type definitions, not implementation logic.

from eth_typing.evm import Address, ChecksumAddress
from eth_typing.encoding import HexStr

def process_ethereum_address(address: Address) -> ChecksumAddress:
    # In a real application, you would perform checksum validation
    # or other address-related logic here.
    # For this example, we'll just cast it for demonstration.
    # eth-utils or web3.py typically handle checksumming.
    if not isinstance(address, str) or not address.startswith('0x'):
        raise ValueError('Invalid address format')
    # Simulate a checksummed address return
    return ChecksumAddress(address.lower()) # Simplified for quickstart

my_raw_address: Address = Address('0x742d35Cc6634C0532925a3b844Bc454e4438f444')
checksum_addr: ChecksumAddress = process_ethereum_address(my_raw_address)

print(f'Processed Address: {checksum_addr}')

def get_hex_string_length(hex_str: HexStr) -> int:
    return len(hex_str)

my_hex_string: HexStr = HexStr('0xabcdef123456')
print(f'Hex string length: {get_hex_string_length(my_hex_string)}')

view raw JSON →