The key=
argument to the decorator takes either a string or a callable.
The following string values for key=
provide shortcuts to commonly used ratelimit keys:
'ip'
- Use the request IP address (i.e.request.META['REMOTE_ADDR']
)Note
If you are using a reverse proxy, make sure this value is correct or use an appropriate
header:
value. See thesecurity <security-chapter>
notes.'get:X'
- Use the value ofrequest.GET.get('X', '')
.'post:X'
- Use the value ofrequest.POST.get('X', '')
.'header:x-x'
- Use the value ofrequest.META.get('HTTP_X_X', '')
.Note
The value right of the colon will be translated to all-caps and any dashes will be replaced with underscores, e.g.: x-client-ip => X_CLIENT_IP.
'user'
- Use an appropriate value fromrequest.user
. Do not use with unauthenticated users.'user_or_ip'
- Use an appropriate value fromrequest.user
if the user is authenticated, otherwise userequest.META['REMOTE_ADDR']
(see the note above about reverse proxies).
Note
Missing headers, GET, and POST values will all be treated as empty strings, and ratelimited in the same bucket.
Warning
Using user-supplied data, like data from GET and POST or headers directly from the User-Agent can allow users to trivially opt out of ratelimiting. See the note in the security chapter
<security-user-supplied>
.
Other string values not from the list above will be treated as the dotted Python path to a callable. See below <keys-callable>
for more on callables.
0.3
0.5 Added support for python path to callables.
0.6 Callable was mistakenly only passed the request
, now also gets group
as documented.
If the value of key=
is a callable, or the path to a callable, that callable will be called with two arguments, the group
<usage-chapter>
and the request
object. It should return a bytestring or unicode object, e.g.:
def my_key(group, request):
return request.META['REMOTE_ADDR'] + request.user.username