Utility Usage

Various utilities for using cooldowns.

cooldowns.define_shared_cooldown(limit: int, time_period: float, bucket: Union[CooldownBucketProtocol, AsyncCooldownBucketProtocol], cooldown_id: COOLDOWN_ID, *, check: Optional[MaybeCoro] = <function default_check>)

Define a global cooldown which can be used to ratelimit 1 or more callables under the same situations.

View the examples for how to use this.

Parameters:

• limit (int) – How many call’s can be made in the time period specified by time_period

• time_period (float) – The time period related to limit

• bucket (Union[CooldownBucketProtocol, AsyncCooldownBucketProtocol]) – The Bucket implementation to use as a bucket to separate cooldown buckets.

• cooldown_id (Union[int, str]) –

  The ID used to refer to this when defining a shared_cooldown

  This should be unique globally, behaviour is not guaranteed if not unique.

• check (Optional[MaybeCoro]) –

  A Callable which dictates whether or not to apply the cooldown on current invoke.

  If this Callable returns a truthy value, then the cooldown will be used for the current call.

  I.e. If you wished to bypass cooldowns, you would return False if you invoked the Callable.

Raises:

CooldownAlreadyExists – A Cooldown with this ID already exists.

Notes

All times are internally handled based off UTC.

cooldowns.define_shared_static_cooldown(limit: int, reset_times: Union[datetime.time, List[datetime.time]], bucket: Union[CooldownBucketProtocol, AsyncCooldownBucketProtocol], cooldown_id: COOLDOWN_ID, *, check: Optional[MaybeCoro] = <function default_check>)

Define a global cooldown which can be used to ratelimit 1 or more callables under the same situations.

View the examples for how to use this.

Parameters:

• limit (int) – How many call’s can be made in the time period specified by time_period

• reset_times (Union[datetime.time, List[datetime.time]]) – A time or list of the possible times in the day to reset cooldowns at

• bucket (Union[CooldownBucketProtocol, AsyncCooldownBucketProtocol]) – The Bucket implementation to use as a bucket to separate cooldown buckets.

• cooldown_id (Union[int, str]) –

  The ID used to refer to this when defining a shared_cooldown

  This should be unique globally, behaviour is not guaranteed if not unique.

• check (Optional[MaybeCoro]) –

  A Callable which dictates whether or not to apply the cooldown on current invoke.

  If this Callable returns a truthy value, then the cooldown will be used for the current call.

  I.e. If you wished to bypass cooldowns, you would return False if you invoked the Callable.

Raises:

CooldownAlreadyExists – A Cooldown with this ID already exists.

async cooldowns.get_remaining_calls(func: Callable[[Any, Any], Coroutine[Any, Any, Any]], *args, **kwargs) → int

Given a Callable, return the amount of remaining available calls before these arguments will result in the callable being rate-limited.

Parameters:

• func (MaybeCoro) – The Callable you want to check.

• args – Any arguments you will pass.

• kwargs – Any key-word arguments you will pass.

Returns:

How many more times this Callable can be called without being rate-limited.

Return type:

int

Raises:

NoRegisteredCooldowns – The given Callable has no cooldowns.

Notes

This aggregates all attached cooldowns and returns the lowest remaining amount.

cooldowns.reset_cooldowns(func: Callable[[Any, Any], Coroutine[Any, Any, Any]])

Reset all cooldown’s on this Callable back to default settings.

Parameters:

func (MaybeCoro) – The func with cooldowns we should reset.

Raises:

NoRegisteredCooldowns – The func has no cooldown’s attached.

cooldowns.reset_cooldown(cooldown_id: int | str)

Reset the cooldown denoted by cooldown_id.

Parameters:

cooldown_id (Union[int, str]) – The id of the cooldown we wish to reset

Raises:

NonExistent – Cannot find a cooldown with this id.

async cooldowns.reset_bucket(func: Callable[[Any, Any], Coroutine[Any, Any, Any]], *args, **kwargs)

Reset all buckets matching the provided arguments.

Parameters:

• func (MaybeCoro) – The func with cooldowns we should reset.

• args – Any arguments you will pass.

• kwargs – Any key-word arguments you will pass.

Notes

Does nothing if it resets nothing.

cooldowns.get_cooldown(func: MaybeCoro, cooldown_id: COOLDOWN_ID) → CooldownT

Get the Cooldown object from the func with the provided cooldown id.

Parameters:

• func (MaybeCoro) – The func with this cooldown.

• cooldown_id (Union[int, str]) – The id of the cooldown we wish to get

Returns:

The associated cooldown

Return type:

Cooldown

Raises:

NonExistent – Failed to find that cooldown on this func.

cooldowns.get_shared_cooldown(cooldown_id: COOLDOWN_ID) → CooldownT

Retrieve a shared Cooldown or StaticCooldown object.

Parameters:

cooldown_id (Union[int, str]) – The id of the cooldown we wish to get

Returns:

The associated cooldown

Return type:

Cooldown

Raises:

NonExistent – Failed to find that cooldown

cooldowns.get_all_cooldowns(func: MaybeCoro) → List[CooldownT]

Get all the Cooldown objects from the func provided.

Parameters:

func (MaybeCoro) – The func with this cooldown.

Returns:

The associated cooldowns

Return type:

List[Cooldown]

Raises:

NoRegisteredCooldowns – No cooldowns on this func