Buckets API Reference#

class lightbulb.buckets.Bucket(length: float, max_usages: int, cooldown_algorithm: ~typing.Type[~lightbulb.cooldown_algorithms.CooldownAlgorithm] = <class 'lightbulb.cooldown_algorithms.BangBangCooldownAlgorithm'>)[source]#

Base class that represents a bucket that cooldowns or max concurrency limits can be applied under. All buckets must inherit from this class.

Note that for max concurrency limiting, the bucket object will never be instantiated.

Parameters:

length (float) – Length of the cooldown timer.
max_usages (int) – Number of command usages before the cooldown is activated.

acquire() → CooldownStatus | Coroutine[Any, Any, CooldownStatus][source]#

Get the current state of the cooldown and add a command usage if the cooldown is not currently active or has expired.

This method is only used when processing cooldowns.

Returns:: The status of the cooldown bucket.
Return type:: CooldownStatus

abstract classmethod extract_hash(context: ctx_base.Context) → t.Hashable[source]#

Extracts the hash from the context which links a command usage to a single bucket.

Parameters:: context (Context) – The context the command was invoked under.
Returns:: Hashable object linking the context to a bucket.
Return type:: Hashable

property active: bool#: Whether the cooldown represented by the bucket is currently active.

property expired: bool#: Whether the cooldown represented by the bucket has expired.

start_time: float | None#: The start time of the bucket cooldown. This is relative to time.perf_counter().

class lightbulb.buckets.ChannelBucket(length: float, max_usages: int, cooldown_algorithm: ~typing.Type[~lightbulb.cooldown_algorithms.CooldownAlgorithm] = <class 'lightbulb.cooldown_algorithms.BangBangCooldownAlgorithm'>)[source]#

Channel bucket. All cooldowns and concurrency limits will be applied per channel if you use this bucket.

classmethod extract_hash(context: ctx_base.Context) → t.Hashable[source]#

Extracts the hash from the context which links a command usage to a single bucket.

Parameters:: context (Context) – The context the command was invoked under.
Returns:: Hashable object linking the context to a bucket.
Return type:: Hashable

class lightbulb.buckets.GlobalBucket(length: float, max_usages: int, cooldown_algorithm: ~typing.Type[~lightbulb.cooldown_algorithms.CooldownAlgorithm] = <class 'lightbulb.cooldown_algorithms.BangBangCooldownAlgorithm'>)[source]#

Global bucket. All cooldowns and concurrency limits will be applied globally if you use this bucket.

classmethod extract_hash(context: ctx_base.Context) → t.Hashable[source]#

Extracts the hash from the context which links a command usage to a single bucket.

Parameters:: context (Context) – The context the command was invoked under.
Returns:: Hashable object linking the context to a bucket.
Return type:: Hashable

class lightbulb.buckets.GuildBucket(length: float, max_usages: int, cooldown_algorithm: ~typing.Type[~lightbulb.cooldown_algorithms.CooldownAlgorithm] = <class 'lightbulb.cooldown_algorithms.BangBangCooldownAlgorithm'>)[source]#

Guild bucket. All cooldowns and concurrency limits will be applied per guild if you use this bucket. The command will still be permitted to be run in DMs in which case the DM channel ID will be used as the cooldown identifier instead of a guild ID.

classmethod extract_hash(context: ctx_base.Context) → t.Hashable[source]#

Extracts the hash from the context which links a command usage to a single bucket.

Parameters:: context (Context) – The context the command was invoked under.
Returns:: Hashable object linking the context to a bucket.
Return type:: Hashable

class lightbulb.buckets.UserBucket(length: float, max_usages: int, cooldown_algorithm: ~typing.Type[~lightbulb.cooldown_algorithms.CooldownAlgorithm] = <class 'lightbulb.cooldown_algorithms.BangBangCooldownAlgorithm'>)[source]#

User bucket. All cooldowns and concurrency limits will be applied per user if you use this bucket.

classmethod extract_hash(context: ctx_base.Context) → t.Hashable[source]#

Extracts the hash from the context which links a command usage to a single bucket.

Parameters:: context (Context) – The context the command was invoked under.
Returns:: Hashable object linking the context to a bucket.
Return type:: Hashable