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

(str, .Plug) dict – Collection of all registered plug instances, keyed by name.

channels

(str, .Channel) dict – Collection of all registered channels, keyed by name.

groups

(str, .Group) dict – Collection of all registered group, keyed by name.

hooks

(str, .Hook) dict – Collection of all registered hooks, keyed by name.

plain_hooks

(str, .Hook) dict – As above, but excluding resources.

resources

(class, .ResourceHook) dict – Collection of all registered resource hooks, keyed by class.

priority

(str, int) dict – Mapping from hook names to their configured ordering. Unordered (lowest priority) hooks are not present.

running

bool – Whether messages from plugs are being processed by the host.

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.

open()

Connect all open plugs and start all hooks.

close()

Disconnect all open plugs and stop all hooks.

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

Retrieve messages from plugs, and distribute them to hooks.

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.

quit()

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