Django Smart Ratelimit Documentation

Core Documentation

• Installation: Setup and basic configuration
• Design Philosophy: Why we built this and how it compares
• Algorithms: Deep dive into Token Buckets and Windows
• Configuration: Backends, Circuit Breakers, and Settings
• Error Handling: Strategies for failure scenarios
• Deployment: Running in production
• Migration Guide: moving from django-ratelimit

API Reference

• Decorator: All arguments for @rate_limit
• Backends: Implementation details
• Utilities: Helper functions

Flagship Features

• Shadow Mode: Set shadow=True to evaluate and log rate-limit decisions (including OpenTelemetry events) without enforcing them. Use it to observe what would be blocked before turning on enforcement. See the Decorator API.
• Cost-Based (Weighted) Limiting: The cost argument charges expensive requests more of the budget. It accepts an int or a callable (request) -> int, so a single export endpoint can cost more than a cheap read. See the Decorator API.
• CIDR Allow/Deny Lists: The allow_list and deny_list arguments (and the IPList, FileBackedIPList, and URLBackedIPList helpers) match clients against IPv4/IPv6 CIDRs sourced from inline values, files, or URL feeds. See Configuration and Deployment.
• DRF Throttle Adapter: Drop-in BaseThrottle subclasses (UserRateLimitThrottle, AnonRateLimitThrottle, and the configurable SmartRateLimitThrottle) bridge Django REST Framework's throttling interface to this library. Install with pip install django-smart-ratelimit[drf]. See Installation.
• Observability: Built-in Prometheus /metrics, OpenTelemetry spans and metrics via instrument_rate_limit(), and structured JSON logging for ELK/Datadog/Splunk. Install the prometheus and opentelemetry extras as needed. See Installation.
• Type-Safe Enums: The optional Algorithm and RateLimitKey enums give you autocomplete and a typo-proof contract; they interoperate with plain strings everywhere. See the Decorator API.
• Configurable Proxy Trust (new in v3.1): RATELIMIT_TRUSTED_PROXIES and RATELIMIT_TRUST_FORWARDED_HEADERS make client IP extraction spoof-resistant behind load balancers and CDNs. See Configuration and Deployment.
• Database Backend: An optional Django ORM backend persists rate-limit state in your SQL database (PostgreSQL, MySQL, SQLite) without requiring Redis. See Backends.