See also the CHANGELOG <../CHANGELOG>.
From 2.0 to 3.0¶
- Ratelimit now supports Django >=1.11 and Python >=3.4.
@ratelimitno longer works directly on class methods, add
RatelimitMixinis gone, migrate to
@ratelimit decorator on class methods¶
In 3.0, the decorator has been simplified and must now be used with
@method_decorator utility. Migrating should be
from django.views.generic import View from ratelimit.decorators import ratelimit class MyView(View): @ratelimit(key='ip', rate='1/m', method='GET') def get(self, request): pass
from django.utils.decorators import method_decorator from django.views.generic import View from ratelimit.decorators import ratelimit class MyView(View): @method_decorator(ratelimit(key='ip', rate='1/m', method='GET')) def get(self, request): pass
RatelimitMixin is a vestige of an older version of Ratelimit that
did not support multiple rates per method. As such, it is significantly
less powerful than the current
@ratelimit decorator. To migrate to
the decorator, use the
@method_decorator from Django:
class MyView(RatelimitMixin, View): ratelimit_key = 'ip' ratelimit_rate = '10/m' ratelimit_method = 'GET' def get(self, request): pass
class MyView(View): @method_decorator(ratelimit(key='ip', rate='10/m', method='GET')) def get(self, request): pass
The major benefit is that it is now possible to apply multiple limits to the same method, as with :ref:`the decorator <usage-decorator>`_.
From <=0.4 to 0.5¶
- Rate limits are now counted against fixed, instead of sliding, windows.
- Rate limits are no longer shared between methods by default.
- A key must always be specified. If using without an explicit key, add
skip_ifto a callable
rate=<callable>method (see Rates.
RatelimitMixin(note the lowercase
Before 0.5, rates were counted against a sliding window, so if the
rate limit was
1/m, and three requests came in:
18.104.22.168 [09/Sep/2014:12:25:03] ... 22.214.171.124 [09/Sep/2014:12:25:53] ... <RATE LIMITED> 126.96.36.199 [09/Sep/2014:12:25:59] ... <RATE LIMITED>
Even though the third request came nearly two minutes after the first request, the second request moved the window. Good actors could easily get caught in this, even trying to implement reasonable back-offs.
Starting in 0.5, windows are fixed, and staggered throughout a given period based on the key value, so the third request, above would not be rate limited (it’s possible neither would the second one).
That means that given a rate of
X/u, you may see up to
2 * X
requests in a short period of time. Make sure to set
accordingly if this is an issue.
This change still limits bad actors while being far kinder to good actors.
To avoid a situation where all limits expire at the top of the hour, windows are automatically staggered throughout their period based on the key value. So if, for example, two IP addresses are hitting hourly limits, instead of both of those limits expiring at 06:00:00, one might expire at 06:13:41 (and subsequently at 07:13:41, etc) and the other might expire at 06:48:13 (and 07:48:13, etc).
Using multiple decorators¶
@ratelimit decorator used to be able to ratelimit against
multiple keys, e.g., before 0.5:
@ratelimit(ip=True, field='username', keys=mykeysfunc) def someview(request): # ...
To simplify both the internals and the question of what limits apply, each decorator now tracks exactly one rate, but decorators can be more reliably stacked (c.f. some examples in the section above).
The pre-0.5 example above would need to become four decorators:
@ratelimit(key='ip') @ratelimit(key='post:username') @ratelimit(key='get:username') @ratelimit(key=mykeysfunc) def someview(request): # ...
As documented above, however, this allows powerful new uses, like burst limits and distinct GET/POST limits.