Utility Usage#

Various utilities for using cooldowns.

cooldowns.define_shared_cooldown(limit: int, time_period: float, bucket: CooldownBucketProtocol, 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 (CooldownBucketProtocol) – 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.

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: Union[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.

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) Cooldown#

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) Cooldown#

Retrieve a shared Cooldown 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