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.

Example
@bot.group("math")
async def math(ctx: Context) -> None:
    await ctx.send_help()

@math.command()
async def add(ctx: Context, a: int, b: int) -> None:
    await ctx.reply(f"{a + b}")

@math.command("sub")
async def subtract(ctx: Context, a: int, b: int) -> None:
    await ctx.reply(f"{a - b}")
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
69
70
71
72
73
74
75
76
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.

    ## Example

    ```python
    @bot.group("math")
    async def math(ctx: Context) -> None:
        await ctx.send_help()

    @math.command()
    async def add(ctx: Context, a: int, b: int) -> None:
        await ctx.reply(f"{a + b}")

    @math.command("sub")
    async def subtract(ctx: Context, a: int, b: int) -> None:
        await ctx.reply(f"{a - b}")
    ```
    """

    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 
78
79
80
81
82
83
84
85
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 
87
88
89
90
91
92
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)