Skip to content

Group

A Group is a command that can contain sub-commands, enabling hierarchical command structures. Invoke a sub-command by sending <prefix><group> <subcommand>.

from matrix import Bot, Context

bot = Bot(prefix="!")

@bot.group("admin")
async def admin(ctx: Context):
    await ctx.reply("Use a subcommand: kick, ban")

@admin.command("kick")
async def kick(ctx: Context, user: str):
    await ctx.reply(f"Kicking {user}")

matrix.group.Group 

Group(
    callback,
    *,
    name=None,
    description=None,
    prefix=None,
    parent=None,
    usage=None,
    cooldown=None
)

Bases: Command

Source code in matrix/group.py 
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
def __init__(
    self,
    callback: Callback,
    *,
    name: Optional[str] = None,
    description: Optional[str] = None,
    prefix: Optional[str] = None,
    parent: Optional[str] = None,
    usage: Optional[str] = None,
    cooldown: Optional[tuple[int, float]] = None,
):
    self.commands: Dict[str, Command] = {}

    super().__init__(
        callback,
        name=name,
        description=description,
        prefix=prefix,
        parent=parent,
        usage=usage,
        cooldown=cooldown,
    )

commands instance-attribute 

commands = {}

get_command 

get_command(cmd_name)
Source code in matrix/group.py 
43
44
45
46
def get_command(self, cmd_name: str) -> Command:
    if cmd := self.commands.get(cmd_name):
        return cmd
    raise CommandNotFoundError(cmd_name)

command 

command(name=None)

Decorator to register a coroutine function as a command handler.

The command name defaults to the function name unless explicitly provided.

:param name: The name of the command. If omitted, the function name is used. :type name: str, optional :raises TypeError: If the decorated function is not a coroutine. :raises ValueError: If a command with the same name is registered. :return: Decorator that registers the command handler. :rtype: Callback

Source code in matrix/group.py 
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
def command(self, name: Optional[str] = None) -> Callable[[Callback], Command]:
    """
    Decorator to register a coroutine function as a command handler.

    The command name defaults to the function name unless
    explicitly provided.

    :param name: The name of the command. If omitted, the function
                 name is used.
    :type name: str, optional
    :raises TypeError: If the decorated function is not a coroutine.
    :raises ValueError: If a command with the same name is registered.
    :return: Decorator that registers the command handler.
    :rtype: Callback
    """

    def wrapper(func: Callback) -> Command:
        cmd = Command(func, name=name, prefix=self.prefix, parent=self.name)
        return self.register_command(cmd)

    return wrapper

register_command 

register_command(cmd)
Source code in matrix/group.py 
70
71
72
73
74
75
76
77
def register_command(self, cmd: Command) -> Command:
    if cmd in self.commands:
        raise AlreadyRegisteredError(cmd)

    self.commands[cmd.name] = cmd
    logger.debug("command '%s' registered for group '%s'", cmd, self)

    return cmd

invoke async 

invoke(ctx)
Source code in matrix/group.py 
79
80
81
82
83
84
async def invoke(self, ctx: "Context") -> None:
    if ctx.args and (subcommand := ctx.args.pop(0)):
        ctx.subcommand = self.get_command(subcommand)
        await ctx.subcommand(ctx)
    else:
        await self.callback(ctx)