Commands

Commands

Ludolph commands are just plugin methods decorated with the @command decorator. There are also other decorators useful for quickly creating new commands.

from ludolph.command import CommandError, command, parameter_required

@command

Syntax:

@command(stream_output=False, reply_output=True, user_required=True, admin_required=False, room_user_required=False, room_admin_required=False)

Example:

@command                             # The decorator (required)
def my_command(self, msg):           # Every method receives the incoming message object as the first positional argument
    """My command documentation."""  # The docstring is used as command documentation
    return 'This is my command'      # The command should return a string which will be send as a reply to the original message

Note: The command should not start with an underscore and underscores in method names are transformed to hyphens to generate the command name.

By default the @command decorator checks if the user has a user permission, i.e. the callers JID is set in users configuration variable. To enable other permission checks you can use a combination of following @command parameters

• user_required
• admin_required
• room_user_required
• room_admin_required

@command(admin_required=True)       # Check is user has admin permission
def my_admin_command(self, msg):
    pass

@parameter_required(n)

Ensure that the command receives n positional arguments. When using @parameter_required(0) your command will receive unlimited number of positional arguments - it is always used with *args and useful for situations when you want to check the parameters inside the command itself.

Note: To use optional keyword parameters you don't have to use the @parameter_required() decorator.

@command
@parameter_required(2)                  # The command must be run with 2 parameters, otherwise an error message is sent to the user
def my_command(self, msg, arg1, arg2):
    ...

@command
@parameter_required(0)                  # The command accepts any number of arguments
def my_command(self, msg, *args):
    if len(args) > 1:
        ...

@admin_required [DEPRECATED]

The command will be accessible only by admin users. Note: This decorator is deprecated. Use the admin_required parameter in the @command decorator instead.

@command
@admin_required                  # Non-admin users will receive an error message
def my_command(self, msg):
    ...

Exceptions

CommandError

You can raise the CommandError exception to send a standard error message to the user.

@command
def my_command(self, msg):
    user = self.xmpp.get_jid(msg)   # Get the request user

    if user != 'user@example.com':
        raise CommandError('Permission denied')
    ...