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: Returns: The result of calculating whether the user should be rate-limited.
Return type:
-
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
-
-
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
, orL - 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.
-