RateLimiter#

This module contains the default ratelimiter implementation in arc.

RateLimiter #

RateLimiter(period: float, limit: int, *, get_key_with: Callable[[KeyT], str])

Bases: Generic[KeyT]

A fixed window ratelimiter implementation.

It is generic over the type of object it extracts the key from (KeyT), and must also be given a key extraction function. It can be used independently for any purpose, or can be used as a hook via LimiterHook.

Tip

If you're looking to use this ratelimiter implementation as a hook, see LimiterHook along with all the other built-in limiter hooks.

PARAMETER	DESCRIPTION
`period`	The period, in seconds, after which the bucket resets. TYPE: `float`
`limit`	The amount of requests allowed in a bucket. TYPE: `int`
`get_key_with`	A callable that returns a key for the ratelimiter bucket. TYPE: `Callable[[Context[Any]], str]`

call `async` #

__call__(item: KeyT) -> HookResult

Acquire a ratelimit, fail if ratelimited.

PARAMETER	DESCRIPTION
`item`	The context to evaluate the ratelimit under. TYPE: `KeyT`

RETURNS	DESCRIPTION
`HookResult`	A hook result to conform to the limiter protocol.

RAISES	DESCRIPTION
`UnderCooldownError`	If the ratelimiter is ratelimited.

acquire `async` #

acquire(item: KeyT, /, *, wait: bool = True) -> None

Acquire a bucket, block execution if ratelimited and wait is True.

PARAMETER	DESCRIPTION
`item`	The item to evaluate the ratelimit under. TYPE: `KeyT`
`wait`	Determines if this call should block in case of hitting a ratelimit. TYPE: `bool` DEFAULT: `True`

RAISES	DESCRIPTION
`RateLimiterExhaustedError`	If the ratelimiter is ratelimited and wait is False.

get_key #

get_key(item: KeyT) -> str

Get key for ratelimiter bucket.

is_rate_limited #

is_rate_limited(item: KeyT) -> bool

Returns a boolean determining if the ratelimiter is ratelimited or not.

PARAMETER	DESCRIPTION
`item`	The context to evaluate the ratelimit under. TYPE: `Context[Any]`

RETURNS	DESCRIPTION
`bool`	A boolean determining if the ratelimiter is ratelimited or not.

reset #

reset(ctx: KeyT) -> None

Reset the ratelimit for a given context.

RateLimiterExhaustedError #

RateLimiterExhaustedError(
    limiter: RateLimiter[Any], retry_after: float, *args: Any
)

Bases: Exception

Raised when a RateLimiter is acquired while it is exhausted, and the wait parameter is set to False.

ATTRIBUTE	DESCRIPTION
`retry_after`	The amount of time in seconds until the command is off cooldown. TYPE: `float`
`limiter`	The limiter that was rate limited. TYPE: `LimiterProto`