Limiters

This module contains all the built-in limiter hooks contained in arc.

Note

Any object that implements the LimiterProto protocol is a valid limiter. If you are looking to create your custom ratelimiter implementation, you should start there.

LimiterHook

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

Bases: RateLimiter[Context[ClientT]], LimiterProto[ClientT]

The default implementation of a ratelimiter that can be used as a hook.

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]

See Also

• global_limiter
• guild_limiter
• channel_limiter
• user_limiter
• member_limiter
• custom_limiter

__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(ctx: Context[ClientT], /, *, wait: bool = True) -> None

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

PARAMETER	DESCRIPTION
ctx	The context to evaluate the ratelimit under. TYPE: Context[Any]
wait	Determines if this call should block in case of hitting a ratelimit. TYPE: bool DEFAULT: True

RAISES	DESCRIPTION
UnderCooldownError	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.

channel_limiter

channel_limiter(period: float, limit: int) -> LimiterHook[Any]

Create a channel ratelimiter.

This ratelimiter is shared across all contexts in a channel.

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

RAISES	DESCRIPTION
RateLimiterExhaustedError	If the limiter is exhausted.

Example

@arc.with_hook(arc.channel_limiter(5.0, 1))

custom_limiter

custom_limiter(
    period: float, limit: int, get_key_with: Callable[[Context[Any]], str]
) -> LimiterHook[Any]

Create a ratelimiter with a custom key extraction function.

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. This key is used to identify the bucket. For instance, to create a ratelimiter that is shared across all contexts in a guild, you would use lambda ctx: str(ctx.guild_id). TYPE: Callable[[Context[Any]], str]

RAISES	DESCRIPTION
RateLimiterExhaustedError	If the limiter is exhausted.

Example

# This is identical to 'arc.guild_limiter(5.0, 1)'
@arc.with_hook(arc.custom_limiter(5.0, 1, lambda ctx: str(ctx.guild_id)))

global_limiter

global_limiter(period: float, limit: int) -> LimiterHook[Any]

Create a global ratelimiter.

This ratelimiter is shared across all invocation contexts.

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

RAISES	DESCRIPTION
RateLimiterExhaustedError	If the limiter is exhausted.

Example

@arc.with_hook(arc.global_limiter(5.0, 1))

guild_limiter

guild_limiter(period: float, limit: int) -> LimiterHook[Any]

Create a guild ratelimiter.

This ratelimiter is shared across all contexts in a guild.

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

RAISES	DESCRIPTION
RateLimiterExhaustedError	If the limiter is exhausted.

Example

@arc.with_hook(arc.guild_limiter(5.0, 1))

member_limiter

member_limiter(period: float, limit: int) -> LimiterHook[Any]

Create a member ratelimiter.

This ratelimiter is shared across all contexts by a member in a guild. The same user in a different guild will be assigned a different bucket.

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

RAISES	DESCRIPTION
RateLimiterExhaustedError	If the limiter is exhausted.

Example

@arc.with_hook(arc.member_limiter(5.0, 1))

user_limiter

user_limiter(period: float, limit: int) -> LimiterHook[Any]

Create a user ratelimiter.

This ratelimiter is shared across all contexts by a user.

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

RAISES	DESCRIPTION
RateLimiterExhaustedError	If the limiter is exhausted.

Example

@arc.with_hook(arc.user_limiter(5.0, 1))