hook.command#

exception immp.hook.command.BadUsage#

Bases: HookError

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

class immp.hook.command.CommandParser(value)#

Bases: 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(value)#

Bases: 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.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)#

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

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().

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, scope=CommandScope.anywhere, 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#

Callback method from a hook to process the command usage.

Type:: method

parser#

Parse mode for the command arguments.

Type:: .CommandParser

scope#

Accessibility of this command for the different channel types.

Type:: .CommandScope

test#

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

Type:: method

sync_aware#

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

Type:: bool

fixed#

Number of fixed arguments the underlying method requires.

Type:: int

doc#

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

Type:: str

spec#

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

Type:: str

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.
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, scope=CommandScope.anywhere, test=None, sync_aware=False, fixed_args=())#

Bases: BaseCommand

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

name#

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

Type:: str

fixed_args#

Additional arguments to pass to the underlying method.

Type:: tuple

complete(name, *args)#

Fully-qualify a 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:

Fully-qualified instance of this base command.

Return type:

.FullCommand

immp.hook.command.command(name=None, parser=CommandParser.spaces, scope=CommandScope.anywhere, 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.
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: Hook

Generic command handler for other hooks.

Hooks should wrap command handler methods with the command() decorator, which will be picked up by any instances of this class configured to include that hook.

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

async 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

async on_receive(sent, source, primary)#

Handle an incoming message received by any plug.

Parameters:

sent (.SentMessage) – Raw message received from another plug.
source (.Message) – Original message data used to generate the raw message, if sent via the plug (e.g. from another hook), equivalent to msg if the source is otherwise unknown.
primary (bool) – False for supplementary messages if the source message required multiple raw messages in order to represent it (e.g. messages with multiple attachments where the underlying network doesn’t support it), otherwise True.