Development guidelines for web3-ethereum-defi Python library - a DeFi trading automation toolkit supporting Uniswap, Aave, Chainlink, and other protocols. Includes British English style, Poetry environment management, pytest workflows, and blockchain RPC configuration.
Development instructions for the tradingstrategy-ai/web3-ethereum-defi codebase - a Python library for trading automation on DeFi, data research and integration.
1. **Use British English** throughout the codebase
- Write "visualise" not "visualize"
- Write "colour" not "color"
- Write "analyse" not "analyze"
2. **Heading Capitalization**
- Only capitalize the first letter of headings
- Do NOT use title case
- Example: "Running Python scripts" not "Running Python Scripts"
Always use Poetry to run Python scripts to ensure the virtual environment is activated:
```shell
poetry run python scripts/logos/post-process-logo.py
```
Never use plain `python` command.
Before running tests for the first time:
1. Ensure the user has created a gitignored file `.local-test.env` in the repository root
2. This file contains a `source` command to include test secrets from outside the repository
3. **NEVER edit this file** - always ask the user to prepare it
1. **Always use Poetry with environment secrets**:
```shell
source .local-test.env && poetry run pytest {test case name or pattern}
```
2. **Always prefix pytest with the source command** - tests need environment variables
3. **Avoid running the entire test suite** - it takes several minutes. Run specific test cases only.
4. **Use extended timeout** for all test commands:
- Specify `timeout: 180000` (3 minutes) in bash tool parameters
5. **For extra output** pass `--log-cli-level=info` to pytest
Environment variables like `JSON_RPC_ETHEREUM`, `JSON_RPC_ARBITRUM` interact with EVM-based blockchains.
**Important RPC URL format rules**:
**Available RPC environment variables**:
Find these in `CHAIN_NAMES` and `eth_defi.provider.env`.
Format code using Ruff via Poetry:
```shell
poetry run ruff format
```
1. **Never push directly to master** - always open a pull request
2. **Do not include test plan** in PR description
3. **For feature PRs**:
- Start title with "feat:" prefix
- Add one line about the feature to `CHANGELOG.md`
- Follow date format: "Something was updated (YYYY-MM-DD)"
4. **Before opening or updating a PR** - format the code
1. **Prefer `dataclass(slots=True)`** for data structures
2. **Use threaded code** instead of async Python
3. **Always type hint** function arguments and return values
4. **Type hints for blockchain**:
- Use `HexAddress` instead of `str` for blockchain addresses
- Use `eth_defi.types.Percent` instead of raw float for percentages
1. **Prefer functional helpers** over loops:
- Use Pandas `apply()` and other functional helpers instead of slow for/while loops
- Use `any()` and `all()` with generators and list comprehension for collection checks
2. **Function returns**:
- Try to return `Iterator` instead of `list` to make functions faster
3. **Naming conventions**:
- Prefix functions that do network reads with `fetch_` not `get_`
4. **Progress bars**:
- For long-running loops, use `tqdm` and `tqdm_loggable.auto` module
- See `lead_scan_core.py` as example
5. **Visualizations**:
- Use Plotly
- Use heading case for chart titles (first letter capitalized only)
1. **Use naive UTC datetimes everywhere**
2. **Import pattern**: `import datetime.datetime`
3. **Type hints**: Use `datetime.datetime` and `datetime.timedelta`
4. **Instead of** `datetime.datetime.utcnow()` **use** `native_datetime_utc_now()` for Python version compatibility
For string enums: both members and values must be in snake_case
1. **Module-level logger pattern**:
```python
logger = logging.getLogger(__name__)
```
2. **String formatting in logs**:
- Prefer `%s` and `%f` unexpanded syntax
- Do NOT use Python string interpolation (for performance)
- Example: `logger.info("Value: %s", value)` not `logger.info(f"Value: {value}")`
1. **Use Sphinx restructured text style** for code comments
2. **For dataclass and Enum members**:
- Use `#: comment here` line comment above variable
- Do NOT use `:param:`
3. **For inherited function overloads**:
- If nothing new to comment, leave empty instead of repeating parent comment
4. **API documentation**:
- All API modules should have stub entry under `docs/source/api`
- Cross-reference in `docs/source/api/index` table of contents
- See `docs/source/api/index.rst` and `docs/source/api/lagoon/index.rst` as examples
5. **In documentation sentences**:
- Include inline links to source pages
- Link each page only once, preferably earlier in the text
1. **Never use test classes** in pytest
2. **No stdout output** like `print` in tests
3. **For fuzzy float comparison**:
- Use `pytest.approx()` instead of manual comparison like `assert abs(value - expected) < 0.01`
4. **DuckDB testing**:
- Always close database using finally clause or fixtures
5. **Always use fixture and test functions** - never test classes
When adding or updating dependencies in `pyproject.toml`, always add a comment explaining why the dependency is needed.
Whenever possible, prefer table output instead of `print()`:
1. **Use environment variables** - do not create command line parsers unless explicitly asked
2. **Logger setup example**: See `scripts/erc-4626/scan-vaults.py`
3. **Tabular output**:
- Do NOT use `print()` loops
- Use `tabulate.tabulate()` function
- See `whitelist-vaults.py` as example
4. **Parallelization**:
- Functions using `joblib.Parallel` must take `max_workers` argument
- Expose to command line as `MAX_WORKERS` environment variable
- See `scripts/erc-4626/scan-vaults.py` as example
1. **Use `joblib.Parallel`** to parallelize API reading of multiple entries
2. **Use threading backend** unless explicitly specified otherwise
3. **Example**: See `lead_scan_core.py`
4. **All parallel functions**:
- Must take `max_workers` argument
- Expose as `MAX_WORKERS` environment variable in scripts
1. **Prefer blockchain explorers** (like Etherscan) over Python/curl for reading proxy contract addresses
2. **Prefer Python snippets** over `curl` for reading data from blockchain explorers
3. **Get latest block number**: Use `web3.eth.block_number` with Web3.py
4. **NEVER figure out RPC URLs yourself**:
- Always use environment variables from local environment
- See `eth_defi.chain.CHAIN_NAMES` for aliases (e.g., chain id 999 -> JSON_RPC_HYPERLIQUID)
- Stop and ask user if you cannot figure it out
Documentation uses Sphinx v4.5 in the `docs` folder.
**Build documentation**:
```shell
source .local-test.env && make build-docs
```
**Clean Sphinx autosummaries**:
```shell
source .local-test.env && make clean-docs
```
**Never directly edit** auto-generated Sphinx files in `_autosummary*` folders.
**Running a specific test**:
```shell
source .local-test.env && poetry run pytest tests/test_uniswap.py::test_swap -v --log-cli-level=info
```
**Running a Python script**:
```shell
poetry run python scripts/erc-4626/scan-vaults.py
```
**Formatting code before PR**:
```shell
poetry run ruff format
```
Leave a review
No reviews yet. Be the first to review this skill!
# Download SKILL.md from killerskills.ai/api/skills/web3-ethereum-defi-development-qifqug/raw