Commands¶

Using commands and events is the main way to interact with the bot.

Argument ¶

Represents a command argument.

Example

from niobot import NioBot, command, Argument

bot = NioBot(...)

@bot.command("echo")
def echo(ctx: niobot.Context, message: str):
    await ctx.respond(message)

bot.run(...)

Parameters:

Name	Type	Description	Default
`name`	`str`	The name of the argument. Will be used to know which argument to pass to the command callback.	required
`arg_type`	`_T`	The type of the argument (e.g. str, int, etc. or a custom type)	required
`description`	`Optional[str]`	The description of the argument. Will be shown in the auto-generated help command.	`None`
`default`	`Any`	The default value of the argument	`...`
`required`	`bool`	Whether the argument is required or not. Defaults to True if default is ..., False otherwise.	`...`
`parser`	`Callable[[Context, Argument, str], Optional[_T]]`	A function that will parse the argument. Defaults to the default parser.	`...`
`greedy`	`bool`	When enabled, will attempt to match as many arguments as possible, without raising an error. If no arguments can be parsed, is merely empty, otherwise is a list of parsed arguments.	`False`

internal_parser `staticmethod` ¶

internal_parser(
    _: Context, arg: Argument, value: str
) -> Optional[_T]

The default parser for the argument. Will try to convert the value to the argument type.

Command ¶

Represents a command.

Example

Note

This example uses the command decorator, but you can also use the Command class directly, but you likely won't need to, unless you want to pass a custom command class.

All that the @command decorator does is create a Command instance and add it to the bot's commands, while wrapping the function its decorating.

from niobot import NioBot, command

bot = NioBot(...)

@bot.command("hello")
def hello(ctx: niobot.Context):
    await ctx.respond("Hello, %s!" % ctx.message.sender)

bot.run(...)

Parameters:

Name	Type	Description	Default
`name`	`str`	The name of the command. Will be used to invoke the command.	required
`callback`	`Callable`	The callback to call when the command is invoked.	required
`aliases`	`Optional[list[str]]`	The aliases of the command. Will also be used to invoke the command.	`None`
`description`	`Optional[str]`	The description of the command. Will be shown in the auto-generated help command.	`None`
`disabled`	`bool`	Whether the command is disabled or not. If disabled, the command will be hidden on the auto-generated help command, and will not be able to be invoked.	`False`
`arguments`	`Optional[list[Argument]]`	A list of `Argument` instances. Will be used to parse the arguments given to the command. `ctx` is always the first argument, regardless of what you put here.	`None`
`usage`	`Optional[str]`	A string representing how to use this command's arguments. Will be shown in the auto-generated help. Do not include the command name or your bot's prefix here, only arguments. For example: `usage="<message> [times]"` will show up as `[p][command] <message> [times]` in the help command.	`None`
`hidden`	`bool`	Whether the command is hidden or not. If hidden, the command will be always hidden on the auto-generated help.	`False`
`greedy`	`bool`	When enabled, `CommandArgumentsError` will not be raised if too many arguments are given to the command. This is useful for commands that take a variable amount of arguments, and retrieve them via `Context.args`.	`False`

display_usage `property` ¶

display_usage: str

Returns the usage string for this command, auto-resolved if not pre-defined

autodetect_args `staticmethod` ¶

autodetect_args(callback) -> list[Argument]

Attempts to auto-detect the arguments for the command, based on the callback's signature

Parameters:

Name	Type	Description	Default
`callback`		The function to inspect	required

Returns:

Type	Description
`list[Argument]`	A list of arguments. `self`, and `ctx` are skipped.

eq ¶

__eq__(other)

Checks if another command's runtime ID is the same as this one's

can_run `async` ¶

can_run(ctx: Context) -> bool

Checks if the current user passes all of the checks on the command.

If the user fails a check, CheckFailure is raised. Otherwise, True is returned.

invoke `async` ¶

invoke(ctx: Context) -> Coroutine

Invokes the current command with the given context

Parameters:

Name	Type	Description	Default
`ctx`	`Context`	The current context	required

Raises:

Type	Description
`CommandArgumentsError`	Too many/few arguments, or an error parsing an argument.
`CheckFailure`	A check failed

construct_context ¶

construct_context(
    client: NioBot,
    room: MatrixRoom,
    src_event: RoomMessageText,
    invoking_prefix: str,
    meta: str,
    cls: type = Context,
) -> Context

Constructs the context for the current command.

You will rarely need to do this, the library automatically gives you a Context when a command is run.

Parameters:

Name	Type	Description	Default
`client`	`NioBot`	The current instance of the client.	required
`room`	`MatrixRoom`	The room the command was invoked in.	required
`src_event`	`RoomMessageText`	The source event that triggered the command. Must be `nio.RoomMessageText`.	required
`invoking_prefix`	`str`	The prefix that triggered the command.	required
`meta`	`str`	The invoking string (usually the command name, however may be an alias instead)	required
`cls`	`type`	The class to construct the context with. Defaults to `Context`.	`Context`

Returns:

Type	Description
`Context`	The constructed Context.

Module ¶

Represents a module.

A module houses a set of commands and events, and can be used to modularise your bot, and organise commands and their respective code into multiple files and classes for ease of use, development, and maintenance.

Attributes:

Name	Type	Description
`bot`		The bot instance this module is mounted to.

list_events ¶

list_events() -> Generator[dict, None, None]

Lists all the @event listeners registered in this module.

This returns the functions themselves. You can get the event name via result.__nio_event__["name"].

setup ¶

__setup__()

Setup function called once by NioBot.mount_module(). Mounts every command discovered.

.. warning: If you override this function, you should ensure that you call super().setup() to ensure that commands are properly registered.

teardown ¶

__teardown__()

Teardown function called once by NioBot.unmount_module(). Removes any command that was mounted.

.. warning: If you override this function, you should ensure that you call super().teardown() to ensure that commands are properly unregistered.

command ¶

command(name: Optional[str] = None, **kwargs) -> Callable

Allows you to register commands later on, by loading modules.

This differs from NioBot.command() in that commands are not automatically added, you need to load them with bot.mount_module

Parameters:

Name	Type	Description	Default
`name`	`Optional[str]`	The name of the command. Defaults to function.name	`None`
`kwargs`		Any key-words to pass to Command	`{}`

Returns:

Type	Description
`Callable`

check ¶

check(
    function: Callable[
        [Context], Union[bool, Coroutine[None, None, bool]]
    ]
) -> Callable

Allows you to register checks in modules.

@niobot.command()
@niobot.check(my_check_func)
async def my_command(ctx: niobot.Context):
    pass

Parameters:

Name	Type	Description	Default
`function`	`Callable[[Context], Union[bool, Coroutine[None, None, bool]]]`	The function to register as a check	required

Returns:

Type	Description
`Callable`	The decorated function.

event ¶

event(name: Optional[Union[str, Event]] = None) -> Callable

Allows you to register event listeners in modules.

Parameters:

Name	Type	Description	Default
`name`	`Optional[Union[str, Event]]`	the name of the event (no `on_` prefix)	`None`

Returns:

Type	Description
`Callable`

Commands¶

Argument ¶

internal_parser staticmethod ¶

Command ¶

display_usage property ¶

autodetect_args staticmethod ¶

__eq__ ¶

can_run async ¶

invoke async ¶

construct_context ¶

Module ¶

list_events ¶

__setup__ ¶

__teardown__ ¶

command ¶

check ¶

event ¶

internal_parser `staticmethod` ¶

display_usage `property` ¶

autodetect_args `staticmethod` ¶

eq ¶

can_run `async` ¶

invoke `async` ¶

setup ¶

teardown ¶