Skip to content

Development Setup

This guide covers setting up a local development environment for zae-limiter.

Prerequisites

  • Python 3.11 or 3.12
  • uv (recommended) or conda
  • Docker (for LocalStack integration tests)

Setup

git clone --recurse-submodules https://github.com/zeroae/zae-limiter.git
cd zae-limiter
uv sync --all-extras
uv tool install hatch  # Required for sync code generation

Using conda

git clone --recurse-submodules https://github.com/zeroae/zae-limiter.git
cd zae-limiter
conda create -n zae-limiter python=3.12
conda activate zae-limiter
pip install -e ".[dev]"
pip install hatch  # Required for sync code generation

Already cloned?

If you cloned without --recurse-submodules, run: 

git submodule update --init --recursive

Running Tests

# Run all unit tests
pytest tests/unit/ -v

# Run with coverage
pytest --cov --cov-report=html

# Run specific test file
pytest tests/unit/test_limiter.py -v

For integration tests with LocalStack, see the Testing Guide.

Code Quality

# Format code
ruff format .

# Lint and auto-fix
ruff check --fix .

# Type checking
mypy

Ruff is pinned to one exact version across pyproject.toml (build requirements, the dev extra, and the hatch default env), .pre-commit-config.yaml and the CI lint workflow, so the formatter you run locally and the one the commit hook runs agree byte for byte. Running ruff format . over the whole tree is therefore safe: on a clean tree it reformats nothing. The check-ruff-pin hook fails the commit if those declarations ever drift apart.

Commit Messages

Follow the ZeroAE commit conventions:

# Examples
feat(limiter): add hierarchical rate limiting support
fix(bucket): prevent integer overflow in refill calculation
docs(readme): add CloudFormation deployment guide
refactor(schema): simplify DynamoDB key structure

Project scopes: limiter, bucket, cli, infra, ci, aggregator, models, schema, repository, lease, exceptions, test, benchmark

Documentation

To preview documentation locally:

uv run mkdocs serve --livereload --dirty

Then open http://localhost:8000/zae-limiter/ in your browser.

Live reload requires --livereload

Due to a known issue with Click 8.3.x, the --livereload flag must be explicitly passed for automatic browser refresh to work.

Next Steps