Metadata-Version: 2.4
Name: fastapi-420
Version: 1.0.1
Summary: Enhance Your Calm - Advanced Rate Limiting & DDoS Protection for FastAPI
Project-URL: Homepage, https://github.com/CarterPerez-dev/Cybersecurity-Projects
Project-URL: Documentation, https://github.com/CarterPerez-dev/Cybersecurity-Projects/blob/main/PROJECTS/advanced/api-rate-limiter/examples/USAGE.md
Project-URL: Repository, https://github.com/CarterPerez-dev/Cybersecurity-Projects/tree/main/PROJECTS/advanced/api-rate-limiter
Project-URL: Issues, https://github.com/CarterPerez-dev/Cybersecurity-Projects/issues
License: MIT
License-File: LICENSE
Keywords: 420,api,ddos,fastapi,rate-limiting,security
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Security
Classifier: Typing :: Typed
Requires-Python: >=3.14
Requires-Dist: fastapi[standard]>=0.128.7
Requires-Dist: pydantic-settings<3.0.0,>=2.12.0
Requires-Dist: pydantic<3.0.0,>=2.12.5
Requires-Dist: pyjwt>=2.11.0
Requires-Dist: redis>=7.1.1
Provides-Extra: dev
Requires-Dist: asgi-lifespan>=2.1.0; extra == 'dev'
Requires-Dist: fakeredis>=2.33.0; extra == 'dev'
Requires-Dist: httpx>=0.28.1; extra == 'dev'
Requires-Dist: mypy>=1.19.1; extra == 'dev'
Requires-Dist: pre-commit>=4.5.1; extra == 'dev'
Requires-Dist: pylint-per-file-ignores>=3.2.0; extra == 'dev'
Requires-Dist: pylint-pydantic>=0.4.1; extra == 'dev'
Requires-Dist: pylint>=4.0.4; extra == 'dev'
Requires-Dist: pytest-asyncio>=1.3.0; extra == 'dev'
Requires-Dist: pytest-cov>=7.0.0; extra == 'dev'
Requires-Dist: pytest>=9.0.2; extra == 'dev'
Requires-Dist: ruff>=0.15.0; extra == 'dev'
Requires-Dist: time-machine>=3.2.0; extra == 'dev'
Requires-Dist: types-redis>=4.6.0.20241004; extra == 'dev'
Description-Content-Type: text/markdown

```ruby
███████╗ █████╗ ███████╗████████╗ █████╗ ██████╗ ██╗     ██╗  ██╗██████╗  ██████╗
██╔════╝██╔══██╗██╔════╝╚══██╔══╝██╔══██╗██╔══██╗██║     ██║  ██║╚════██╗██╔═████╗
█████╗  ███████║███████╗   ██║   ███████║██████╔╝██║     ███████║ █████╔╝██║██╔██║
██╔══╝  ██╔══██║╚════██║   ██║   ██╔══██║██╔═══╝ ██║     ╚════██║██╔═══╝ ████╔╝██║
██║     ██║  ██║███████║   ██║   ██║  ██║██║     ██║          ██║███████╗╚██████╔╝
╚═╝     ╚═╝  ╚═╝╚══════╝   ╚═╝   ╚═╝  ╚═╝╚═╝     ╚═╝          ╚═╝╚══════╝ ╚═════╝
```

[![Cybersecurity Projects](https://img.shields.io/badge/Cybersecurity--Projects-Project%20%235-red?style=flat&logo=github)](https://github.com/CarterPerez-dev/Cybersecurity-Projects/tree/main/PROJECTS/advanced/api-rate-limiter)
[![Python](https://img.shields.io/badge/Python-3.12+-3776AB?style=flat&logo=python&logoColor=white)](https://www.python.org)
[![License: AGPLv3](https://img.shields.io/badge/License-AGPL_v3-purple.svg)](https://www.gnu.org/licenses/agpl-3.0)
[![PyPI](https://img.shields.io/pypi/v/fastapi-420?color=3775A9&logo=pypi&logoColor=white)](https://pypi.org/project/fastapi-420/)
[![FastAPI](https://img.shields.io/badge/FastAPI-compatible-009688?style=flat&logo=fastapi)](https://fastapi.tiangolo.com)

> Production rate limiting for FastAPI using HTTP 420 "Enhance Your Calm".

*This is a quick overview — security theory, architecture, and full walkthroughs are in the [learn modules](#learn).*

## What It Does

- Three implementation methods: middleware (global), decorator (per route), dependency injection
- Sliding Window, Token Bucket, and Fixed Window rate limiting algorithms
- Redis support with automatic in-memory fallback when Redis is unavailable
- Scoped rate limiters for applying different limits to endpoint groups
- Fingerprint levels (RELAXED, NORMAL, STRICT) for client identification granularity
- Multiple stacking rules where the most restrictive limit applies

## Quick Start

```bash
uv add fastapi-420
```

```python
from fastapi import FastAPI
from fastapi_420 import RateLimiter, RateLimiterSettings

app = FastAPI()
limiter = RateLimiter(RateLimiterSettings(default_limit="100/minute"))
app.add_middleware(limiter.middleware)
```

For Redis support: `uv add fastapi-420[redis]`

> [!TIP]
> This project uses [`just`](https://github.com/casey/just) as a command runner. Type `just` to see all available commands.
>
> Install: `curl -sSf https://just.systems/install.sh | bash -s -- --to ~/.local/bin`

## Learn

This project includes step-by-step learning materials covering security theory, architecture, and implementation.

| Module | Topic |
|--------|-------|
| [00 - Overview](learn/00-OVERVIEW.md) | Prerequisites and quick start |
| [01 - Concepts](learn/01-CONCEPTS.md) | Security theory and real-world breaches |
| [02 - Architecture](learn/02-ARCHITECTURE.md) | System design and data flow |
| [03 - Implementation](learn/03-IMPLEMENTATION.md) | Code walkthrough |
| [04 - Challenges](learn/04-CHALLENGES.md) | Extension ideas and exercises |


## License

AGPL 3.0
