zanewalker
e658aa92a2
Rewrote README and DEVELOPMENT.md to sound less robotic. Added changelog documenting the new test suite and other recent changes.
153 lines
3.1 KiB
Markdown
153 lines
3.1 KiB
Markdown
# 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](https://github.com/astral-sh/uv) (recommended) or pip
|
|
- Docker if you want to test the Redis backend
|
|
|
|
## Getting started
|
|
|
|
### Using uv (the fast way)
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
docker run -d -p 6379:6379 redis:alpine
|
|
```
|
|
|
|
## Running tests
|
|
|
|
We have 134 tests covering algorithms, backends, decorators, middleware, and integration scenarios.
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
uv run pyright
|
|
# or just: pyright
|
|
```
|
|
|
|
VS Code with Pylance gives you real-time feedback.
|
|
|
|
## Linting
|
|
|
|
Ruff handles both linting and formatting:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# 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.
|