core.host

class immp.core.host.HostGetter(cls)

Bases: object

Filter property used to return a subset of objects by type.

class immp.core.host.Host

Bases: object

Main class responsible for starting, stopping, and interacting with plugs.

To run as the main coroutine for an application, use run() in conjunction with AbstractEventLoop.run_until_complete(). To stop a running host in an async context, await quit().

For finer control, you can call open(), process() and close() explicitly.

plugs

Collection of all registered plug instances, keyed by name.

Type:

(str, .Plug) dict

channels

Collection of all registered channels, keyed by name.

Type:

(str, .Channel) dict

groups

Collection of all registered group, keyed by name.

Type:

(str, .Group) dict

hooks

Collection of all registered hooks, keyed by name.

Type:

(str, .Hook) dict

plain_hooks

As above, but excluding resources.

Type:

(str, .Hook) dict

resources

Collection of all registered resource hooks, keyed by class.

Type:

(class, .ResourceHook) dict

priority

Mapping from hook names to their configured ordering. Unordered (lowest priority) hooks are not present.

Type:

(str, int) dict

running

Whether messages from plugs are being processed by the host.

Type:

bool

started

Timestamp when the host instance began listening for messages.

Type:

datetime.datetime

ordered_hooks()

Sort all registered hooks by priority.

Returns:

Hooks grouped by their relative order – one set for each ascending priority, followed by unordered hooks at the end.

Return type:

(.Hook set) list

add_plug(plug, enabled=True)

Register a plug to the host.

If the host is already running, use join_plug() instead, which will start the plug and begin processing messages straight away.

Parameters:

• plug (.Plug) – Existing plug instance to add.

• enabled (bool) – True to connect this plug at startup.

Returns:

Name used to reference this plug.

Return type:

str

remove_plug(name)

Unregister an existing plug.

Warning

This will not notify any hooks with a reference to this plug, nor will it attempt to remove it from their state.

Parameters:

name (str) – Name of a previously registered plug instance to remove.

Returns:

Removed plug instance.

Return type:

.Plug

add_channel(name, channel)

Register a channel to the host. The channel’s plug must be registered first.

Parameters:

• name (str) – Unique identifier for this channel to be referenced by plugs and hooks.

• channel (.Channel) – Existing channel instance to add.

remove_channel(name)

Unregister an existing channel.

Parameters:

name (str) – Name of a previously registered channel instance to remove.

add_group(group)

Register a group to the host.

Parameters:

group (.Group) – Existing group instance to add.

Returns:

Name used to reference this group.

Return type:

str

remove_group(name)

Unregister an existing group.

Warning

This will not notify any hooks with a reference to this group, nor will it attempt to remove it from their state.

Parameters:

name (str) – Name of a previously registered group instance to remove.

Returns:

Removed group instance.

Return type:

.Group

add_hook(hook, enabled=True, priority=None)

Register a hook to the host.

Parameters:

• hook (.Hook) – Existing hook instance to add.

• enabled (bool) – True to connect this plug at startup.

• priority (int) – Optional ordering constraint, applied to send and receive events. Hooks registered with a priority will be processed in ascending priority order, followed by those without prioritisation. Where multiple hooks share a priority value, events may be processed in parallel (e.g. on-receive is dispatched to all hooks simultaneously).

Returns:

Name used to reference this hook.

Return type:

str

prioritise_hook(name, priority)

Re-prioritise an existing hook.

Parameters:

• name (str) – Name of a previously registered hook instance to prioritise.

• priority (int) – Optional ordering constraint – see add_hook().

remove_hook(name)

Unregister an existing hook.

Warning

This will not notify any dependent hooks with a reference to this hook, nor will it attempt to remove it from their state.

Parameters:

name (str) – Name of a previously registered hook instance to remove.

Returns:

Removed hook instance.

Return type:

.Hook

loaded()

Trigger the on-load event for all plugs and hooks.

async open()

Connect all open plugs and start all hooks.

async close()

Disconnect all open plugs and stop all hooks.

async channel_migrate(old, new)

Issue a migration call to all hooks.

Parameters:

• old (.Channel) – Existing channel with local data.

• new (.Channel) – Target replacement channel to migrate data to.

Returns:

Names of hooks that migrated any data for the requested channel.

Return type:

str list

config_change(source)

Event handler called from a configurable when its config changes, dispatched to all hooks.

Parameters:

source (.Configurable) – Source plug or hook that triggered the event.

async process()

Retrieve messages from plugs, and distribute them to hooks.

async run()

Main entry point for running as a full application. Opens all plugs and hooks, blocks (when awaited) for the duration of process(), and closes openables during shutdown.

async quit()

Request the running host to stop processing. This only works if started via run().