lightbulb.prefab.cooldowns

exception OnCooldown(remaining: float)[source]

Exception raised when a user attempts to invoke command, but it is on cooldown.

remaining: float

The remaining time in seconds before the command can be invoked again.

class CommandCooldown(ctx: Context, cls: _FixedWindow | _SlidingWindow)[source]

Utility class registered as a dependency when a cooldown hook runs for a command. Can be injected into any dependency-enabled function in order to manipulate the cooldown state within your code.

async apply() → None[source]

Applies the cooldown to the enclosed context.

Returns:

None

Raises:

~OnCooldown – If the cooldown has been exceeded.

async reset() → None[source]

Resets the cooldown for the enclosed context.

Returns:

None

async undo() → None[source]

Undoes the last cooldown application for the enclosed context. If called multiple times, it will continue to undo each cooldown application until all have been removed.

Returns:

None

fixed_window(window_length: float, allowed_invocations: int, bucket: Literal['global', 'user', 'channel', 'guild'] | Callable[[Context], Snowflake | int | Coroutine[Any, Any, Snowflake | int]]) → ExecutionHook[source]

Creates a hook that applies a cooldown to command invocations using the fixed-window cooldown algorithm. The created hook raises OnCooldown when the cooldown is exceeded. This hook is run during the COOLDOWNS execution step.

You can pass one of "global", "user", "channel" or "guild" to the bucket parameter, or a synchronous or asynchronous function to be used to resolve the bucket hash to apply the cooldown to.

  • "global" - every invocation of the command shares a common cooldown

  • "user" - cooldown is applied individually for each user

  • "channel" - cooldown is applied individually for each channel

  • "guild" - cooldown is applied individually for each guild. If in DMs, the cooldown is applied individually to each DM.

If DI is enabled, this hook will register an instance of CommandCooldown when it is executed.

Parameters:

  • window_length – The length of the cooldown window.

  • allowed_invocations – The number of invocations allowed within one window.

  • bucket – The bucket that should be used to classify invocations.

Returns:

The created hook.

sliding_window(window_length: float, allowed_invocations: int, bucket: Literal['global', 'user', 'channel', 'guild'] | Callable[[Context], Snowflake | int | Coroutine[Any, Any, Snowflake | int]]) → ExecutionHook[source]

Creates a hook that applies a cooldown to command invocations using the sliding-window cooldown algorithm. The created hook raises OnCooldown when the cooldown is exceeded. This hook is run during the COOLDOWNS execution step.

You can pass one of "global", "user", "channel" or "guild" to the bucket parameter, or a synchronous or asynchronous function to be used to resolve the bucket hash to apply the cooldown to.

  • "global" - every invocation of the command shares a common cooldown

  • "user" - cooldown is applied individually for each user

  • "channel" - cooldown is applied individually for each channel

  • "guild" - cooldown is applied individually for each guild. If in DMs, the cooldown is applied individually to each DM.

If DI is enabled, this hook will register an instance of CommandCooldown when it is executed.

Parameters:

  • window_length – The length of the cooldown window.

  • allowed_invocations – The number of invocations allowed within one window.

  • bucket – The bucket that should be used to classify invocations.

Returns:

The created hook.