General API Reference

Commands

Filament provides a different method of defining commands than is provided by lightbulb. It uses a class-based approach similar to how slash commands were defined in lightbulb v1.

To create commands you need to subclass filament.commands.impl.CommandLike and define class attributes in order to specify parameters such as command name, description, etc.

Example:

import lightbulb
from lightbulb import commands
from lightbulb.ext import filament

class EchoCommand(filament.CommandLike):
    # This defines the command types that this command will implement
    # Similar to the @lightbulb.implements decorator for lightbulb commands
    implements = [commands.SlashCommand, commands.PrefixCommand]

    # Define the command's name
    name = "echo"
    # Define the command's description
    description = "Repeats the input text

    # Define 0 or more options for the command. In this case we will have a single
    # string option
    text_opt = filament.opt("text", "Text to repeat", modifier=commands.OptionModifier.CONSUME_REST)

    # Define the callback function for this command
    async def callback(self, ctx: lightbulb.context.Context) -> None:
        await ctx.respond(ctx.options.text)

You are required to override the following attributes:

There are also some attributes available that you can override for additional functionality:

Command Groups and Subcommands

Creating groups and subcommands is relatively simple. You need to first create a command that implements a command group:

from lightbulb import commands
from lightbulb.ext import filament

class FooGroup(filament.CommandLike):
    # Define that this command implements SlashCommandGroup
    implements = [commands.SlashCommandGroup]
    # The command's name
    name = "foo"
    # The command's description
    description = "test command group"
    # Note that we don't need to override the callback here because due to a discord limitation,
    # slash command groups cannot be invoked.

To create a subcommand for the above group, we create a second command class and mark it as a child of FooGroup. The subcommand class must implement the appropriate command type, which in this case is lightbulb.commands.slash.SlashSubCommand:

import lightbulb
from lightbulb import commands
from lightbulb.ext import filament

@FooGroup.child
class BarSubcommand(filament.CommandLike):
    # Define that this command implements SlashSubCommand
    implements = [commands.SlashSubCommand]
    # The command's name
    name = "bar"
    # The command's description
    description = "test subcommand"

    async def callback(self, ctx: lightbulb.context.Context) -> None:
        # Just send a simple message to the invocation context so we know the command worked
        await ctx.respond("foo bar")

Note

When adding the command to the bot, you must pass an instance of the command class instead of the class itself. E.g. bot.command(FooGroup()) not bot.command(FooGroup).

API Reference

class filament.commands.impl.CommandLike(*args: Any, **kwargs: Any)

Base class for filament’s command implementation. All of your command’s must be a subclass of this.

async callback(ctx: lightbulb.context.base.Context) → None

The callback function for this command - called when the command is invoked.

Parameters

ctx (lightbulb.context.base.Context) – The context that the command was invoked under.

Returns

None

classmethod child(other: Optional[Type[filament.commands.impl.CommandLike]] = None) → Union[Type[filament.commands.impl.CommandLike], Callable[[Type[filament.commands.impl.CommandLike]], Type[filament.commands.impl.CommandLike]]]

Registers a CommandLike subclass as a child to this command. This can be used as a first or second order decorator, or called manually with the CommandLike subclass to add as a child.

classmethod set_error_handler(other: Optional[Callable[[lightbulb.context.base.Context], Coroutine[Any, Any, bool]]] = None) → Union[Callable[[lightbulb.context.base.Context], Coroutine[Any, Any, bool]], Callable[[Callable[[lightbulb.context.base.Context], Coroutine[Any, Any, bool]]], Callable[[lightbulb.context.base.Context], Coroutine[Any, Any, bool]]]]

Registers a coroutine function as an error handler for this command. This can be used as a first or second order decorator, or called manually with the function to register.

classmethod set_help(text: Optional[str] = None) → Optional[Callable[[Callable[[lightbulb.commands.base.Command, lightbulb.context.base.Context], str]], Callable[[lightbulb.commands.base.Command, lightbulb.context.base.Context], str]]]

Sets the method for getting long help text for this command. This function can be called with the help text to use or can be used as a second order decorator for a syncronous function to set a callable used to get the help text for the command.

Parameters

text (Optional[str]) – Text to use as the long help text for this command. If not provided then the function will be assumed to be a decorator.

property aliases: Sequence[str]

Sequence of aliases to use for this command. This only applies to prefix commands.

property auto_defer: bool

Whether or not a deferred response should be automatically created for invocations of this command.

property checks: Sequence[lightbulb.checks.Check]

Sequence of checks to user for this command.

property cooldown_manager: Optional[lightbulb.cooldowns.CooldownManager]

The cooldown manager instance to use for this command.

abstract property description: str

The description of this command.

property ephemeral: bool

Whether or not responses from this command should be ephemeral by default. Only applies to application commands.

property guilds: t.Union[int, t.Sequence[int], hikari.UNDEFINED]

Guild ID or IDs to restrict this command to. This only applies to application commands.

property hidden: bool

Whether or not this command should be hidden from the default help command.

abstract property implements: Sequence[Type[lightbulb.commands.base.Command]]

Sequence of the lightbulb command types that this command class will implement.

property inherit_checks: bool

Whether or not this command should inherit checks from its parent command. Only applies to subcommands.

abstract property name: str

The name of this command.

property parser: Optional[Type[lightbulb.utils.parser.BaseParser]]

The argument parser class to use for this command. If not specified lightbulb.utils.parser.Parser will be used. Only applies to prefix commands.

filament.commands.impl.opt(name: str, description: str, **kwargs: Any) → lightbulb.commands.base.OptionLike

Function that defines an option inside a command class. This function takes all the same arguments as lightbulb.decorators.option.

Parameters

  • name (str) – Name of the option.

  • description (str) – Description of the option.

  • **kwargs – Additional keyword arguments passed to the lightbulb.decorators.option decorator.

Returns

Created option object.

Return type

lightbulb.commands.base.OptionLike

filament.commands.impl.option(name: str, description: str, **kwargs: Any) → lightbulb.commands.base.OptionLike

Alias for opt.