# Django Smart Ratelimit
[](https://github.com/YasserShkeir/django-smart-ratelimit/actions)
[](https://pypi.org/project/django-smart-ratelimit/)
[](https://pypi.org/project/django-smart-ratelimit/)
[](https://pypi.org/project/django-smart-ratelimit/)
[](https://pypi.org/project/django-smart-ratelimit/)
[](https://pypi.org/project/django-smart-ratelimit/)
[](https://github.com/YasserShkeir/django-smart-ratelimit/blob/main/LICENSE)
[](https://github.com/YasserShkeir/django-smart-ratelimit/discussions)
A comprehensive rate limiting library for Django applications with multiple algorithms, backends, and flexible configuration options.
## Why Rate Limiting Matters
Rate limiting helps protect your Django applications from:
- **Resource exhaustion** from excessive requests
- **Brute force attacks** on authentication endpoints
- **API abuse** and scraping attempts
- **Unintentional traffic spikes** that can overwhelm your server
## Why Choose Django Smart Ratelimit?
### Comparison with Other Packages
| Feature | django-smart-ratelimit | django-ratelimit | Other Packages |
| ------------------------------ | --------------------------------------------- | ---------------------------------------------- | -------------------------- |
| **Maintenance Status** | ✅ Actively maintained | 🔄 Minimal maintenance (last release Jul 2023) | 🔄 Varies |
| **Multiple Algorithms** | ✅ Token bucket, sliding window, fixed window | ❌ Fixed window only | ❌ Usually basic |
| **Backend Flexibility** | ✅ Redis, Database, Memory, Multi-backend | ❌ Django cache framework only | ❌ Limited options |
| **Circuit Breaker Protection** | ✅ Automatic failure recovery | ❌ No | ❌ Rarely available |
| **Atomic Operations** | ✅ Redis Lua scripts prevent race conditions | ❌ Race condition prone | ❌ Usually not atomic |
| **Automatic Failover** | ✅ Graceful degradation between backends | ❌ No | ❌ Single point of failure |
| **Type Safety** | ✅ Full mypy compatibility | ❌ No type hints | ❌ Usually untyped |
| **Decorator Syntax** | ✅ `@rate_limit()` | ✅ `@ratelimit()` | 🔄 Varies |
| **Monitoring Tools** | ✅ Health checks, cleanup commands | ❌ No | ❌ Usually manual |
| **Standard Headers** | ✅ X-RateLimit-\* headers | ❌ No headers | ❌ Inconsistent |
| **Concurrency Safety** | ✅ Race condition free | ❌ Race conditions possible | ❌ Usually problematic |
### Key Advantages
**🚀 Modern Architecture**: Built from the ground up with modern Django best practices, type safety, and comprehensive testing.
**🔧 Enterprise-Ready**: Multiple algorithms and backends allow you to choose the right solution for your specific use case - from simple fixed windows to sophisticated token buckets with burst handling.
**🛡️ Reliability**: Circuit breaker protection and automatic failover ensure your rate limiting doesn't become a single point of failure.
**📊 Observability**: Built-in monitoring, health checks, and standard HTTP headers provide visibility into rate limiting behavior.
**🔄 Migration Path**: Easy migration from django-ratelimit with similar decorator syntax but enhanced functionality.
## Library Features
- **Multiple algorithms**: Token bucket, sliding window, and fixed window
- **Backend flexibility**: Redis, Database, Memory, and Multi-Backend support
- **Circuit breaker protection**: Automatic failure detection and recovery for backends
- **Atomic operations**: Redis Lua scripts prevent race conditions
- **Automatic failover**: Graceful degradation between backends
- **Type safety**: Full mypy compatibility with strict type checking
- **Framework integration**: Native Django and Django REST Framework support
- **Monitoring tools**: Health checks and cleanup management commands
- **Standard headers**: X-RateLimit-\* headers for client information
## Quick Start
### Installation
```bash
pip install django-smart-ratelimit[redis]
```
### Basic Usage
```python
from django_smart_ratelimit import rate_limit
# IP-based rate limiting
@rate_limit(key='ip', rate='100/h')
def api_endpoint(request):
return JsonResponse({'data': 'protected'})
# User-based rate limiting
@rate_limit(key='user', rate='50/h')
def user_dashboard(request):
return JsonResponse({'user_data': '...'})
```
### Authentication Protection
```python
@rate_limit(key='ip', rate='5/m', block=True)
def login_view(request):
return authenticate_user(request)
```
### Django REST Framework
```python
from rest_framework import viewsets
from django_smart_ratelimit import rate_limit
class APIViewSet(viewsets.ViewSet):
@rate_limit(key='ip', rate='100/h')
def list(self, request):
return Response({'data': 'list'})
```
### Middleware Configuration
```python
# settings.py
MIDDLEWARE = ['django_smart_ratelimit.middleware.RateLimitMiddleware']
RATELIMIT_MIDDLEWARE = {
'DEFAULT_RATE': '1000/h',
'RATE_LIMITS': {
'/api/auth/': '10/m',
'/api/': '500/h',
}
}
```
## Migration from django-ratelimit
Migrating from `django-ratelimit` is straightforward with minimal code changes:
### Basic Decorator Migration
```python
# OLD: django-ratelimit
from django_ratelimit.decorators import ratelimit
@ratelimit(key='ip', rate='10/m', block=True)
def my_view(request):
return HttpResponse('Hello')
# NEW: django-smart-ratelimit
from django_smart_ratelimit import rate_limit
@rate_limit(key='ip', rate='10/m', block=True)
def my_view(request):
return HttpResponse('Hello')
```
### Enhanced Features Available
```python
# NEW: Add algorithm choice
@rate_limit(key='ip', rate='10/m', algorithm='token_bucket')
# NEW: Add backend failover
@rate_limit(key='ip', rate='10/m', backend='redis')
# NEW: Add skip conditions
@rate_limit(key='ip', rate='10/m', skip_if=lambda req: req.user.is_staff)
```
### Key Migration Benefits
- **Drop-in replacement**: Same decorator syntax (ratelimit vs. rate_limit)
- **Enhanced reliability**: Circuit breaker protection
- **Better performance**: Atomic Redis operations
- **More flexibility**: Multiple algorithms and backends
- **Active maintenance**: Regular updates and bug fixes
## Algorithm Comparison
| Algorithm | Characteristics | Best For |
| ------------------ | ---------------------------- | -------------------------- |
| **token_bucket** | Allows traffic bursts | APIs with variable load |
| **sliding_window** | Smooth request distribution | Consistent traffic control |
| **fixed_window** | Simple, predictable behavior | Basic rate limiting needs |
### Token Bucket Algorithm
The token bucket algorithm allows for burst traffic handling:
```python
@rate_limit(
key='user',
rate='100/h', # Base rate
algorithm='token_bucket',
algorithm_config={
'bucket_size': 200, # Allow bursts up to 200 requests
'refill_rate': 2.0, # Refill tokens at 2 per second
}
)
def api_with_bursts(request):
return JsonResponse({'data': 'handled'})
```
**Common use cases:**
- Mobile app synchronization after offline periods
- Batch file processing
- API retry mechanisms
## Backend Configuration
### Redis (Recommended)
```python
RATELIMIT_BACKEND = 'redis'
RATELIMIT_REDIS = {
'host': 'localhost',
'port': 6379,
'db': 0,
}
```
### Database
```python
RATELIMIT_BACKEND = 'database'
# Uses your default Django database
```
> **Upgrade note:** Run `python manage.py migrate` after upgrading to ensure the new `RateLimitCounter.data` column exists. The database backend now stores serialized token-bucket state in this field so token counts persist across requests.
### Multi-Backend with Failover
```python
RATELIMIT_BACKENDS = [
{
'name': 'primary_redis',
'backend': 'redis',
'config': {'host': 'redis-primary.example.com'}
},
{
'name': 'fallback_db',
'backend': 'database',
'config': {}
}
]
```
## Response Headers
The library adds standard rate limit headers to responses:
```http
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1642678800
Retry-After: 200
```
## Monitoring and Management
### Health Checks
```bash
# Check backend health
python manage.py ratelimit_health
# Detailed status
python manage.py ratelimit_health --verbose
```
### Cleanup (Database Backend)
```bash
# Clean expired entries
python manage.py cleanup_ratelimit
# Preview cleanup
python manage.py cleanup_ratelimit --dry-run
```
## Library Features
- **Multiple algorithms**: Token bucket, sliding window, and fixed window
- **Backend flexibility**: Redis, Database, Memory, and Multi-Backend support
- **Atomic operations**: Redis Lua scripts prevent race conditions
- **Automatic failover**: Graceful degradation between backends
- **Type safety**: Full mypy compatibility with strict type checking
- **Framework integration**: Native Django and Django REST Framework support
## Examples
The library includes comprehensive examples for various use cases:
- **[Basic Rate Limiting](https://github.com/YasserShkeir/django-smart-ratelimit/blob/main/examples/basic_rate_limiting.py)** - IP and user-based limiting
- **[Custom Key Functions](https://github.com/YasserShkeir/django-smart-ratelimit/blob/main/examples/custom_key_functions.py)** - Geographic and device-based keys
- **[JWT Rate Limiting](https://github.com/YasserShkeir/django-smart-ratelimit/blob/main/examples/jwt_rate_limiting.py)** - Token-based limiting
- **[DRF Integration](https://github.com/YasserShkeir/django-smart-ratelimit/blob/main/examples/drf_integration/)** - Django REST Framework examples
- **[Multi-tenant Applications](https://github.com/YasserShkeir/django-smart-ratelimit/blob/main/examples/tenant_rate_limiting.py)** - Tenant-aware rate limiting
## Configuration Options
### Decorator Parameters
```python
@rate_limit(
key='user', # Key function or string
rate='100/h', # Rate limit (requests/period)
algorithm='token_bucket', # Algorithm choice
algorithm_config={}, # Algorithm-specific config
backend='redis', # Backend override
block=True, # Block vs. continue on limit
skip_if=lambda req: req.user.is_staff, # Skip condition
)
```
## Testing
```bash
# Run tests
python -m pytest
# Run with coverage
python -m pytest --cov=django_smart_ratelimit
```
### Decorator Examples
```python
from django_smart_ratelimit import rate_limit
# Basic IP-based limiting
@rate_limit(key='ip', rate='10/m')
def public_api(request):
return JsonResponse({'message': 'Hello World'})
# User-based limiting (automatically falls back to IP for anonymous users)
@rate_limit(key='user', rate='100/h')
def user_dashboard(request):
return JsonResponse({'user_data': '...'})
# Custom key function for more control
@rate_limit(key=lambda req: f"user:{req.user.id}" if req.user.is_authenticated else f"ip:{req.META.get('REMOTE_ADDR')}", rate='50/h')
def flexible_api(request):
return JsonResponse({'data': '...'})
# Block when limit exceeded (default is to continue)
@rate_limit(key='ip', rate='5/m', block=True)
def strict_api(request):
return JsonResponse({'sensitive': 'data'})
# Skip rate limiting for staff users
@rate_limit(key='ip', rate='10/m', skip_if=lambda req: req.user.is_staff)
def staff_friendly_api(request):
return JsonResponse({'data': 'staff can access unlimited'})
# Use sliding window algorithm
@rate_limit(key='user', rate='100/h', algorithm='sliding_window')
def smooth_api(request):
return JsonResponse({'algorithm': 'sliding_window'})
# Use fixed window algorithm
@rate_limit(key='ip', rate='20/m', algorithm='fixed_window')
def burst_api(request):
return JsonResponse({'algorithm': 'fixed_window'})
# Use token bucket algorithm (NEW!)
@rate_limit(
key='api_key',
rate='100/m', # Base rate: 100 requests per minute
algorithm='token_bucket',
algorithm_config={
'bucket_size': 200, # Allow bursts up to 200 requests
'refill_rate': 2.0, # Refill at 2 tokens per second
}
)
def api_with_bursts(request):
return JsonResponse({'algorithm': 'token_bucket', 'burst_allowed': True})
```
## Circuit Breaker Protection
Automatic failure detection and recovery for backend operations to ensure system reliability:
### Configuration
```python
# settings.py
RATELIMIT_CIRCUIT_BREAKER = {
'failure_threshold': 5, # Open circuit after 5 failures
'recovery_timeout': 60, # Wait 60 seconds before testing recovery
'reset_timeout': 300, # Reset after 5 minutes of success
'half_open_max_calls': 1, # Test with 1 call in half-open state
}
```
### Backend-Specific Circuit Breakers
```python
from django_smart_ratelimit.backends import MemoryBackend
# Enable circuit breaker (default: enabled)
backend = MemoryBackend(enable_circuit_breaker=True)
# Custom configuration
custom_config = {'failure_threshold': 3, 'recovery_timeout': 30}
backend = MemoryBackend(
enable_circuit_breaker=True,
circuit_breaker_config=custom_config
)
# Check circuit breaker status
status = backend.get_backend_health_status()
print(f"Circuit breaker enabled: {status['circuit_breaker_enabled']}")
print(f"Current state: {status['circuit_breaker']['state']}")
```
### Circuit Breaker States
- **🟢 CLOSED**: Normal operation, requests pass through
- **🔴 OPEN**: Too many failures, requests fail fast (no backend calls)
- **🟡 HALF_OPEN**: Testing recovery with limited requests
## Community & Support
- **[GitHub Discussions](https://github.com/YasserShkeir/django-smart-ratelimit/discussions)** - Community support and questions
- **[Issues](https://github.com/YasserShkeir/django-smart-ratelimit/issues)** - Bug reports and feature requests
- **[Contributing](https://github.com/YasserShkeir/django-smart-ratelimit/blob/main/CONTRIBUTING.md)** - Contributing guidelines
- **[AI Usage Policy](https://github.com/YasserShkeir/django-smart-ratelimit/blob/main/AI_USAGE.md)** - Transparency about AI assistance in development
## 💖 Support the Project
If you find this project helpful and want to support its development, you can make a donation to help maintain and improve this open-source library:
### Cryptocurrency Donations
- **USDT (Ethereum Network)**: `0xBD90e5df7389295AE6fbaB5FEf6817f22A8123eF`
- **Solana (SOL)**: `WzQHS7hzBcznkYoR7TkMH1DRo3WLYQdWCNBuy6ZfY3h`
- **Ripple (XRP)**: `rE8CM2sv4gBEDhek2Ajm2vMmqMXdPV34jC`
Your support helps maintain and improve this project for the Django community! 🙏
## License
This project is licensed under the MIT License - see the [LICENSE](https://github.com/YasserShkeir/django-smart-ratelimit/blob/main/LICENSE) file for details.
---
**[📚 Documentation](https://github.com/YasserShkeir/django-smart-ratelimit/blob/main/docs/)** • **[💡 Examples](https://github.com/YasserShkeir/django-smart-ratelimit/blob/main/examples/)** • **[🤝 Contributing](https://github.com/YasserShkeir/django-smart-ratelimit/blob/main/CONTRIBUTING.md)** • **[💬 Discussions](https://github.com/YasserShkeir/django-smart-ratelimit/discussions)** • **[🤖 AI Usage](https://github.com/YasserShkeir/django-smart-ratelimit/blob/main/AI_USAGE.md)**
Raw data
{
"_id": null,
"home_page": null,
"name": "django-smart-ratelimit",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "decorator, django, middleware, rate-limiting, redis",
"author": null,
"author_email": "Yasser Shkeir <shkeiryasser@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/03/f9/10b260ba3a02508eb47787e8413cf38d0e0b0b211c8a47bfd6a8be871502/django_smart_ratelimit-0.8.11.tar.gz",
"platform": null,
"description": "# Django Smart Ratelimit\n\n[](https://github.com/YasserShkeir/django-smart-ratelimit/actions)\n[](https://pypi.org/project/django-smart-ratelimit/)\n[](https://pypi.org/project/django-smart-ratelimit/)\n[](https://pypi.org/project/django-smart-ratelimit/)\n[](https://pypi.org/project/django-smart-ratelimit/)\n[](https://pypi.org/project/django-smart-ratelimit/)\n[](https://github.com/YasserShkeir/django-smart-ratelimit/blob/main/LICENSE)\n[](https://github.com/YasserShkeir/django-smart-ratelimit/discussions)\n\nA comprehensive rate limiting library for Django applications with multiple algorithms, backends, and flexible configuration options.\n\n## Why Rate Limiting Matters\n\nRate limiting helps protect your Django applications from:\n\n- **Resource exhaustion** from excessive requests\n- **Brute force attacks** on authentication endpoints\n- **API abuse** and scraping attempts\n- **Unintentional traffic spikes** that can overwhelm your server\n\n## Why Choose Django Smart Ratelimit?\n\n### Comparison with Other Packages\n\n| Feature | django-smart-ratelimit | django-ratelimit | Other Packages |\n| ------------------------------ | --------------------------------------------- | ---------------------------------------------- | -------------------------- |\n| **Maintenance Status** | \u2705 Actively maintained | \ud83d\udd04 Minimal maintenance (last release Jul 2023) | \ud83d\udd04 Varies |\n| **Multiple Algorithms** | \u2705 Token bucket, sliding window, fixed window | \u274c Fixed window only | \u274c Usually basic |\n| **Backend Flexibility** | \u2705 Redis, Database, Memory, Multi-backend | \u274c Django cache framework only | \u274c Limited options |\n| **Circuit Breaker Protection** | \u2705 Automatic failure recovery | \u274c No | \u274c Rarely available |\n| **Atomic Operations** | \u2705 Redis Lua scripts prevent race conditions | \u274c Race condition prone | \u274c Usually not atomic |\n| **Automatic Failover** | \u2705 Graceful degradation between backends | \u274c No | \u274c Single point of failure |\n| **Type Safety** | \u2705 Full mypy compatibility | \u274c No type hints | \u274c Usually untyped |\n| **Decorator Syntax** | \u2705 `@rate_limit()` | \u2705 `@ratelimit()` | \ud83d\udd04 Varies |\n| **Monitoring Tools** | \u2705 Health checks, cleanup commands | \u274c No | \u274c Usually manual |\n| **Standard Headers** | \u2705 X-RateLimit-\\* headers | \u274c No headers | \u274c Inconsistent |\n| **Concurrency Safety** | \u2705 Race condition free | \u274c Race conditions possible | \u274c Usually problematic |\n\n### Key Advantages\n\n**\ud83d\ude80 Modern Architecture**: Built from the ground up with modern Django best practices, type safety, and comprehensive testing.\n\n**\ud83d\udd27 Enterprise-Ready**: Multiple algorithms and backends allow you to choose the right solution for your specific use case - from simple fixed windows to sophisticated token buckets with burst handling.\n\n**\ud83d\udee1\ufe0f Reliability**: Circuit breaker protection and automatic failover ensure your rate limiting doesn't become a single point of failure.\n\n**\ud83d\udcca Observability**: Built-in monitoring, health checks, and standard HTTP headers provide visibility into rate limiting behavior.\n\n**\ud83d\udd04 Migration Path**: Easy migration from django-ratelimit with similar decorator syntax but enhanced functionality.\n\n## Library Features\n\n- **Multiple algorithms**: Token bucket, sliding window, and fixed window\n- **Backend flexibility**: Redis, Database, Memory, and Multi-Backend support\n- **Circuit breaker protection**: Automatic failure detection and recovery for backends\n- **Atomic operations**: Redis Lua scripts prevent race conditions\n- **Automatic failover**: Graceful degradation between backends\n- **Type safety**: Full mypy compatibility with strict type checking\n- **Framework integration**: Native Django and Django REST Framework support\n- **Monitoring tools**: Health checks and cleanup management commands\n- **Standard headers**: X-RateLimit-\\* headers for client information\n\n## Quick Start\n\n### Installation\n\n```bash\npip install django-smart-ratelimit[redis]\n```\n\n### Basic Usage\n\n```python\nfrom django_smart_ratelimit import rate_limit\n\n# IP-based rate limiting\n@rate_limit(key='ip', rate='100/h')\ndef api_endpoint(request):\n return JsonResponse({'data': 'protected'})\n\n# User-based rate limiting\n@rate_limit(key='user', rate='50/h')\ndef user_dashboard(request):\n return JsonResponse({'user_data': '...'})\n```\n\n### Authentication Protection\n\n```python\n@rate_limit(key='ip', rate='5/m', block=True)\ndef login_view(request):\n return authenticate_user(request)\n```\n\n### Django REST Framework\n\n```python\nfrom rest_framework import viewsets\nfrom django_smart_ratelimit import rate_limit\n\nclass APIViewSet(viewsets.ViewSet):\n @rate_limit(key='ip', rate='100/h')\n def list(self, request):\n return Response({'data': 'list'})\n```\n\n### Middleware Configuration\n\n```python\n# settings.py\nMIDDLEWARE = ['django_smart_ratelimit.middleware.RateLimitMiddleware']\nRATELIMIT_MIDDLEWARE = {\n 'DEFAULT_RATE': '1000/h',\n 'RATE_LIMITS': {\n '/api/auth/': '10/m',\n '/api/': '500/h',\n }\n}\n```\n\n## Migration from django-ratelimit\n\nMigrating from `django-ratelimit` is straightforward with minimal code changes:\n\n### Basic Decorator Migration\n\n```python\n# OLD: django-ratelimit\nfrom django_ratelimit.decorators import ratelimit\n\n@ratelimit(key='ip', rate='10/m', block=True)\ndef my_view(request):\n return HttpResponse('Hello')\n\n# NEW: django-smart-ratelimit\nfrom django_smart_ratelimit import rate_limit\n\n@rate_limit(key='ip', rate='10/m', block=True)\ndef my_view(request):\n return HttpResponse('Hello')\n```\n\n### Enhanced Features Available\n\n```python\n# NEW: Add algorithm choice\n@rate_limit(key='ip', rate='10/m', algorithm='token_bucket')\n\n# NEW: Add backend failover\n@rate_limit(key='ip', rate='10/m', backend='redis')\n\n# NEW: Add skip conditions\n@rate_limit(key='ip', rate='10/m', skip_if=lambda req: req.user.is_staff)\n```\n\n### Key Migration Benefits\n\n- **Drop-in replacement**: Same decorator syntax (ratelimit vs. rate_limit)\n- **Enhanced reliability**: Circuit breaker protection\n- **Better performance**: Atomic Redis operations\n- **More flexibility**: Multiple algorithms and backends\n- **Active maintenance**: Regular updates and bug fixes\n\n## Algorithm Comparison\n\n| Algorithm | Characteristics | Best For |\n| ------------------ | ---------------------------- | -------------------------- |\n| **token_bucket** | Allows traffic bursts | APIs with variable load |\n| **sliding_window** | Smooth request distribution | Consistent traffic control |\n| **fixed_window** | Simple, predictable behavior | Basic rate limiting needs |\n\n### Token Bucket Algorithm\n\nThe token bucket algorithm allows for burst traffic handling:\n\n```python\n@rate_limit(\n key='user',\n rate='100/h', # Base rate\n algorithm='token_bucket',\n algorithm_config={\n 'bucket_size': 200, # Allow bursts up to 200 requests\n 'refill_rate': 2.0, # Refill tokens at 2 per second\n }\n)\ndef api_with_bursts(request):\n return JsonResponse({'data': 'handled'})\n```\n\n**Common use cases:**\n\n- Mobile app synchronization after offline periods\n- Batch file processing\n- API retry mechanisms\n\n## Backend Configuration\n\n### Redis (Recommended)\n\n```python\nRATELIMIT_BACKEND = 'redis'\nRATELIMIT_REDIS = {\n 'host': 'localhost',\n 'port': 6379,\n 'db': 0,\n}\n```\n\n### Database\n\n```python\nRATELIMIT_BACKEND = 'database'\n# Uses your default Django database\n```\n\n> **Upgrade note:** Run `python manage.py migrate` after upgrading to ensure the new `RateLimitCounter.data` column exists. The database backend now stores serialized token-bucket state in this field so token counts persist across requests.\n\n### Multi-Backend with Failover\n\n```python\nRATELIMIT_BACKENDS = [\n {\n 'name': 'primary_redis',\n 'backend': 'redis',\n 'config': {'host': 'redis-primary.example.com'}\n },\n {\n 'name': 'fallback_db',\n 'backend': 'database',\n 'config': {}\n }\n]\n```\n\n## Response Headers\n\nThe library adds standard rate limit headers to responses:\n\n```http\nX-RateLimit-Limit: 100\nX-RateLimit-Remaining: 99\nX-RateLimit-Reset: 1642678800\nRetry-After: 200\n```\n\n## Monitoring and Management\n\n### Health Checks\n\n```bash\n# Check backend health\npython manage.py ratelimit_health\n\n# Detailed status\npython manage.py ratelimit_health --verbose\n```\n\n### Cleanup (Database Backend)\n\n```bash\n# Clean expired entries\npython manage.py cleanup_ratelimit\n\n# Preview cleanup\npython manage.py cleanup_ratelimit --dry-run\n```\n\n## Library Features\n\n- **Multiple algorithms**: Token bucket, sliding window, and fixed window\n- **Backend flexibility**: Redis, Database, Memory, and Multi-Backend support\n- **Atomic operations**: Redis Lua scripts prevent race conditions\n- **Automatic failover**: Graceful degradation between backends\n- **Type safety**: Full mypy compatibility with strict type checking\n- **Framework integration**: Native Django and Django REST Framework support\n\n## Examples\n\nThe library includes comprehensive examples for various use cases:\n\n- **[Basic Rate Limiting](https://github.com/YasserShkeir/django-smart-ratelimit/blob/main/examples/basic_rate_limiting.py)** - IP and user-based limiting\n- **[Custom Key Functions](https://github.com/YasserShkeir/django-smart-ratelimit/blob/main/examples/custom_key_functions.py)** - Geographic and device-based keys\n- **[JWT Rate Limiting](https://github.com/YasserShkeir/django-smart-ratelimit/blob/main/examples/jwt_rate_limiting.py)** - Token-based limiting\n- **[DRF Integration](https://github.com/YasserShkeir/django-smart-ratelimit/blob/main/examples/drf_integration/)** - Django REST Framework examples\n- **[Multi-tenant Applications](https://github.com/YasserShkeir/django-smart-ratelimit/blob/main/examples/tenant_rate_limiting.py)** - Tenant-aware rate limiting\n\n## Configuration Options\n\n### Decorator Parameters\n\n```python\n@rate_limit(\n key='user', # Key function or string\n rate='100/h', # Rate limit (requests/period)\n algorithm='token_bucket', # Algorithm choice\n algorithm_config={}, # Algorithm-specific config\n backend='redis', # Backend override\n block=True, # Block vs. continue on limit\n skip_if=lambda req: req.user.is_staff, # Skip condition\n)\n```\n\n## Testing\n\n```bash\n# Run tests\npython -m pytest\n\n# Run with coverage\npython -m pytest --cov=django_smart_ratelimit\n```\n\n### Decorator Examples\n\n```python\nfrom django_smart_ratelimit import rate_limit\n\n# Basic IP-based limiting\n@rate_limit(key='ip', rate='10/m')\ndef public_api(request):\n return JsonResponse({'message': 'Hello World'})\n\n# User-based limiting (automatically falls back to IP for anonymous users)\n@rate_limit(key='user', rate='100/h')\ndef user_dashboard(request):\n return JsonResponse({'user_data': '...'})\n\n# Custom key function for more control\n@rate_limit(key=lambda req: f\"user:{req.user.id}\" if req.user.is_authenticated else f\"ip:{req.META.get('REMOTE_ADDR')}\", rate='50/h')\ndef flexible_api(request):\n return JsonResponse({'data': '...'})\n\n# Block when limit exceeded (default is to continue)\n@rate_limit(key='ip', rate='5/m', block=True)\ndef strict_api(request):\n return JsonResponse({'sensitive': 'data'})\n\n# Skip rate limiting for staff users\n@rate_limit(key='ip', rate='10/m', skip_if=lambda req: req.user.is_staff)\ndef staff_friendly_api(request):\n return JsonResponse({'data': 'staff can access unlimited'})\n\n# Use sliding window algorithm\n@rate_limit(key='user', rate='100/h', algorithm='sliding_window')\ndef smooth_api(request):\n return JsonResponse({'algorithm': 'sliding_window'})\n\n# Use fixed window algorithm\n@rate_limit(key='ip', rate='20/m', algorithm='fixed_window')\ndef burst_api(request):\n return JsonResponse({'algorithm': 'fixed_window'})\n\n# Use token bucket algorithm (NEW!)\n@rate_limit(\n key='api_key',\n rate='100/m', # Base rate: 100 requests per minute\n algorithm='token_bucket',\n algorithm_config={\n 'bucket_size': 200, # Allow bursts up to 200 requests\n 'refill_rate': 2.0, # Refill at 2 tokens per second\n }\n)\ndef api_with_bursts(request):\n return JsonResponse({'algorithm': 'token_bucket', 'burst_allowed': True})\n```\n\n## Circuit Breaker Protection\n\nAutomatic failure detection and recovery for backend operations to ensure system reliability:\n\n### Configuration\n\n```python\n# settings.py\nRATELIMIT_CIRCUIT_BREAKER = {\n 'failure_threshold': 5, # Open circuit after 5 failures\n 'recovery_timeout': 60, # Wait 60 seconds before testing recovery\n 'reset_timeout': 300, # Reset after 5 minutes of success\n 'half_open_max_calls': 1, # Test with 1 call in half-open state\n}\n```\n\n### Backend-Specific Circuit Breakers\n\n```python\nfrom django_smart_ratelimit.backends import MemoryBackend\n\n# Enable circuit breaker (default: enabled)\nbackend = MemoryBackend(enable_circuit_breaker=True)\n\n# Custom configuration\ncustom_config = {'failure_threshold': 3, 'recovery_timeout': 30}\nbackend = MemoryBackend(\n enable_circuit_breaker=True,\n circuit_breaker_config=custom_config\n)\n\n# Check circuit breaker status\nstatus = backend.get_backend_health_status()\nprint(f\"Circuit breaker enabled: {status['circuit_breaker_enabled']}\")\nprint(f\"Current state: {status['circuit_breaker']['state']}\")\n```\n\n### Circuit Breaker States\n\n- **\ud83d\udfe2 CLOSED**: Normal operation, requests pass through\n- **\ud83d\udd34 OPEN**: Too many failures, requests fail fast (no backend calls)\n- **\ud83d\udfe1 HALF_OPEN**: Testing recovery with limited requests\n\n## Community & Support\n\n- **[GitHub Discussions](https://github.com/YasserShkeir/django-smart-ratelimit/discussions)** - Community support and questions\n- **[Issues](https://github.com/YasserShkeir/django-smart-ratelimit/issues)** - Bug reports and feature requests\n- **[Contributing](https://github.com/YasserShkeir/django-smart-ratelimit/blob/main/CONTRIBUTING.md)** - Contributing guidelines\n- **[AI Usage Policy](https://github.com/YasserShkeir/django-smart-ratelimit/blob/main/AI_USAGE.md)** - Transparency about AI assistance in development\n\n## \ud83d\udc96 Support the Project\n\nIf you find this project helpful and want to support its development, you can make a donation to help maintain and improve this open-source library:\n\n### Cryptocurrency Donations\n\n- **USDT (Ethereum Network)**: `0xBD90e5df7389295AE6fbaB5FEf6817f22A8123eF`\n- **Solana (SOL)**: `WzQHS7hzBcznkYoR7TkMH1DRo3WLYQdWCNBuy6ZfY3h`\n- **Ripple (XRP)**: `rE8CM2sv4gBEDhek2Ajm2vMmqMXdPV34jC`\n\nYour support helps maintain and improve this project for the Django community! \ud83d\ude4f\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](https://github.com/YasserShkeir/django-smart-ratelimit/blob/main/LICENSE) file for details.\n\n---\n\n**[\ud83d\udcda Documentation](https://github.com/YasserShkeir/django-smart-ratelimit/blob/main/docs/)** \u2022 **[\ud83d\udca1 Examples](https://github.com/YasserShkeir/django-smart-ratelimit/blob/main/examples/)** \u2022 **[\ud83e\udd1d Contributing](https://github.com/YasserShkeir/django-smart-ratelimit/blob/main/CONTRIBUTING.md)** \u2022 **[\ud83d\udcac Discussions](https://github.com/YasserShkeir/django-smart-ratelimit/discussions)** \u2022 **[\ud83e\udd16 AI Usage](https://github.com/YasserShkeir/django-smart-ratelimit/blob/main/AI_USAGE.md)**\n",
"bugtrack_url": null,
"license": null,
"summary": "A flexible and efficient rate limiting library for Django applications",
"version": "0.8.11",
"project_urls": {
"Changelog": "https://github.com/YasserShkeir/django-smart-ratelimit/blob/main/CHANGELOG.md",
"Discussions": "https://github.com/YasserShkeir/django-smart-ratelimit/discussions",
"Documentation": "https://django-smart-ratelimit.readthedocs.io",
"Homepage": "https://github.com/YasserShkeir/django-smart-ratelimit",
"Issues": "https://github.com/YasserShkeir/django-smart-ratelimit/issues",
"Repository": "https://github.com/YasserShkeir/django-smart-ratelimit"
},
"split_keywords": [
"decorator",
" django",
" middleware",
" rate-limiting",
" redis"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "26560f5024cf3dad1bd631ccfcdb47b95302ba3931ee866366252974d19b0afc",
"md5": "3f7058d601c439b8e4cf9657769b6347",
"sha256": "5be0de0dc7b68e2e7883ac39d0005b9de97f33eed8fd6016b95a19974f57fe13"
},
"downloads": -1,
"filename": "django_smart_ratelimit-0.8.11-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3f7058d601c439b8e4cf9657769b6347",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 89214,
"upload_time": "2025-10-19T11:04:06",
"upload_time_iso_8601": "2025-10-19T11:04:06.325945Z",
"url": "https://files.pythonhosted.org/packages/26/56/0f5024cf3dad1bd631ccfcdb47b95302ba3931ee866366252974d19b0afc/django_smart_ratelimit-0.8.11-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "03f910b260ba3a02508eb47787e8413cf38d0e0b0b211c8a47bfd6a8be871502",
"md5": "72c7eccfe62b48ecf1f358403c16e4d6",
"sha256": "439d97df959b6e9cc2afbc983ddbe5f8e6b24707298dc66f6bf93dc9c5f93fa2"
},
"downloads": -1,
"filename": "django_smart_ratelimit-0.8.11.tar.gz",
"has_sig": false,
"md5_digest": "72c7eccfe62b48ecf1f358403c16e4d6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 162979,
"upload_time": "2025-10-19T11:04:07",
"upload_time_iso_8601": "2025-10-19T11:04:07.647838Z",
"url": "https://files.pythonhosted.org/packages/03/f9/10b260ba3a02508eb47787e8413cf38d0e0b0b211c8a47bfd6a8be871502/django_smart_ratelimit-0.8.11.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-19 11:04:07",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "YasserShkeir",
"github_project": "django-smart-ratelimit",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "Django",
"specs": [
[
">=",
"3.2"
]
]
},
{
"name": "redis",
"specs": [
[
">=",
"4.0"
]
]
},
{
"name": "pymongo",
"specs": [
[
">=",
"4.0"
]
]
}
],
"lcname": "django-smart-ratelimit"
}
JSON
