djblets.protect.ratelimit¶

General support for rate limiting of operations.

This can be used to impose rate limits on operations or access to resources, locked down to a user, IP, or any other criteria.

class RateLimitUsage(count: int, limit: int | None = None, time_left_secs: int | None = None)[source]¶

Bases: object

Usage information for a rate limit key.

This information can be used to determine if a user has any activity remaining before hitting a rate limit, or if they’ve hit the limit.

New in version 6.0.

count: int¶

The number of attempts made against the rate limit key.

limit: int | None = None¶

The total number of attempts allowed.

time_left_secs: int | None = None¶

The time remaining in seconds before the rate limit resets.

property is_limited: bool[source]¶

Whether the usage has hit the rate limit.

Type:

bool

__annotations__ = {'count': 'int', 'limit': 'int | None', 'time_left_secs': 'int | None'}¶

__dataclass_fields__ = {'count': Field(name='count',type='int',default=<dataclasses._MISSING_TYPE object>,default_factory=<dataclasses._MISSING_TYPE object>,init=True,repr=True,hash=None,compare=True,metadata=mappingproxy({}),kw_only=False,_field_type=_FIELD), 'limit': Field(name='limit',type='int | None',default=None,default_factory=<dataclasses._MISSING_TYPE object>,init=True,repr=True,hash=None,compare=True,metadata=mappingproxy({}),kw_only=False,_field_type=_FIELD), 'time_left_secs': Field(name='time_left_secs',type='int | None',default=None,default_factory=<dataclasses._MISSING_TYPE object>,init=True,repr=True,hash=None,compare=True,metadata=mappingproxy({}),kw_only=False,_field_type=_FIELD)}¶

__dataclass_params__ = _DataclassParams(init=True,repr=True,eq=True,order=False,unsafe_hash=False,frozen=False)¶

__eq__(other)¶

Return self==value.

__hash__ = None¶

__init__(count: int, limit: int | None = None, time_left_secs: int | None = None) → None¶

__match_args__ = ('count', 'limit', 'time_left_secs')¶

__repr__()¶

Return repr(self).

class RateLimit(*, total_limit: int, period_secs: int)[source]¶

Bases: object

A rate limit applied to an operation or access.

This represents the data behind a parsed rate limit imposed on an operation or access to a resource.

New in version 6.0.

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

Dictionary contains keys that represent different time periods.

The time periods are represented in seconds for days, hours, minutes, and seconds.

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

Regular expression that interprets the rate string.

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

Return a RateLimit 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) – The number of attempts allowed within a period of time (can be seconds, minutes, hours, or days).

Returns:

The parsed rate limit information.

Return type:

RateLimit

__init__(*, total_limit: int, period_secs: 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:

• total_limit (int) – The total number of failed attempts allowed.

• period_secs (int) – The time period in seconds for a rate limit window.

total_limit: int¶

The total number of failed attempts allowed.

period_secs: int¶

The time period in seconds for a rate limit window.

get_reset_timestamp(timestamp: int) → int[source]¶

Return the timestamp until a rate limit is reset.

This calculates the number of seconds from the given timestamp when a rate limit period will reset.

Parameters:

timestamp (int) – The time in seconds used as “now” for the calculation.

Returns:

The timestamp at which the rate limit will reset.

Return type:

int

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

Return whether the two Rate instances are equal.

Parameters:

other (object) – The object to compare to.

Returns:

Return true if the count and seconds match.

Return type:

bool

__repr__() → str[source]¶

Return a string representation of the instance.

Returns:

The string representation.

Return type:

str

__annotations__ = {'period_secs': 'int', 'total_limit': 'int'}¶

__hash__ = None¶

check_rate_limit(*, rate_limit: RateLimit | str | None, key: str | Sequence[str], increment_count: bool = False) → RateLimitUsage[source]¶

Return rate limit status for a given key.

This fetches the rate limit status for a key, optionally incrementing the count towards the limit in the process.

New in version 6.0.

Parameters:

• rate_limit (str or RateLimit) –

  The default limit for any new rate limits.

  This may be a rate limit string or a pre-parsed RateLimit.

  If None, then rate limiting will not be performed. A result with a count of 1 will be returned.

• key (str or list of str) –

  The rate limit key associated with the rate limit.

  This key is used along with other state to form a cache key. It may be a string or a sequence of components for a key.

• increment_count (bool, optional) – Whether to increment the count toward the rate limit.

Returns:

The resulting rate limit stats for the key.

Return type:

RateLimitUsage