Using Rush’s Throttle

The primary interface intended to be used by Rush’s users is the Throttle class. It does the heavy lifting in ensuring that the limiter is used and works to abstract away the underlying moving pieces.

class rush.throttle.Throttle(rate: rush.quota.Quota, limiter: rush.limiters.base.BaseLimiter)

The class that acts as the primary interface for throttles.

This class requires the intantiated rate quota and limiter and handles passing the right arguments to the limiter.

limiter

The instance of the rate limiting algorithm that should be used by the throttle.

rate

The instantiated Quota that tells the throttle and limiter what the limits and periods are for rate limiting.

check(key: str, quantity: int) → rush.result.RateLimitResult

Check if the user should be rate limited.

Parameters:
  • key (str) – The key to use for rate limiting.
  • quantity (int) – How many resources is being requested against the rate limit.
Returns:

The result of calculating whether the user should be rate-limited.

Return type:

RateLimitResult

clear(key: str) → rush.result.RateLimitResult

Clear any existing limits for the given key.

Parameters:key (str) – The key to use for rate limiting that should be cleared.
Returns:The result of resetting the rate-limit.
Return type:RateLimitResult
peek(key: str) → rush.result.RateLimitResult

Peek at the user’s current rate-limit usage.

Note

This is equivalent to calling check() with a quantity of 0.

Parameters:key (str) – The key to use for rate limiting.
Returns:The current rate-limit usage.
Return type:RateLimitResult
class rush.quota.Quota(period: datetime.timedelta, count: int, maximum_burst: int = 0)

The definition of a user’s quota of resources.

period

The time between equally spaced requests. This must be greater than 0 seconds.

count

The number of requests to a resource allowed in the period. This must be greater than 0.

maximum_burst

The number of requests that will be allowed to exceed the rate in a single burst. This must be greater than or equal to 0 and defaults to 0.

limit

Return the calculated limit including maximum burst.

classmethod per_day(count: int, *, maximum_burst: int = 0) → Q

Create a quota based on the number allowed per day.

Parameters:count (int) – The number of requests allowed per day.
Returns:A new quota.
Return type:Quota
classmethod per_hour(count: int, *, maximum_burst: int = 0) → Q

Create a quota based on the number allowed per hour.

Parameters:count (int) – The number of requests allowed per hour.
Returns:A new quota.
Return type:Quota
classmethod per_minute(count: int, *, maximum_burst: int = 0) → Q

Create a quota based on the number allowed per minute.

Parameters:count (int) – The number of requests allowed per minute.
Returns:A new quota.
Return type:Quota
classmethod per_second(count: int, *, maximum_burst: int = 0) → Q

Create a quota based on the number allowed per second.

Parameters:count (int) – The number of requests allowed per second.
Returns:A new quota.
Return type:Quota
class rush.result.RateLimitResult(limit: int, limited: bool, remaining: int, reset_after: datetime.timedelta, retry_after: datetime.timedelta)

A result of checking a ratelimit.

The attributes on this object are:

limit

The integer limit that was checked against, e.g., if the user’s ratelimit is 10,000 this value will be 10,000 regardless of how much they have consumed.

limited

Whether or not the user should be ratelimited (a.k.a., throttled).

remaining

The integer representing how much of the user’s ratelimit is left. This should be the number of requests made during the time period, N, subtracted from the limit, L, or L - N.

reset_after

This will be a timedelta representing how much time is left until the ratelimit resets. For example if the ratelimit will reset in 800ms then this might look like:

datetime.timedelta(0, 0, 800000)
# == datetime.timedelta(milliseconds=800)
retry_after

This will be a timedelta representing the length of time after which a retry can be made.

resets_at(from_when: Optional[datetime.datetime] = None) → datetime.datetime

Calculate the reset time from UTC now.

Returns:The UTC timezone-aware datetime representing when the limit resets.
retry_at(from_when: Optional[datetime.datetime] = None) → datetime.datetime

Calculate the retry time from UTC now.

Returns:The UTC timezone-aware datetime representing when the user can retry.