core.hook

class immp.core.hook.Hook(name, config, host, virtual=False)

Bases: immp.core.util.Configurable, immp.core.util.Openable

Base of all hook classes, performs any form of processing on messages from all connected plugs, via the provided host instance.

Instantiation may raise ConfigError if the provided configuration is invalid.

virtual

boolTrue if managed by another component (e.g. a hook that exposes plug functionality).

start()

Perform any setup tasks.

stop()

Perform any teardown tasks.

on_load()

Perform any additional one-time setup that requires other plugs or hooks to be loaded.

channel_migrate(old, new)

Move any private data between channels on admin request. This is intended to cover data keyed by channel sources and plug network identifiers.

Parameters
  • old (Channel) – Existing channel with local data.
  • new (Channel) – Target replacement channel to migrate data to.
Returns

True if any data was migrated for the requested channel.

Return type

bool

before_send(channel, msg)

Modify an outgoing message before it’s pushed to the network. The (channel, msg) pair must be returned, so hooks may modify in-place or return a different pair. This method is called for each hook, one after another. If channel is modified, the sending will restart on the new channel, meaning this method will be called again for all hooks.

Hooks may also suppress a message (e.g. if their actions caused it, but it bears no value to the network) by returning None.

Parameters
  • channel (Channel) – Original source of this message.
  • msg (Message) – Raw message received from another plug.
Returns

The augmented or replacement pair, or None to suppress this message.

Return type

(Channel, Message) tuple

before_receive(sent, source, primary)

Modify an incoming message before it’s pushed to other hooks. The sent object must be returned, so hooks may modify in-place or return a different object. This method is called for each hook, one after another, so any time-consuming tasks should be deferred to process() (which is run for all hooks in parallel).

Hooks may also suppress a message (e.g. if their actions caused it, but it bears no value to the rest of the system) by returning None.

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.
Returns

The augmented or replacement message, or None to suppress this message.

Return type

SentMessage

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

Handle a configuration change from another plug or hook.

Parameters
source (Configurable) – Source plug or hook that triggered the event.
class immp.core.hook.ResourceHook(name, config, host, virtual=False)

Bases: immp.core.hook.Hook

Variant of hooks that globally provide access to some resource.

Only one of each class may be loaded, which happens before regular hooks, and such hooks are keyed by their class rather than a name, allowing for easier lookups.