Buckets API Reference#

class lightbulb.buckets.Bucket(length: float, max_usages: int)[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() lightbulb.buckets.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.

commands_run: int#

Commands run for this bucket since it was created.

property expired: bool#

Whether the cooldown represented by the bucket has expired.

start_time: Optional[float]#

The start time of the bucket cooldown. This is relative to time.perf_counter().

class lightbulb.buckets.ChannelBucket(length: float, max_usages: int)[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.CooldownStatus(value)[source]#

An enumeration.

class lightbulb.buckets.GlobalBucket(length: float, max_usages: int)[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)[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)[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