core.plug¶

class immp.core.plug.Plug(name, config, host, virtual=False)¶

Bases: Configurable, Openable

Base of all plug classes, handles communication with an external network by converting outside data into standardised message objects, and pushing new messages into the network.

Instantiation may raise ConfigError if the provided configuration is invalid.

name¶

User-provided, unique name of the plug, used for config references.

Type:: str

config¶

Reference to the user-provided configuration.

Type:: dict

host¶

Controlling host instance, providing access to plugs.

Type:: .Host

virtual¶

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

Type:: bool

network_name¶

Readable name of the underlying network, for use when displaying info about this plug.

Type:: str

network_id¶

Unique and stable identifier for this plug.

This should usually vary by the account or keys being used to connect, but persistent with later connections. If a network provides multiple distinct spaces, this should also vary by space.

Type:: str

on_load()¶: Perform any additional one-time setup that requires other plugs or hooks to be loaded.

on_ready()¶: Perform any post-startup tasks once all hooks and plugs are ready.

async user_from_id(id_)¶

Retrieve a User based on the underlying network’s identifier.

Parameters:: id (str) – Network identifier of the user.
Returns:: Corresponding user instance.
Return type:: .User

async user_from_username(username)¶

Retrieve a User based on the underlying network’s username.

Parameters:: username (str) – Network username of the user.
Returns:: Corresponding user instance.
Return type:: .User

async user_is_system(user)¶

Check if a given user is automated by the plug (for example a bot user from which the plug operates). Hooks may exclude system users from certain operations.

Returns:: True if the user relates to the plug itself.
Return type:: bool

async public_channels()¶

Retrieve all shared channels known to this plug, either public or otherwise accessible. May return None if the network doesn’t support channel discovery.

Returns:: All available non-private channels.
Return type:: .Channel list

async private_channels()¶

Retrieve all private (one-to-one) channels known to this plug. May return None if the network doesn’t support channel discovery.

Returns:: All available private channels.
Return type:: .Channel list

async channel_for_user(user)¶

Retrieve a Channel representing a private (one-to-one) conversation between a given user and the service. Returns None if the user does not have a private channel.

Parameters:: user (.User) – Requested user instance.
Returns:: Private channel for this user.
Return type:: .Channel

async channel_is_private(channel)¶

Test if a given channel represents a private (one-to-one) conversation between a given user and the service. May return None if the network doesn’t have a notion of public/shared and private channels.

Parameters:: channel (.Channel) – Requested channel instance.
Returns:: True if the channel is private.
Return type:: bool

async channel_title(channel)¶

Retrieve the friendly name of this channel, as used in the underlying network. May return None if the service doesn’t have a notion of titles.

Returns:: Display name for the channel.
Return type:: str

async channel_link(channel)¶

Return a URL that acts as a direct link to the given channel. This is not a join link, rather one that opens a conversation in the client (it may e.g. use a custom protocol).

Parameters:: channel (.Channel) – Requested channel instance.
Returns:: Internal deep link to this channel.
Return type:: str

async channel_rename(channel, title)¶

Update the friendly name of this conversation.

Parameters:

channel (.Channel) – Requested channel instance.
title (str) – New display name for the channel.

async channel_members(channel)¶

Retrieve a User list representing all members of the given channel. May return None if the plug doesn’t recognise the channel, or is unable to query members.

Parameters:: channel (.Channel) – Requested channel instance.
Returns:: Members present in the channel.
Return type:: .User list

async channel_admins(channel)¶

Retrieve a User list representing members of the given channel with the ability to manage the channel or its members. May return None if the plug doesn’t recognise the channel, is unable to query members, or has no concept of admins.

Parameters:: channel (.Channel) – Requested channel instance.
Returns:: Members with admin privileges present in the channel.
Return type:: .User list

async channel_invite_multi(channel, users)¶

Add multiple users to the channel’s list of members.

By default, calls channel_invite() for each channel-user pair, but can be overridden in order to optimise any necessary work.

Parameters:

