fastapi-traffic/DEVELOPMENT.md

Development Guide

Want to contribute or just poke around? Here's how to get set up.

What you'll need

• Python 3.10 or newer
• uv (recommended) or pip
• Docker if you want to test the Redis backend

Getting started

Using uv (the fast way)

git clone https://gitlab.com/bereckobrian/fastapi-traffic.git
cd fastapi-traffic

# This creates a venv and installs everything
uv sync

That's it. uv figures out the rest.

Using pip

git clone https://gitlab.com/bereckobrian/fastapi-traffic.git
cd fastapi-traffic

python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

pip install -e ".[dev]"

Redis for testing (optional)

If you want to run the Redis backend tests:

docker run -d -p 6379:6379 redis:alpine

Running tests

We have 134 tests covering algorithms, backends, decorators, middleware, and integration scenarios.

# Run everything
uv run pytest

# Or with pip
pytest

# With coverage report
pytest --cov=fastapi_traffic

# Just one file
pytest tests/test_algorithms.py

# Match a pattern
pytest -k "token_bucket"

Tests run async by default via pytest-asyncio.

Type checking

We use pyright in strict mode:

uv run pyright
# or just: pyright

VS Code with Pylance gives you real-time feedback.

Linting

Ruff handles both linting and formatting:

# Check for issues
uv run ruff check .

# Auto-fix
uv run ruff check . --fix

# Format
uv run ruff format .

Running examples

The examples/ folder has working examples you can run:

# Basic usage
uv run python examples/01_quickstart.py

# Redis example (needs Redis running)
REDIS_URL=redis://localhost:6379/0 uv run python examples/07_redis_distributed.py

Then open http://localhost:8000 in your browser.

Project layout

fastapi_traffic/
├── __init__.py          # Public exports
├── exceptions.py        # Custom exceptions
├── middleware.py        # ASGI middleware
├── backends/
│   ├── base.py          # Backend interface
│   ├── memory.py        # In-memory (default)
│   ├── sqlite.py        # SQLite
│   └── redis.py         # Redis
└── core/
    ├── algorithms.py    # Rate limiting algorithms
    ├── config.py        # Configuration
    ├── decorator.py     # @rate_limit decorator
    └── limiter.py       # RateLimiter class

Adding a backend

1. Create a file in fastapi_traffic/backends/
2. Subclass Backend from base.py
3. Implement: get, set, delete, exists, increment, clear
4. Optionally: ping, get_stats, close
5. Add tests in tests/test_backends.py
6. Export from __init__.py if public

Adding an algorithm

1. Add enum value to Algorithm in core/algorithms.py
2. Create a handler class
3. Register it in the dispatcher
4. Add tests in tests/test_algorithms.py
5. Document in README

Tips

• Memory backend is great for development - no dependencies
• Use skip_on_error=True if you don't want backend errors blocking requests
• Check examples for real usage patterns

Questions?

Open an issue. Happy to help.