Magic Commands

class cactusbot.commands.command.Command(api=None)

Parent class to all magic commands.

Function definitions may use annotations to specify information about the arguments.

Using a string signifies a required regular expression to match. (If no groups are specified, the entire match is returned. If one group is specified, it is returned as a string. Otherwise, the tuple of groups is returned.)

Special shortcuts, beginning with a ?, are taken from a built-in list.

Shortcut	Regular Expression
?command	!?([\w-]{1,32})

Using the False annotation on *args signifies that no arguments are required to successfully execute the command.

An asynchronous function may be used as a validation annotation, as well. The function is passed the command argument. If an exception is not raised, the return value of the function is passed to the command. Otherwise, an error message is returned.

Keyword-only arguments should be annotated with the requested metadata.

Value	Description
username	The username of the message sender.
channel	The name of the channel which the message was sent in.
packet	The entire MessagePacket.

The COMMAND attribute is required, and should be set to the command name string.

Parameters:api (CactusAPI or None) – Instance of CactusAPI. Must be provided to the top-level magic Command.

Examples

>>> class Test(Command):
...
...     COMMAND = "test"
...
...     @Command.command()
...     async def add(self, command: "?command", *response):
...         return "Added !{command} with response {response}.".format(
...             command=command, response=' '.join(response))
...
...     @Command.command(hidden=True)
...     async def highfive(self, *, recipient: "username"):
...         return "Have a highfive, {recipient}!".format(
...             recipient=recipient)
...
...     @Command.command()
...     async def potato(self, *users: False):
...
...         if not users:
...             return "Have a potato!"
...
...         return "Have a potato, {users}!".format(users=', '.join(users))

classmethod command(name=None, **meta)

Accept arguments for command decorator.

Parameters:

• name (str or None, default None) – The name of the command. If None, the function name is used.
• hidden (bool) – Whether or not to hide the command from help messages.
• role (str or int, default 1) – The minimum role required to run the command. String capitalization is ignored.
• **meta –

  Custom meta filters. Any keyword arguments are valid.

  Number	String
  5	Owner
  4	Moderator
  2	Subscriber
  1	User
  0	Banned

Returns:

Decorator command.

Return type:

function

Examples

>>> @Command.command()
... async def hello():
...     return "Hello, world."

>>> @Command.command(name="return")
... async def return_():
...     return "Achievement Get: Return to Sender"

>>> @Command.command(hidden=True)
... async def secret():
...     return "Wow, you found a secret!"

>>> @Command.command(role="moderator")
... async def secure():
...     return "Moderator-only things have happened."

commands(**meta)

Return commands belonging to the parent class.

Parameters:**meta – Attributes to filter by. Returns:Commands which match the meta attributes. Keys are names, values are methods. Return type:dict

Examples

>>> @Command.command()
... class Test(Command):
...
...     @Command.command()
...     async def simple(self):
...         return "Simple response."
...
...     @Command.command(hidden=True)
...     async def secret(self):
...         return "#secrets"
...
>>> Test.commands(hidden=False).keys()
dict_keys(['simple'])