hook.sync

class immp.hook.sync.SyncBackRef(*args, **kwargs)

Bases: immp.hook.database.BaseModel

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

key

str – Shared ID for each message in the same set.

network

str – Network identifier of the plug for this message.

channel

str – Origin channel of the referenced message.

message

str – Message ID as generated by the plug.

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

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

ids

(.Channel, str) dict – Mapping from Channel to a list of echoed message IDs.

revisions

(.Channel, (str, set) dict) dict – Mapping from Channel to message ID to synced revisions of that message.

source

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

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.

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: immp.core.plug.Plug

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

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
class immp.hook.sync.SyncHook(name, config, host)

Bases: immp.hook.sync._SyncHookBase

Hook to propagate messages between two or more channels.

plug

.SyncPlug – Virtual plug for this sync, if configured.

send(label, msg, origin=None)

Send a message to all channels in this sync.

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.
class immp.hook.sync.ForwardHook(name, config, host, virtual=False)

Bases: immp.hook.sync._SyncHookBase

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

send(channel, msg)

Send a message to all channels in this sync.

Parameters
  • channel (Channel) – Source channel that defines the underlying forwarding channels to send to.
  • msg (Message) – External message to push.