Update docs to be more readable and add uv instructions

Rewrote README and DEVELOPMENT.md to sound less robotic. Added changelog documenting the new test suite and other recent changes.
2026-01-09 00:50:57 +00:00
parent 9fe700296d
commit e658aa92a2
3 changed files with 219 additions and 24 deletions
--- a/DEVELOPMENT.md
+++ b/DEVELOPMENT.md
@@ -0,0 +1,152 @@
+# 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.