Cooldown Reference#

class cooldowns.Cooldown(limit: int, time_period: float | ~datetime.timedelta, bucket: ~cooldowns.protocols.bucket.CooldownBucketProtocol | ~cooldowns.protocols.bucket.AsyncCooldownBucketProtocol | None = None, func: ~typing.Callable | None = None, *, cooldown_id: int | str | None = None, check: ~typing.Callable[[~typing.Any, ~typing.Any], ~typing.Coroutine[~typing.Any, ~typing.Any, ~typing.Any]] | None = <function default_check>)#

Represents a cooldown for any given :type:`Callable`.

__init__(limit: int, time_period: float | ~datetime.timedelta, bucket: ~cooldowns.protocols.bucket.CooldownBucketProtocol | ~cooldowns.protocols.bucket.AsyncCooldownBucketProtocol | None = None, func: ~typing.Callable | None = None, *, cooldown_id: int | str | None = None, check: ~typing.Callable[[~typing.Any, ~typing.Any], ~typing.Coroutine[~typing.Any, ~typing.Any, ~typing.Any]] | None = <function default_check>) → None#

Parameters:

limit (int) – How many call’s can be made in the time period specified by time_period
time_period (Union[float, datetime.timedelta]) – The time period related to limit. This is seconds.
bucket (Optional[Union[CooldownBucketProtocol, AsyncCooldownBucketProtocol]]) –
The Bucket implementation to use as a bucket to separate cooldown buckets.

Defaults to CooldownBucket.all
func (Optional[Callable]) – The function this cooldown is attached to
cooldown_id (Optional[Union[int, str]]) – Useful for resetting individual stacked cooldowns. This should be unique globally, behaviour is not guaranteed if not unique.
check (Optional[MaybeCoro]) –
The check used to validate calls to this Cooldown.

This is not used here, however, its required as an implementation detail for shared cooldowns and can be safely ignored as a parameter.

Note

This check will be given the same arguments as the item you are applying the cooldown to.

property bucket: CooldownBucketProtocol | AsyncCooldownBucketProtocol#: Returns the underlying bucket to process cooldowns against.

clear(bucket: _HashableArguments | None = None, *, force_evict: bool = False) → None#

Remove all un-needed buckets, this maintains buckets which are currently tracking cooldown’s.

Parameters:

bucket (Optional[_HashableArguments]) – The bucket we wish to reset
force_evict (bool) –
If True, delete all tracked cooldown’s regardless of whether or not they are needed.

I.e. reset this back to a fresh state.

Notes

You can get _HashableArguments by using the Cooldown.get_bucket() method.

property func: Callable | None#: Returns the wrapped function.

async get_bucket(*args, **kwargs) → _HashableArguments#

Return the given bucket for some given arguments.

This uses the underlying CooldownBucket and will return a _HashableArguments instance which is inline with how Cooldown’s function.

Parameters:

args (Any) – The arguments to get a bucket for
kwargs (Any) – The keyword arguments to get a bucket for

Returns:

An internally correct representation of a bucket for the given arguments.

This can then be used in Cooldown.clear() calls.

Return type:

_HashableArguments

get_cooldown_times_per(bucket: _HashableArguments) → TP | None#

Return the relevant CooldownTimesPer object for this bucket, returns None if one does not currently exist.

Parameters:: bucket (_HashableArguments) – The bucket you wish to receive against. Get this using Cooldown.get_bucket()
Returns:: The internal CooldownTimesPer object
Return type:: Optional[CooldownTimesPer]

get_state() → State#

Return the state of this cooldown as a dictionary in order to be able to persist it.

Returns:: This cooldown as a dictionary
Return type:: State

load_from_state(state: State) → None#

Load this cooldown as per state

Parameters:: state (State) – The state you wish to set this cooldown to

Notes

state should be the output of Cooldown.get_state() and remain unmodified in order for this operation to work.

async remaining_calls(*args, **kwargs) → int#

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

Parameters:

args –
pass. (Any arguments you will) –
kwargs – Any key-word arguments you will pass.

Returns:

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

Return type:

int

class cooldowns.StaticCooldown(limit: int, reset_times: ~datetime.time | ~typing.List[~datetime.time], bucket: ~cooldowns.protocols.bucket.CooldownBucketProtocol | ~cooldowns.protocols.bucket.AsyncCooldownBucketProtocol | None = None, func: ~typing.Callable | None = None, *, cooldown_id: int | str | None = None, check: ~typing.Callable[[~typing.Any, ~typing.Any], ~typing.Coroutine[~typing.Any, ~typing.Any, ~typing.Any]] | None = <function default_check>)#

A cooldown which implements a set amount of cooldown reset times per day.

__init__(limit: int, reset_times: ~datetime.time | ~typing.List[~datetime.time], bucket: ~cooldowns.protocols.bucket.CooldownBucketProtocol | ~cooldowns.protocols.bucket.AsyncCooldownBucketProtocol | None = None, func: ~typing.Callable | None = None, *, cooldown_id: int | str | None = None, check: ~typing.Callable[[~typing.Any, ~typing.Any], ~typing.Coroutine[~typing.Any, ~typing.Any, ~typing.Any]] | None = <function default_check>) → None#

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 (Optional[CooldownBucketProtocol]) –
The Bucket implementation to use as a bucket to separate cooldown buckets.

Defaults to CooldownBucket.all
func (Optional[Callable]) – The function this cooldown is attached to
cooldown_id (Optional[Union[int, str]]) – Useful for resetting individual stacked cooldowns. This should be unique globally, behaviour is not guaranteed if not unique.
check (Optional[MaybeCoro]) –
The check used to validate calls to this Cooldown.

This is not used here, however, its required as an implementation detail for shared cooldowns and can be safely ignored as a parameter.

Note

This check will be given the same arguments as the item you are applying the cooldown to.

Notes

All times are internally handled based off UTC.