Decorator Usage

You have two choices for decorators, as documented below.

For example usages, view the examples section.

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

Wrap this Callable in a cooldown.

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

• check (Optional[MaybeCoro]) –

  A Callable which dictates whether 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.

  Note

  This check will be given the same arguments as the item you are applying the cooldown 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.

Raises:

• RuntimeError – Expected the decorated function to be a coroutine

• CallableOnCooldown – This call resulted in a cooldown being put into effect

cooldowns.static_cooldown(limit: int, reset_times: ~datetime.time | ~typing.List[~datetime.time], bucket: ~cooldowns.protocols.bucket.CooldownBucketProtocol | ~cooldowns.protocols.bucket.AsyncCooldownBucketProtocol, check: ~typing.Callable[[~typing.Any, ~typing.Any], ~typing.Coroutine[~typing.Any, ~typing.Any, ~typing.Any]] | None = <function default_check>, *, cooldown_id: int | str | None = 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.

Raises:

• RuntimeError – Expected the decorated function to be a coroutine

• CallableOnCooldown – This call resulted in a cooldown being put into effect

cooldowns.shared_cooldown(cooldown_id: int | str | None)

Wrap this Callable in a shared cooldown.

Use define_shared_cooldown() before this.

Parameters:

cooldown_id (Optional[Union[int, str]]) – The cooldown for the registered shared cooldown.

Raises:

• RuntimeError – Expected the decorated function to be a coroutine

• CallableOnCooldown – This call resulted in a cooldown being put into effect

• NonExistent – Could not find a cooldown with this ID registered.