0
# eth-utils
1
2
A comprehensive utility library providing essential functions for Python applications that interact with Ethereum blockchain and related technologies. It offers tools for address validation, ABI processing, data conversions, cryptographic operations, currency handling, and more.
3
4
## Package Information
5
6
- **Package Name**: eth-utils
7
- **Language**: Python
8
- **Installation**: `pip install eth-utils`
9
- **Version**: 5.3.1
10
- **License**: MIT
11
12
## Core Imports
13
14
```python
15
import eth_utils
16
```
17
18
Common imports for specific functionality:
19
20
```python
21
from eth_utils import (
22
# Address handling
23
is_address, to_checksum_address, is_checksum_address,
24
# Data conversions
25
to_bytes, to_hex, to_int, to_text,
26
# ABI processing
27
function_signature_to_4byte_selector, event_signature_to_log_topic,
28
# Currency conversions
29
from_wei, to_wei, denoms,
30
# Hexadecimal utilities
31
encode_hex, decode_hex, is_hex,
32
# Type checking
33
is_integer, is_string, is_bytes
34
)
35
```
36
37
## Basic Usage
38
39
```python
40
from eth_utils import (
41
to_checksum_address, to_wei, from_wei,
42
keccak, to_bytes, encode_hex
43
)
44
45
# Address validation and formatting
46
address = "0xd3cda913deb6f67967b99d67acdfa1712c293601"
47
checksum_addr = to_checksum_address(address)
48
print(checksum_addr) # 0xd3CdA913deB6f67967B99D67aCDFa1712C293601
49
50
# Currency conversions
51
wei_amount = to_wei(1.5, 'ether') # Convert 1.5 ETH to wei
52
eth_amount = from_wei(wei_amount, 'ether') # Convert back to ETH
53
54
# Data conversions and hashing
55
data = to_bytes(text="Hello, Ethereum!")
56
hash_result = keccak(data)
57
hex_hash = encode_hex(hash_result)
58
59
# ABI function selector generation
60
from eth_utils import function_signature_to_4byte_selector
61
selector = function_signature_to_4byte_selector("transfer(address,uint256)")
62
print(encode_hex(selector)) # 0xa9059cbb
63
```
64
65
## Architecture
66
67
eth-utils is organized into focused modules that address specific aspects of Ethereum development:
68
69
- **Core Data Types**: Address, hex string, and byte handling with format validation
70
- **ABI Processing**: Smart contract interface manipulation and signature generation
71
- **Type System**: Comprehensive type checking and conversion utilities
72
- **Functional Patterns**: Curried functions and applicators for data transformation
73
- **Debugging Tools**: Environment introspection and development utilities
74
75
The library follows a zero-dependency core philosophy while providing optional extensions, ensuring minimal overhead and maximum compatibility across Python 3.8+ environments.
76
77
## Capabilities
78
79
### Address Operations
80
81
Comprehensive Ethereum address handling including validation, format conversion, and EIP-55 checksum processing. Supports all address formats: binary (20 bytes), hex, normalized, and checksummed.
82
83
```python { .api }
84
def is_address(value) -> bool: ...
85
def to_checksum_address(value) -> str: ...
86
def is_checksum_address(value) -> bool: ...
87
def to_canonical_address(address) -> bytes: ...
88
def is_same_address(left, right) -> bool: ...
89
```
90
91
[Address Operations](./address-operations.md)
92
93
### ABI Processing
94
95
Smart contract ABI manipulation including signature generation, function selectors, event topics, and parameter extraction. Essential for contract interaction and transaction processing.
96
97
```python { .api }
98
def function_signature_to_4byte_selector(function_signature: str) -> bytes: ...
99
def event_signature_to_log_topic(event_signature: str) -> bytes: ...
100
def abi_to_signature(abi_element) -> str: ...
101
def filter_abi_by_type(abi_type: str, contract_abi) -> list: ...
102
```
103
104
[ABI Processing](./abi-processing.md)
105
106
### Data Conversions
107
108
Flexible type conversion utilities supporting multiple input formats (primitive values, hex strings, text) with consistent output types. Core functionality for data transformation pipelines.
109
110
```python { .api }
111
def to_bytes(primitive=None, hexstr=None, text=None) -> bytes: ...
112
def to_hex(primitive=None, hexstr=None, text=None) -> str: ...
113
def to_int(primitive=None, hexstr=None, text=None) -> int: ...
114
def to_text(primitive=None, hexstr=None, text=None) -> str: ...
115
```
116
117
[Data Conversions](./data-conversions.md)
118
119
### Currency and Units
120
121
Ethereum currency conversions between wei and various denominations (ether, gwei, finney, etc.) with precise decimal handling and comprehensive denomination constants.
122
123
```python { .api }
124
def to_wei(number, unit: str) -> int: ...
125
def from_wei(number: int, unit: str) -> Union[int, Decimal]: ...
126
class denoms:
127
wei: int
128
gwei: int
129
ether: int
130
...
131
```
132
133
[Currency and Units](./currency-units.md)
134
135
### Hexadecimal Utilities
136
137
Hex string processing including encoding, decoding, prefix handling, and validation. Essential for working with Ethereum's hex-encoded data formats.
138
139
```python { .api }
140
def encode_hex(value) -> str: ...
141
def decode_hex(value: str) -> bytes: ...
142
def is_hex(value) -> bool: ...
143
def add_0x_prefix(value: str) -> str: ...
144
def remove_0x_prefix(value: str) -> str: ...
145
```
146
147
[Hexadecimal Utilities](./hexadecimal-utilities.md)
148
149
### Type Checking
150
151
Comprehensive type validation utilities for common Python and Ethereum-specific data types. Provides reliable type checking for data validation pipelines.
152
153
```python { .api }
154
def is_integer(value) -> bool: ...
155
def is_string(value) -> bool: ...
156
def is_bytes(value) -> bool: ...
157
def is_boolean(value) -> bool: ...
158
def is_list_like(obj) -> bool: ...
159
```
160
161
[Type Checking](./type-checking.md)
162
163
### Cryptographic Functions
164
165
Cryptographic utilities centered around Keccak-256 hashing with flexible input handling. Essential for Ethereum hash computations.
166
167
```python { .api }
168
def keccak(primitive=None, hexstr=None, text=None) -> bytes: ...
169
```
170
171
[Cryptographic Functions](./crypto-functions.md)
172
173
### Data Formatting
174
175
Advanced data transformation utilities including formatters, applicators, and functional programming tools for complex data processing workflows.
176
177
```python { .api }
178
def apply_formatters_to_dict(formatters, value) -> dict: ...
179
def apply_formatter_if(condition, formatter, value): ...
180
def apply_key_map(key_mappings, value) -> dict: ...
181
```
182
183
[Data Formatting](./data-formatting.md)
184
185
### Logging and Debugging
186
187
Enhanced logging capabilities with DEBUG2 level support and environment introspection tools for development and troubleshooting.
188
189
```python { .api }
190
def get_logger(name: str) -> Logger: ...
191
def get_extended_debug_logger(name: str) -> ExtendedDebugLogger: ...
192
def get_environment_summary() -> str: ...
193
```
194
195
[Logging and Debugging](./logging-debugging.md)
196
197
### Network Information
198
199
Ethereum network data including chain IDs, network names, and metadata for all major Ethereum networks and testnets.
200
201
```python { .api }
202
def network_from_chain_id(chain_id: int) -> Network: ...
203
def name_from_chain_id(chain_id: int) -> str: ...
204
class Network:
205
chain_id: int
206
name: str
207
shortName: str
208
symbol: str
209
```
210
211
[Network Information](./network-information.md)
212
213
### Functional Programming
214
215
Functional programming utilities including curried functions, return value transformers, and functional composition tools for advanced data processing patterns.
216
217
```python { .api }
218
def apply_to_return_value(callback): ...
219
def to_tuple(func): ...
220
def flatten_return(func): ...
221
from eth_utils.curried import filter_abi_by_type, apply_formatter_if
222
```
223
224
[Functional Programming](./functional-programming.md)
225
226
## Error Handling
227
228
eth-utils defines custom exceptions for validation failures:
229
230
```python { .api }
231
class ValidationError(Exception):
232
"""Raised when validation of input data fails."""
233
```
234
235
Most functions will raise `ValidationError` for invalid inputs, `TypeError` for incorrect types, and `ValueError` for values outside expected ranges.