Skip to content

Hooks#

Hooks allow you to run code before or after a command is run. They also allow you to create checks for a certain command.

This is a simple hook that says "hello there" before every command you hook it to.

async def my_hook(ctx: crescent.Context) -> None:
    await ctx.respond("Hello there")

To use this hook on a command, simply do: 

@client.include
@crescent.hook(my_hook)
@crescent.command
async def my_command(ctx: crescent.Context) -> None:
    await ctx.respond("General Kenobi")

This command will respond "Hello there" and "General kenobi" in two different messages.

You can access command options in hooks with ctx.options. This is a dict of option name to option value.

Using hooks as checks#

You can also stop a command callback from running in a hook. Simply return crescent.HookResult(exit=True)

This is a command that uses that feature. It stops you from using the command if your name has an "L" in it.

async def no_Ls_allowed(ctx: crescent.Context) -> crescent.HookResult:
    if "l" in ctx.user.username.lower():
        await ctx.respond("You can't use this command!")
        return crescent.HookResult(exit=True)

    return crescent.HookResult()

@client.include
@crescent.hook(no_Ls_allowed)
@crescent.command
async def my_command(ctx: crescent.Context) -> None:
    await ctx.respond("Hello")

Running a hook after a command#

To run a hook after a command, add after=True to the decorator. This command will return "General Kenobi" then "Hello there" in two separate messages. 

async def my_hook(ctx: crescent.Context) -> None:
    await ctx.respond("Hello there")

To use this hook on a command, simply do: 

@client.include
@crescent.hook(my_hook, after=True)
@crescent.command
async def my_command(ctx: crescent.Context) -> None:
    await ctx.respond("General Kenobi")

Adding hooks to more than commands#

Bots and plugins (we will cover these later) support hooks by adding them with the command_hooks and command_after_hooks kwargs. Hooks on the bot object will run for all commands. Hooks on the plugin object will run for all commands in that plugin.

bot = crescent.Bot("...", command_hooks=[hook_a, hook_b])

crescent.Group and crescent.SubGroup also support hooks. Use the hooks and after_hooks kwargs to add them. Groups and sub groups will add hooks to any commands in their respective groups.

group = crescent.Group("group", hooks=[hook_a])
sub_group = group.sub_group("sub-group", hooks=[hook_b])

Sub groups will inherit all hooks from the group.

Hook Resolution Order#

Command -> Sub Group -> Group -> Plugin -> Bot

Using hooks for ratelimiting#

One of crescent's built in extensions is crescent.ext.cooldowns, allowing for rate limiting. To use this extension, you must install hikari-crescent[cooldowns].

import crescent
import datetime
from crescent.ext import cooldowns

bucket_size = 1
delay = datetime.timedelta(seconds=20)

@client.include
@crescent.hook(cooldowns.cooldown(bucket_size, delay))
@crescent.command
async def my_command(ctx: crescent.Context) -> None:
    await ctx.respond("General Kenobi")

To see more information on this function, check the API reference for crescent.ext.cooldowns.