hook.command

exception immp.hook.command.BadUsage

Bases: immp.core.error.HookError

May be raised from within a command to indicate that the arguments were invalid.

class immp.hook.command.CommandParser

Bases: enum.Enum

Constants representing the method used to parse the argument text following a used command.

spaces

Split using str.split(), for simple inputs breaking on whitespace characters.

shlex

Split using shlex.split(), which allows quoting of multi-word arguments.

none

Don’t split the argument, just provide the rich message text as-is.

hybrid

Split as with spaces up to the number of accepted arguments, and return rich text in the last argument. If optional arguments are present, only the last will receive the rich text, or none of them if not filled in.

class immp.hook.command.CommandScope

Bases: enum.Enum

Constants representing the types of conversations a command is available in.

anywhere

All configured channels.

private

Only private channels, as configured per-plug.

shared

Only non-private channels, as configured per-channel.

class immp.hook.command.CommandRole

Bases: enum.Enum

Constants representing the types of users a command is available in.

anyone

All configured channels.

admin

Only authorised users in the command group.

class immp.hook.command.BoundCommand(hook, cmd)

Bases: object

Wrapper object returned when accessing a command via a Hook instance, similar to types.MethodType.

This object is callable, which invokes the command’s underlying method against the bound hook.

applicable(channel, user, private, admin)

Test the availability of the current command based on the scope and role.

Parameters
  • channel (Channel) – Source channel where the command will be executed.
  • user (User) – Author of the message to trigger the command.
  • private (bool) – Result of Channel.is_private().
  • admin (bool) – True if the author is defined as an admin of this CommandHook.
Returns

True if the command may be used.

Return type

bool

complete(name, *args)

Fully-qualify an underlying base command.

Parameters
  • name (str) – Command name, used to access the command when directly following the prefix.
  • args (tuple) – Additional arguments to pass to the underlying method.
Returns

Wrapper around the now-fully-qualified instance of the base command.

Return type

BoundCommand

class immp.hook.command.BaseCommand(fn, parser=<CommandParser.spaces: 0>, scope=<CommandScope.anywhere: 0>, role=<CommandRole.anyone: 0>, test=None, sync_aware=False)

Bases: object

Container of a command function. Use the command() decorator to wrap a class method and convert it into an instance of this class. Unless dynamic, command objects will be an instance of the FullCommand subclass.

Accessing an instance of this class via the attribute of a containing class will create a new BoundCommand allowing invocation of the method.

fn

method – Callback method from a hook to process the command usage.

parser

.CommandParser – Parse mode for the command arguments.

scope

.CommandScope – Accessibility of this command for the different channel types.

role

.CommandRole – Accessibility of this command for different users.

test

method – Additional predicate that can enable or disable a command based on hook state.

sync_aware

boolTrue if the hook is aware of synced channels provided by a SyncPlug.

fixed

int – Number of fixed arguments the underlying method requires.

doc

str – Help for the command, taken from the callback method’s docstring if present.

spec

str – Human-readable summary of the arguments required by the method.

parse(args)

Convert a string of multiple arguments into a list according to the chosen parse mode.

Parameters
args (RichText) – Trailing argument text from a message.
Returns
Parsed arguments.
Return type
(str or RichText) list
valid(*args)

Test the validity of the given arguments against the command’s underlying method. Raises ValueError if the arguments don’t match the signature.

Parameters
args (str list) – Parsed arguments.
complete(name, *args)

Fully-qualify a base command.

Parameters
  • name (str) – Command name, used to access the command when directly following the prefix.
  • fixed_args (tuple) – Additional arguments to pass to the underlying method.
Returns

Fully-qualified instance of this base command.

Return type

FullCommand

class immp.hook.command.FullCommand(name, fn, parser=<CommandParser.spaces: 0>, scope=<CommandScope.anywhere: 0>, role=<CommandRole.anyone: 0>, test=None, sync_aware=False, fixed_args=())

Bases: immp.hook.command.BaseCommand

Fully-qualified and named command, an extension of BaseCommand to make it callable.

name

str – Command name, used to access the command when directly following the prefix.

fixed_args

tuple – Additional arguments to pass to the underlying method.

immp.hook.command.command(name=None, parser=<CommandParser.spaces: 0>, scope=<CommandScope.anywhere: 0>, role=<CommandRole.anyone: 0>, test=None, sync_aware=False)

Decorator: mark up a hook method as a command.

This doesn’t return the original function, rather a BaseCommand object.

The method’s accepted arguments must start with self, and must accept one called msg, which will be set to the Message instance that triggered this command.

A dynamic command is an unnamed instance that can be used to create multiple commands with the same underlying method call. These commands are not collected automatically – the parent hook must implement DynamicCommands.

Parameters
  • name (str) – Command name, used to access the command when directly following the prefix.
  • parser (CommandParser) – Parse mode for the command arguments.
  • scope (CommandScope) – Accessibility of this command for the different channel types.
  • role (CommandRole) – Accessibility of this command for different users.
  • test (method) – Additional predicate that can enable or disable a command based on hook state.
  • sync_aware (bool) – True if the hook is aware of synced channels provided by a SyncPlug. In this case, the command handler will receive the native channel rather than the virtual sync channel. See SyncPlug.sync_for() for resolving this to a virtual channel.
class immp.hook.command.DynamicCommands

Bases: object

Interface for commands generated at runtime. Typically combined with additional arguments in a command method’s signature.

commands()

Provide additional commands dependent on state or config. Dynamic commands must be filled in using BaseCommand.complete() to provide their name and any fixed arguments.

Returns
Set of available commands.
Return type
BoundCommand set
class immp.hook.command.CommandHook(name, config, host)

Bases: immp.core.hook.Hook

Generic command handler for other hooks.

discover(hook)

Inspect a Hook instance, scanning its attributes for commands.

Returns
Commands provided by this hook, keyed by name.
Return type
(str, BoundCommand) dict
commands(channel, user)

Retrieve all commands, and filter against the mappings.

Parameters
  • channel (Channel) – Source channel where the command will be executed.
  • user (User) – Author of the message to trigger the command.
Returns

Commands provided by all hooks, in this channel for this user, keyed by name.

Return type

(str, BoundCommand) dict