zanewalker
f3453cb0fc
- Refactor Redis backend connection handling and pool management - Update algorithm implementations with improved type annotations - Enhance config loader validation with stricter Pydantic schemas - Improve decorator and middleware error handling - Expand example scripts with better docstrings and usage patterns - Add new 00_basic_usage.py example for quick start - Reorganize examples directory structure - Fix type annotation inconsistencies across core modules - Update dependencies in pyproject.toml
205 lines
4.3 KiB
ReStructuredText
205 lines
4.3 KiB
ReStructuredText
Contributing
|
|
============
|
|
|
|
Thanks for your interest in contributing to FastAPI Traffic! This guide will help
|
|
you get started.
|
|
|
|
Development Setup
|
|
-----------------
|
|
|
|
1. **Clone the repository:**
|
|
|
|
.. code-block:: bash
|
|
|
|
git clone https://gitlab.com/zanewalker/fastapi-traffic.git
|
|
cd fastapi-traffic
|
|
|
|
2. **Install uv** (if you don't have it):
|
|
|
|
.. code-block:: bash
|
|
|
|
curl -LsSf https://astral.sh/uv/install.sh | sh
|
|
|
|
3. **Create a virtual environment and install dependencies:**
|
|
|
|
.. code-block:: bash
|
|
|
|
uv venv
|
|
source .venv/bin/activate # or .venv\Scripts\activate on Windows
|
|
uv pip install -e ".[dev]"
|
|
|
|
4. **Verify everything works:**
|
|
|
|
.. code-block:: bash
|
|
|
|
pytest
|
|
|
|
Running Tests
|
|
-------------
|
|
|
|
Run the full test suite:
|
|
|
|
.. code-block:: bash
|
|
|
|
pytest
|
|
|
|
Run with coverage:
|
|
|
|
.. code-block:: bash
|
|
|
|
pytest --cov=fastapi_traffic --cov-report=html
|
|
|
|
Run specific tests:
|
|
|
|
.. code-block:: bash
|
|
|
|
pytest tests/test_algorithms.py
|
|
pytest -k "test_token_bucket"
|
|
|
|
Code Style
|
|
----------
|
|
|
|
We use ruff for linting and formatting:
|
|
|
|
.. code-block:: bash
|
|
|
|
# Check for issues
|
|
ruff check .
|
|
|
|
# Auto-fix issues
|
|
ruff check --fix .
|
|
|
|
# Format code
|
|
ruff format .
|
|
|
|
Type Checking
|
|
-------------
|
|
|
|
We use pyright for type checking:
|
|
|
|
.. code-block:: bash
|
|
|
|
pyright
|
|
|
|
The codebase is strictly typed. All public APIs should have complete type hints.
|
|
|
|
Making Changes
|
|
--------------
|
|
|
|
1. **Create a branch:**
|
|
|
|
.. code-block:: bash
|
|
|
|
git checkout -b feature/my-feature
|
|
|
|
2. **Make your changes.** Follow the existing code style.
|
|
|
|
3. **Add tests.** All new features should have tests.
|
|
|
|
4. **Run the checks:**
|
|
|
|
.. code-block:: bash
|
|
|
|
ruff check .
|
|
ruff format .
|
|
pyright
|
|
pytest
|
|
|
|
5. **Commit your changes:**
|
|
|
|
.. code-block:: bash
|
|
|
|
git commit -m "feat: add my feature"
|
|
|
|
We follow `Conventional Commits <https://www.conventionalcommits.org/>`_:
|
|
|
|
- ``feat:`` New features
|
|
- ``fix:`` Bug fixes
|
|
- ``docs:`` Documentation changes
|
|
- ``style:`` Code style changes (formatting, etc.)
|
|
- ``refactor:`` Code refactoring
|
|
- ``test:`` Adding or updating tests
|
|
- ``chore:`` Maintenance tasks
|
|
|
|
6. **Push and create a merge request:**
|
|
|
|
.. code-block:: bash
|
|
|
|
git push origin feature/my-feature
|
|
|
|
Project Structure
|
|
-----------------
|
|
|
|
.. code-block:: text
|
|
|
|
fastapi-traffic/
|
|
├── fastapi_traffic/
|
|
│ ├── __init__.py # Public API exports
|
|
│ ├── exceptions.py # Custom exceptions
|
|
│ ├── middleware.py # Rate limit middleware
|
|
│ ├── backends/
|
|
│ │ ├── base.py # Backend abstract class
|
|
│ │ ├── memory.py # In-memory backend
|
|
│ │ ├── sqlite.py # SQLite backend
|
|
│ │ └── redis.py # Redis backend
|
|
│ └── core/
|
|
│ ├── algorithms.py # Rate limiting algorithms
|
|
│ ├── config.py # Configuration classes
|
|
│ ├── config_loader.py # Configuration loading
|
|
│ ├── decorator.py # @rate_limit decorator
|
|
│ ├── limiter.py # Main RateLimiter class
|
|
│ └── models.py # Data models
|
|
├── tests/
|
|
│ ├── test_algorithms.py
|
|
│ ├── test_backends.py
|
|
│ ├── test_decorator.py
|
|
│ └── ...
|
|
├── examples/
|
|
│ ├── 01_quickstart.py
|
|
│ └── ...
|
|
└── docs/
|
|
└── ...
|
|
|
|
Guidelines
|
|
----------
|
|
|
|
**Code:**
|
|
|
|
- Keep functions focused and small
|
|
- Use descriptive variable names
|
|
- Add docstrings to public functions and classes
|
|
- Follow existing patterns in the codebase
|
|
|
|
**Tests:**
|
|
|
|
- Test both happy path and edge cases
|
|
- Use descriptive test names
|
|
- Mock external dependencies (Redis, etc.)
|
|
- Keep tests fast and isolated
|
|
|
|
**Documentation:**
|
|
|
|
- Update docs when adding features
|
|
- Include code examples
|
|
- Keep language clear and concise
|
|
|
|
Reporting Issues
|
|
----------------
|
|
|
|
Found a bug? Have a feature request? Please open an issue on GitLab:
|
|
|
|
https://gitlab.com/zanewalker/fastapi-traffic/issues
|
|
|
|
Include:
|
|
|
|
- What you expected to happen
|
|
- What actually happened
|
|
- Steps to reproduce
|
|
- Python version and OS
|
|
- FastAPI Traffic version
|
|
|
|
Questions?
|
|
----------
|
|
|
|
Feel free to open an issue for questions. We're happy to help!
|