djblets.auth.ratelimit¶

Utilities for rate-limiting login attempts.

RATE_LIMIT_LOGIN = 0[source]¶

Available rate limit categories.

DEFAULT_LOGIN_LIMIT_RATE = '5/m'[source]¶

The default rate limit for logins.

DEFAULT_API_ANONYMOUS_LIMIT_RATE = '1000/h'[source]¶

The default rate limit for anonymous API requests.

DEFAULT_API_AUTHENTICATED_LIMIT_RATE = '10000/h'[source]¶

The default rate limit for authenticated API requests.

class UsageCount[source]¶

Bases: TypedDict

Rate limit status for a given user or IP address.

New in version 6.0.

count: int¶

The number of login attempts made.

limit: int¶

The number of attempts allowed.

time_left: int¶

The time left before rate limit is over.

__annotations__ = {'count': ForwardRef('int', module='djblets.auth.ratelimit'), 'limit': ForwardRef('int', module='djblets.auth.ratelimit'), 'time_left': ForwardRef('int', module='djblets.auth.ratelimit')}¶

__closed__ = False¶

__extra_items__ = None¶

__mutable_keys__ = frozenset({'count', 'limit', 'time_left'})¶

__optional_keys__ = frozenset({})¶

__orig_bases__ = (<function TypedDict>,)¶

__readonly_keys__ = frozenset({})¶

__required_keys__ = frozenset({'count', 'limit', 'time_left'})¶

__total__ = True¶

get_user_id_or_ip(request: HttpRequest) → str[source]¶

Return the user’s ID or IP address from the given HTTP request.

Parameters:

request (django.http.HttpRequest) – The HTTP request from the client.

Returns:

If the user is authenticated, the user ID will be returned. Otherwise, the IP address of the client is returned instead.

Return type:

str

is_ratelimited(request: HttpRequest, increment: bool = False, limit_type: int = 0) → bool[source]¶

Check whether the user or IP address has exceeded the rate limit.

The parameters are used to create a new key or fetch an existing key to save or update to the cache and to determine the amount of time period left.

Parameters:

• request (django.http.HttpRequest) – The HTTP request from the client.

• increment (bool, optional) – Whether the number of login attempts should be incremented.

• limit_type (int, optional) – The type of rate limit to check.

Returns:

Whether the current user has exceeded the rate limit of login attempts.

Return type:

bool

get_usage_count(request: HttpRequest, increment: bool = False, limit_type: int = 0) → Optional[UsageCount][source]¶

Return rate limit status for a given user or IP address.

This method performs validation checks on the input parameters and creates the cache key to keep track of the number of login attempts made by the user. It saves the new cache key and initial number of attempts or updates the existing cache key and number of attempts before returning the count, limit, and time_left.

Parameters:

• request (django.http.HttpRequest) – The HTTP request from the client.

• increment (bool, optional) – Whether the number of login attempts should be incremented.

• limit_type (int, optional) – The type of rate limit to check.

Returns:

The rate limit status.

Return type:

UsageCount

Raises:

django.core.exceptions.ImproperlyConfigured – The LOGIN_LIMIT_RATE setting could not be parsed.

class Rate(count: int, seconds: int)[source]¶

Bases: object

A rate representing login attempt frequency.

The main functionality of this class is found in the parse() function. This class converts a rate into a Rate object, which contains the number of login attempts allowed within a time period based on a given rate string.

PERIODS = {'d': 86400, 'h': 3600, 'm': 60, 's': 1}[source]¶

RATE_RE = re.compile('(\\d+)/(\\d*)([smhd])?')[source]¶

Regular expression that interprets the rate string.

classmethod parse(rate_str: str) → Self[source]¶

Return a Rate parsed from the given rate string.

Converts the given rate string into a Rate object, which contains the number of login attempts allowed (count) and the time period allotted for these attempts (seconds).

Parameters:

rate_str (str) – The number of attempts allowed within a period of time (can be seconds, minutes, hours, or days).

Returns:

A Rate object that returns the number of login attempts allowed (count), and the total time period for these attempts (seconds).

Return type:

Rate

Raises:

ValueError – The value could not be parsed.

__init__(count: int, seconds: int) → None[source]¶

Initialize attributes for the Rate object.

This initializes the number of failed login attempts allowed, and the time period for the login attempts in seconds based on the data returned from the parse() function.

Parameters:

• count (int) – The number of failed login attempts allowed.

• seconds (int) – The time period for the login attempts in seconds.

count: int¶

The number of failed login attempts allowed.

__annotations__ = {'count': 'int', 'seconds': 'int'}¶

__hash__ = None¶

seconds: int¶

The time period for the login attempts in seconds.

__eq__(other: Any) → bool[source]¶

Return whether the two Rate instances are equal.

Returns:

Return true if the count and seconds match.

Return type:

bool