core.plug

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

Bases: immp.core.util.Configurable, immp.core.util.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

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

config

dict – Reference to the user-provided configuration.

host

.Host – Controlling host instance, providing access to plugs.

virtual

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

network_name

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

network_id

str – 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.

start()

Start a connection to the external network.

If using an event-driven framework that yields and runs in the background, you should use a signal of some form (e.g. asyncio.Condition) to block this method until the underlying network is ready for use.

stop()

Terminate the external network connection.

Like with start(), this should block if needed, such that this method ends when the plug can be started again.

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

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

Returns
Internal deep link to this channel.
Return type
str
channel_rename(channel, title)

Update the friendly name of this conversation.

Parameters
title (str) – New display name for the channel.
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
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.
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.
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

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

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

IDs of new messages sent to the plug.

Return type

list

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

IDs of new messages sent to the plug.

Return type

list

delete(sent)

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

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

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