eth-utils

The eth_utils package is organized into several specialized submodules and subpackages to handle Ethereum-specific data types and operations. Key functional areas include:

• Core Ethereum Types: eth_utils.address, eth_utils.abi, eth_utils.types, and eth_utils.units.
• Data Conversion & Encoding: eth_utils.conversions, eth_utils.encoding, and eth_utils.hexadecimal.
• Mathematical & Numeric Operations: eth_utils.numeric, eth_utils.currency, and eth_utils.units.
• Functional Programming & Utilities: eth_utils.functional, eth_utils.applicators, eth_utils.curried, and eth_utils.toolz.
• Security & Debugging: eth_utils.crypto, eth_utils.debug, and eth_utils.logging.
• Developer Ergonomics: eth_utils.humanize, eth_utils.decorators, and eth_utils.exceptions.

Applicators are tools used to apply "formatters" to data structures. A formatter is defined as any callable that accepts a single positional argument and returns a formatted result (e.g., int(), str(), or a custom function).

Applicators allow you to:

• Apply formatters to dictionary values by key.
• Apply formatters to lists/sequences by index.
• Conditionally apply a formatter based on a predicate.
• Apply one of several formatters based on which condition matches first.

Use the make release command to bump the version. You must specify which part of the version to bump using the bump argument.

Version Formats:

• Stable: {major}.{minor}.{patch}
• Unstable: {major}.{minor}.{patch}-{stage}.{devnum} (where stage is alpha or beta).

Common Commands:

• make release bump=minor: Bumps the minor version.
• make release bump=stage: If currently in a beta version, this switches to a stable version.
• make release bump="--new-version 4.0.0-alpha.1 devnum": Issues an unstable version from a stable state by specifying the new version explicitly.

make release bump=$$VERSION_PART_TO_BUMP$$

All utility functions can be imported directly from the eth_utils module. For a functional programming style, you can import curried versions of these functions from the eth_utils.curried module.

# Standard import
from eth_utils import some_function

# Curried import
from eth_utils.curried import hexstr_if_str

To use eth-utils in your project, install the package using pip from PyPI. Note that the package name is eth-utils (formerly ethereum-utils).

python -m pip install eth-utils

If you are contributing to eth-utils, follow these steps to set up your environment:

1. Clone the repository.
2. Create and activate a Python 3 virtual environment.
3. Install the package in editable mode with development dependencies.
4. Install pre-commit hooks to maintain code style automatically.

git clone git@github.com:ethereum/eth-utils.git
cd eth-utils
virtualenv -p python3 venv
. venv/bin/activate
python -m pip install -e ".[dev]"
pre-commit install

To contribute to eth-utils, fork the repository, clone it locally, and set up a virtual environment with development dependencies. It is recommended to use virtualenv and install the package in editable mode with the [dev] extra to include testing and linting tools.

git clone git@github.com:your-github-username/eth-utils.git

cd eth-utils
virtualenv -p python venv
. venv/bin/activate
python -m pip install -e ".[dev]"
pre-commit install

To contribute to the release notes, you must create a "newsfragment" in the newsfragments/ directory. A newsfragment is a short ReST-formatted text file describing changes relevant to end-users.

Naming Convention: Files must be named using the pattern <ISSUE>.<TYPE>.rst:

• <ISSUE>: The issue number (or PR number if no issue exists).
• <TYPE>: One of the following allowed types:
  • breaking
  • bugfix
  • deprecation
  • docs
  • feature
  • internal
  • misc
  • performance
  • removal

Example filenames:

• 123.feature.rst
• 456.bugfix.rst

Formatting Note: Do not use complex formatting. The towncrier tool will automatically reflow your text during the release process.

# Example of creating a newsfragment file
touch 123.feature.rst

The library uses a JSON file located at eth_utils/__json/eth_networks.json to initialize Networks objects, which allow you to retrieve network information using a chain ID. To update this local JSON file with the latest information from the remote list, run the update_networks.py script.

python update_networks.py

To build the project documentation locally, install the documentation dependencies using the [docs] extra, navigate to the docs directory, and use make html.

python -m pip install -e ".[docs]"
cd docs
make html

You can preview how your newsfragment will appear in the final release notes by using the towncrier tool with the --draft flag. This is useful for checking how the text reflow will look before the actual release.

towncrier build --draft