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#
  • 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.


    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.

  • 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.


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.

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

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


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

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

Return type


get_cooldown_times_per(bucket: _HashableArguments) Optional[CooldownTimesPer]#

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


bucket (_HashableArguments) – The bucket you wish to receive against. Get this using Cooldown.get_bucket()


The internal CooldownTimesPer object

Return type


get_state() State#

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


This cooldown as a dictionary

Return type


load_from_state(state: State) None#

Load this cooldown as per state


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


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.

  • args

  • pass. (Any arguments you will) –

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


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

Return type