channel (.Channel) – Requested channel instance.
users (.User list) – New users to invite.

async channel_invite(channel, user)¶

Add the given user to the channel’s list of members.

Parameters:

channel (.Channel) – Requested channel instance.
user (.User) – New user to invite.

async channel_remove_multi(channel, users)¶

Remove multiple users from the channel’s list of members.

By default, calls channel_remove() for each channel-user pair, but can be overridden in order to optimise any necessary work.

Parameters:

channel (.Channel) – Requested channel instance.
user (.User) – Existing users to kick.

async channel_remove(channel, user)¶

Remove the given user from the channel’s list of members.

Parameters:

channel (.Channel) – Requested channel instance.
user (.User) – Existing user to kick.

async channel_link_create(channel, shared=True)¶

Create a URL that can be used by non-members to join the given channel. To link existing participants to the channel without invite authorisation, see channel_link().

Parameters:

channel (.Channel) – Requested channel instance.
shared (bool) –
True (default) for a common, unlimited-use, non-expiring link (subject to any limitations from the underlying network); False for a private, single-use link.

Networks may only support one of these two modes of link creation; if None is returned, but the caller can make do with the other type, they may retry the call and flip this option.

Returns:

Shareable invite link, or None if one couldn’t be created.

Return type:

str

async channel_link_revoke(channel, link=None)¶

Revoke an invite link, or otherwise prevent its use in the future.

Parameters:

channel (.Channel) – Requested channel instance.
link (str) – Existing invite link to revoke. This should be provided when known; if None, the plug will revoke the default invite link, if such a link exists for the channel in the underlying network.

async channel_history(channel, before=None)¶

Retrieve the most recent messages sent or received in the given channel. May return an empty list if the plug is unable to query history.

Parameters:

channel (.Channel) – Requested channel instance.
before (.Receipt) – Starting point message, or None to fetch the most recent.

Returns:

Messages from the channel, oldest first.

Return type:

.Receipt list

async get_message(receipt)¶

Lookup a Receipt and fetch the corresponding SentMessage.

Parameters:: receipt (.Receipt) – Existing message reference to retrieve.
Returns:: Full message.
Return type:: .SentMessage

async resolve_message(msg)¶

Lookup a Receipt if no Message data is present, and fetch the corresponding SentMessage.

Parameters:: msg (.Message | .Receipt) – Existing message reference to retrieve.
Returns:: Full message.
Return type:: .SentMessage

queue(sent)¶

Add a new message to the queue, picked up from get() by default.

Parameters:: sent (.SentMessage) – Message received and processed by the plug.

async stream()¶

Wrapper method to receive messages from the network. Plugs should implement their own retrieval of messages, scheduled as a background task or managed by another async client, then call queue() for each received message to have it yielded here.

This method is called by the PlugStream, in parallel with other plugs to produce a single stream of messages across all sources.

Yields:: (.SentMessage, .Message, bool) tuple – Messages received and processed by the plug, paired with a source message if one exists (from a call to send()).

Warning

Because the message buffer is backed by an asyncio.Queue, only one generator from this method should be used at once – each message will only be retrieved from the queue once, by the first instance that asks for it.

async send(channel, msg)¶

Wrapper method to send a message to the network. Plugs should implement put() to convert the framework message into a native representation and submit it.

Parameters:

channel (.Channel) – Target channel for the new message.
msg (.Message) – Original message received from another channel or plug.

Returns:

References to new messages sent to the plug.

Return type:

.Receipt list

async put(channel, msg)¶

Take a Message object, and push it to the underlying network.

Because some plugs may not support combinations of message components (such as text and an accompanying image), this method may send more than one physical message.

Parameters:

channel (.Channel) – Target channel for the new message.
msg (.Message) – Original message received from another channel or plug.

Returns:

References to new messages sent to the plug.

Return type:

.Receipt list

async delete(sent)¶

Request deletion of this message, if supported by the network.

Parameters:: sent (.SentMessage) – Existing message to be removed.