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