django-smart-ratelimit 2.2.1

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)

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

from django_smart_ratelimit import RateLimitMixin

class LoginView(RateLimitMixin, View):
    ratelimit_key = 'ip'
    ratelimit_rate = '5/m'
    ratelimit_block = True

Configuration

Add to your Django settings:

RATELIMIT_DEFAULT_BACKEND = 'redis'
RATELIMIT_REDIS_URL = 'redis://localhost:6379/0'

# Optional: enable structured logging
RATELIMIT_LOGGING = {
    'ENABLED': True,
    'LEVEL': 'INFO',
    'FORMAT': 'json',
}

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

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.