Cooldown Reference#

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

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

__init__(limit: int, time_period: ~typing.Union[float, ~datetime.timedelta], bucket: ~typing.Optional[~cooldowns.protocols.bucket.CooldownBucketProtocol] = None, func: ~typing.Optional[~typing.Callable] = None, *, cooldown_id: ~typing.Optional[~typing.Union[int, str]] = None, check: ~typing.Optional[~typing.Callable[[~typing.Any, ~typing.Any], ~typing.Coroutine[~typing.Any, ~typing.Any, ~typing.Any]]] = <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[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.

property bucket: CooldownBucketProtocol#

Returns the underlying bucket to process cooldowns against.

clear(bucket: Optional[_HashableArguments] = 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: Optional[Callable]#

Returns the wrapped function.

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) → Optional[CooldownTimesPer]#

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.

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