commands

The commands module offers functions and types for adding new Command instances to mudpuppy. Typically these are called "slash commands" since the default command prefix is a / character.

Commands are an alternative to mudpuppy_core.Alias instances and are helpful if you want to do more complex argument parsing.

type CommandCallable = Callable[[int, argparse.Namespace], Awaitable[NoneType]]

An async function that is called when input sent to a MUD matches the command prefix and name of a command. Typically you will assign a CommandCallable to the handler property of a Command.

The handler is called with:

  • the int session ID of the session that received the input.
  • an argparse.Namespace with parsed arguments.
class Command:

An instance of a Mudpuppy "slash command".

See add_command().

Command( name: str, session: int, handler: CommandCallable, description: Optional[str] = None, aliases: Optional[list[str]] = None)

Create an instance of a Command that is run for /$NAME.

  • name - The name of the command. This is what the user will type to trigger the command. E.g. /$NAME
  • session - The session ID that the command should be associated with using add_command().`
  • handler - a CommandCallable to invoke when the command is run.
  • description - An optional description of the command that can be shown in a command list.
  • aliases - An optional list of other names the command should respond to in addition to name.
parser: argparse.ArgumentParser

An argparse.ArgumentParser that is used to parse arguments for this command.

It is created with exit_on_error=False and add_help=False to allow for custom error handling and help display.

def display_help(self, sesh_id: int):

Called when the user requests help for this command.

@staticmethod
def on_error(message):

Called by the arg parser when an error occurs

async def invoke(self, sesh_id: int, args: str):

Invoke the command for the provided sesh_id by parsing args with the Command's parser.

def add_command(sesh_id: int, command: Command):

Register the given Command as usable by the given sesh_id.

def all_commands(sesh_id: int) -> list[Command]:

Returns a list of all Commands that have been registered for the given sesh_id with add_command().