hook.sync¶

class immp.hook.sync.SyncBackRef(**kwargs: Any)¶

Bases: Model

One of a set of references, each pointing to a representation of a source message.

key¶

Shared ID for each message in the same set.

Type:: str

network¶

Network identifier of the plug for this message.

Type:: str

channel¶

Origin channel of the referenced message.

Type:: str

message¶

Message ID as generated by the plug.

Type:: str

class Meta¶: Bases: object

async classmethod map_from_sent(sent)¶

Take a Receipt and attempt to resolve it to a key from a previously synced reference, then defer to map_from_key() to make the mapping with the key.

Parameters:: sent (.Receipt) – Referenced message to lookup.
Returns:: Generated reference mapping.
Return type:: ((str, str), .SyncBackRef) dict

async classmethod map_from_key(key)¶

For a given key, fetch all messages references synced from the corresponding source, and group them by network and channel.

Parameters:: key (str) – Synced message identifier.
Returns:: Generated reference mapping.
Return type:: ((str, str), .SyncBackRef) dict

class immp.hook.sync.SyncRef(ids, *, key=None, source=None, origin=None)¶

Bases: object

Representation of a single synced message.

key¶

Unique synced message identifier, used by SyncPlug when yielding messages.

Type:: str

ids¶

Mapping from Channel to a list of echoed message IDs.

Type:: (.Channel, str) dict

revisions¶

Mapping from Channel to message ID to synced revisions of that message.

Type:: (.Channel, (str, set) dict) dict

source¶

Original copy of the source message, if we have it.

Type:: .Message

classmethod from_backref_map(key, mapped, host)¶

Take a mapping generated in SyncBackRef.map_from_key() and produce a local reference suitable for the memory cache.

Parameters:

key (str) – Synced message identifier.
mapped (((str, str), .SyncBackRef list) dict) – Generated reference mapping.
host (.Host) – Parent host instance, needed to resolve network IDs to plugs.

Returns:

Newly created reference.

Return type:

.SyncRef

revision(sent)¶

Log a new revision of a message.

Parameters:: sent (.Receipt) – Updated message relating to a previously synced message.
Returns:: True if this is an edit (i.e. we’ve already seen a base revision for this message) and needs syncing to other channels.
Return type:: bool

class immp.hook.sync.SyncCache(hook)¶

Bases: object

Synced message cache manager, using both in-memory and database-based caches.

This class has dict-like access, using either Receipt objects or SyncPlug message IDs that map to SyncRef keys.

async add(ref, back=False)¶

Add a SyncRef to the cache. This will also commit a new SyncBackRef to the database if configured.

Parameters:

ref (.SyncRef) – Newly synced message to store.
back (bool) – True if sourced from a SyncBackRef, and therefore doesn’t need committing back to the database.

Returns:

The same ref, useful for shorthand add-then-return.

Return type:

.SyncRef

class immp.hook.sync.SyncPlug(name, hook, host)¶

Bases: Plug

Virtual plug that allows sending external messages to a synced conversation.

schema = None¶

classmethod any_sync(host, channel)¶

Produce a synced channel for the given source, searching across all SyncPlug instances running on the host.

Parameters:

host (.Host) – Controlling host instance.
channel (.Channel) – Original channel to lookup.

Returns:

Sync channel containing the given channel as a source, or None if not synced.

Return type:

.Channel

sync_for(channel)¶

Produce a synced channel for the given source.

Parameters:: channel (.Channel) – Original channel to lookup.
Returns:: Sync channel containing the given channel as a source, or None if not synced.
Return type:: .Channel

in_sync(channel)¶

Retrieve the list of member channels for a given sync channel.

Parameters:: channel (.Channel) – Virtual channel belonging to this sync instance.
Returns:: Channels participating in this sync.
Return type:: .Channel list

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

class immp.hook.sync.SyncHook(name, config, host)¶

Bases: _SyncHookBase

Hook to propagate messages between two or more channels.

plug¶

Virtual plug for this sync, if configured.

Type:: .SyncPlug

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

async send(label, msg, origin=None, ref=None, update=False)¶

Send a message to all channels in this synced group.

Parameters:

label (str) – Bridge that defines the underlying synced channels to send to.
msg (.Message) – External message to push. This should be the source copy when syncing a message from another channel.
origin (.Receipt) – Raw message that triggered this sync; if set and part of the sync, it will be skipped (used to avoid retransmitting a message we just received). This should be the plug-native copy of a message when syncing from another channel.
ref (.SyncRef) – Existing sync reference, if message has been partially synced.
update (bool) – True to force resending an updated message to all synced channels.

async on_receive(sent, source, primary)¶

Handle an incoming message received by any plug.

Parameters:

sent (.SentMessage) – Raw message received from another plug.
source (.Message) – Original message data used to generate the raw message, if sent via the plug (e.g. from another hook), equivalent to msg if the source is otherwise unknown.
primary (bool) – False for supplementary messages if the source message required multiple raw messages in order to represent it (e.g. messages with multiple attachments where the underlying network doesn’t support it), otherwise True.

class immp.hook.sync.ForwardHook(name, config, host, virtual=False)¶

Bases: _SyncHookBase

Hook to propagate messages from a source channel to one or more destination channels.

async send(msg, channels)¶

Send a message to all channels in this forwarding group.

Parameters:

msg (.Message) – External message to push.
channels (.Channel list) – Set of target channels to forward the message to.

async on_receive(sent, source, primary)¶

Handle an incoming message received by any plug.

Parameters:

sent (.SentMessage) – Raw message received from another plug.
source (.Message) – Original message data used to generate the raw message, if sent via the plug (e.g. from another hook), equivalent to msg if the source is otherwise unknown.
primary (bool) – False for supplementary messages if the source message required multiple raw messages in order to represent it (e.g. messages with multiple attachments where the underlying network doesn’t support it), otherwise True.