django-smart-ratelimit 3.0.0

A flexible and efficient rate limiting library for Django applications

Django Smart Ratelimit

A high-performance, stateless rate limiting library for Django. Protects your APIs from abuse with atomic Redis operations, multiple algorithms, circuit breaking, and full async support -- optimized for distributed systems.

Key Features

• Stateless and Modern -- Dual-mode support (sync and async) with no database dependencies
• Enterprise Reliability -- Built-in circuit breaker, automatic failover, and fail-open strategies
• Multiple Algorithms -- Token bucket, sliding window, fixed window, and leaky bucket
• Flexible Backends -- Redis (recommended), async Redis, in-memory, MongoDB, or custom backends
• Precise Control -- Rate limit by IP, user, header, or any custom callable
• Prometheus Metrics -- Built-in /metrics endpoint for monitoring
• Structured JSON Logging -- ELK/Datadog/Splunk-compatible structured log output
• Adaptive Rate Limiting -- Dynamic limits based on CPU, memory, latency, and custom load indicators

Quick Start

Installation

pip install django-smart-ratelimit[redis]

Basic Usage

from django_smart_ratelimit import ratelimit

@ratelimit(key='ip', rate='5/m', block=True)
def login_view(request):
    return authenticate(request)

Keys and algorithms accept plain strings, or the RateLimitKey and Algorithm enums if you prefer autocomplete and a typo-proof contract. The two are interchangeable:

from django_smart_ratelimit import ratelimit
from django_smart_ratelimit.enums import Algorithm, RateLimitKey

@ratelimit(key=RateLimitKey.USER_OR_IP, rate='5/m', algorithm=Algorithm.TOKEN_BUCKET)
def login_view(request):
    return authenticate(request)

Async Support

from django_smart_ratelimit import aratelimit

@aratelimit(key='user', rate='100/h', block=True)
async def api_view(request):
    return await process(request)

Class-Based Views

Apply the decorator to a method with Django's method_decorator:

from django.utils.decorators import method_decorator
from django.views import View

from django_smart_ratelimit import ratelimit


class LoginView(View):
    @method_decorator(ratelimit(key='ip', rate='5/m', block=True))
    def post(self, request):
        return authenticate(request)

Configuration

Add to your Django settings:

RATELIMIT_BACKEND = 'redis'
RATELIMIT_REDIS = {'host': 'localhost', 'port': 6379, 'db': 0}
# Or point at a Redis URL instead of host/port:
# RATELIMIT_REDIS = {'url': 'redis://localhost:6379/0'}

# Optional: enable structured logging
RATELIMIT_LOGGING = {
    'ENABLED': True,
    'FORMAT': 'json',  # "json" or "text"
}

# Optional: enable Prometheus metrics
RATELIMIT_PROMETHEUS = {
    'ENABLED': True,
}

If RATELIMIT_BACKEND is unset, the in-memory backend is used by default.

Documentation

Detailed documentation is available in the docs/ folder:

Topic	Description
Full Documentation	Start here for the complete guide
Migration Guide	Steps for upgrading from django-ratelimit
Algorithms	Deep dive into token bucket, sliding window, and more
Configuration	Advanced settings, backends, and circuit breakers
Design Philosophy	Architecture decisions and comparison with alternatives

Compatibility

	Supported Versions
Python	3.9, 3.10, 3.11, 3.12, 3.13
Django	3.2, 4.0, 4.1, 4.2, 5.0, 5.1

Contributing

Contributions are welcome. Please see CONTRIBUTING.md for details on how to submit pull requests, report issues, and set up your development environment.

Community and Support

• GitHub Discussions -- Ask questions and share ideas
• Issues -- Report bugs
• Changelog -- Release history

Sponsors

Support the ongoing development of Django Smart Ratelimit:

License

This project is licensed under the MIT License. See the LICENSE file for details.