`slidge.contact`#

Everything related to 1 on 1 chats, and other legacy users’ details.

Package Contents#

Classes#

`LegacyContact`	This class centralizes actions in relation to a specific legacy contact.
`LegacyRoster`	Virtual roster of a gateway user, that allows to represent all

class slidge.contact.LegacyContact(session, legacy_id, jid_username)#

This class centralizes actions in relation to a specific legacy contact.

You shouldn’t create instances of contacts manually, but rather rely on LegacyRoster.by_legacy_id() to ensure that contact instances are singletons. The LegacyRoster instance of a session is accessible through the BaseSession.contacts attribute.

Typically, your plugin should have methods hook to the legacy events and call appropriate methods here to transmit the “legacy action” to the xmpp user. This should look like this:

Use carbon=True as a keyword arg for methods to represent an action FROM the user TO the contact, typically when the user uses an official client to do an action such as sending a message or marking as message as read. This will use XEP-0363 to impersonate the XMPP user in order.

Parameters:

session (slidge.core.session.BaseSession) –
legacy_id (slidge.util.types.LegacyUserIdType) –
jid_username (str) –

property name#: Friendly name of the contact, as it should appear in the user’s roster

property avatar_id: slidge.util.types.AvatarIdType | None#

The unique ID of this entity’s avatar.

Return type:: Optional[slidge.util.types.AvatarIdType]

property avatar: slidge.util.types.AvatarIdType | None#

This property can be used to set the avatar, but set_avatar() should be preferred because you can provide a unique ID for the avatar for efficient caching. Setting this is OKish in case the avatar type is a URL or a local path that can act as a legacy ID.

Python’s property is abused here to maintain backwards compatibility, but when getting it you actually get the avatar legacy ID.

Return type:: Optional[slidge.util.types.AvatarIdType]

RESOURCE: str = 'slidge'#: A full JID, including a resource part is required for chat states (and maybe other stuff) to work properly. This is the name of the resource the contacts will use.

legacy_id: slidge.util.types.LegacyUserIdType#

The legacy identifier of the Legacy Contact. By default, this is the JID Local Part of this XMPP Entity.

Controlling what values are valid and how they are translated from a JID Local Part is done in jid_username_to_legacy_id(). Reciprocally, in legacy_id_to_jid_username() the inverse transformation is defined.

get_msg_xmpp_id_up_to(horizon_xmpp_id)#

Return XMPP msg ids sent by this contact up to a given XMPP msg id.

Plugins have no reason to use this, but it is used by slidge core for legacy networks that need to mark all messages as read (most XMPP clients only send a read marker for the latest message).

This has side effects, if the horizon XMPP id is found, messages up to this horizon are not cleared, to avoid sending the same read mark twice.

Parameters:: horizon_xmpp_id (str) – The latest message
Returns:: A list of XMPP ids or None if horizon_xmpp_id was not found

async add_to_roster(force=False)#

Add this contact to the user roster using XEP-0356

Parameters:: force – add even if the contact was already added successfully

async accept_friend_request(text=None)#

Call this to signify that this Contact has accepted to be a friend of the user.

Parameters:: text (Optional[str]) – Optional message from the friend to the user

reject_friend_request(text=None)#

Call this to signify that this Contact has refused to be a contact of the user (or that they don’t want to be friends anymore)

Parameters:: text (Optional[str]) – Optional message from the non-friend to the user

async on_friend_request(text='')#

Called when receiving a “subscribe” presence, ie, “I would like to add you to my contacts/friends”, from the user to this contact.

In XMPP terms: “I would like to receive your presence updates”

This is only called if self.is_friend = False. If self.is_friend = True, slidge will automatically “accept the friend request”, ie, reply with a “subscribed” presence.

When called, a ‘friend request event’ should be sent to the legacy service, and when the contact responds, you should either call self.accept_subscription() or self.reject_subscription()

async on_friend_delete(text='')#

Called when receiving an “unsubscribed” presence, ie, “I would like to remove you to my contacts/friends” or “I refuse your friend request” from the user to this contact.

In XMPP terms: “You won’t receive my presence updates anymore (or you never have)”.

async on_friend_accept()#

Called when receiving a “subscribed” presence, ie, “I accept to be your/confirm that you are my friend” from the user to this contact.

In XMPP terms: “You will receive my presence updates”.

unsubscribe()#

(internal use by slidge)

Send an “unsubscribe”, “unsubscribed”, “unavailable” presence sequence from this contact to the user, ie, “this contact has removed you from their ‘friends’”.

async update_info()#

Fetch information about this contact from the legacy network

This is awaited on Contact instantiation, and should be overridden to update the nickname, avatar, vcard […] of this contact, by making “legacy API calls”.

To take advantage of the slidge avatar cache, you can check the .avatar property to retrieve the “legacy file ID” of the cached avatar. If there is no change, you should not call slidge.core.mixins.avatar.AvatarMixin.set_avatar() or attempt to modify the .avatar property.

async fetch_vcard()#: It the legacy network doesn’t like that you fetch too many profiles on startup, it’s also possible to fetch it here, which will be called when XMPP clients of the user request the vcard, if it hasn’t been fetched before :return:

async set_avatar(a, avatar_unique_id=None, blocking=False, cancel=True)#

Set an avatar for this entity

Parameters:

a (Optional[slidge.util.types.AvatarType]) –
avatar_unique_id (Optional[slidge.util.types.LegacyFileIdType]) –
blocking –
cancel –

Return type:

None

invite_to(muc, reason=None, password=None, **send_kwargs)#

Send an invitation to join a group (XEP-0249) from this XMPP Entity.

Parameters:

muc (slidge.group.LegacyMUC) – the muc the user is invited to
reason (Optional[str]) – a text explaining why the user should join this muc
password (Optional[str]) – maybe this will make sense later? not sure
send_kwargs – additional kwargs to be passed to _send() (internal use by slidge)

active(**kwargs)#: Send an “active” chat state (XEP-0085) from this XMPP Entity.

composing(**kwargs)#: Send a “composing” (ie “typing notification”) chat state (XEP-0085) from this XMPP Entity.

paused(**kwargs)#: Send a “paused” (ie “typing paused notification”) chat state (XEP-0085) from this XMPP Entity.

inactive(**kwargs)#: Send an “inactive” (ie “contact has not interacted with the chat session interface for an intermediate period of time”) chat state (XEP-0085) from this XMPP Entity.

gone(**kwargs)#: Send a “gone” (ie “contact has not interacted with the chat session interface, system, or device for a relatively long period of time”) chat state (XEP-0085) from this XMPP Entity.

send_text(body, legacy_msg_id=None, *, when=None, reply_to=None, thread=None, hints=None, carbon=False, archive_only=False, correction=False, correction_event_id=None, link_previews=None, **send_kwargs)#

Send a text message from this XMPP Entity.

Parameters:

body (str) – Content of the message
legacy_msg_id (Optional[slidge.util.types.LegacyMessageType]) – If you want to be able to transport read markers from the gateway user to the legacy network, specify this
when (Optional[datetime.datetime]) – when the message was sent, for a “delay” tag (XEP-0203)
reply_to (Optional[slidge.util.types.MessageReference]) – Quote another message (XEP-0461)
hints (Optional[Iterable[slidge.util.types.ProcessingHint]]) –
thread (Optional[slidge.util.types.LegacyThreadType]) –
carbon – (only used if called on a LegacyContact) Set this to True if this is actually a message sent to the LegacyContact by the User. Use this to synchronize outgoing history for legacy official apps.
correction – whether this message is a correction or not
correction_event_id (Optional[slidge.util.types.LegacyMessageType]) – in the case where an ID is associated with the legacy ‘correction event’, specify it here to use it on the XMPP side. If not specified, a random ID will be used.
link_previews (Optional[list[slidge.util.types.LinkPreview]]) – A little of sender (or server, or gateway)-generated previews of URLs linked in the body.
archive_only – (only in groups) Do not send this message to user, but store it in the archive. Meant to be used during MUC.backfill()

correct(legacy_msg_id, new_text, *, when=None, reply_to=None, thread=None, hints=None, carbon=False, archive_only=False, correction_event_id=None, link_previews=None, **send_kwargs)#

Modify a message that was previously sent by this XMPP Entity.

Uses last message correction (XEP-0308)

Parameters:

new_text (str) – New content of the message
legacy_msg_id (slidge.util.types.LegacyMessageType) – The legacy message ID of the message to correct
when (Optional[datetime.datetime]) – when the message was sent, for a “delay” tag (XEP-0203)
reply_to (Optional[slidge.util.types.MessageReference]) – Quote another message (XEP-0461)
hints (Optional[Iterable[slidge.util.types.ProcessingHint]]) –
thread (Optional[slidge.util.types.LegacyThreadType]) –
carbon – (only in 1:1) Reflect a message sent to this Contact by the user. Use this to synchronize outgoing history for legacy official apps.
archive_only – (only in groups) Do not send this message to user, but store it in the archive. Meant to be used during MUC.backfill()
correction_event_id (Optional[slidge.util.types.LegacyMessageType]) – in the case where an ID is associated with the legacy ‘correction event’, specify it here to use it on the XMPP side. If not specified, a random ID will be used.
link_previews (Optional[list[slidge.util.types.LinkPreview]]) – A little of sender (or server, or gateway)-generated previews of URLs linked in the body.

react(legacy_msg_id, emojis=(), thread=None, **kwargs)#

Send a reaction (XEP-0444) from this XMPP Entity.

Parameters:

legacy_msg_id (slidge.util.types.LegacyMessageType) – The message which the reaction refers to.
emojis (Iterable[str]) – An iterable of emojis used as reactions
thread (Optional[slidge.util.types.LegacyThreadType]) –

retract(legacy_msg_id, thread=None, **kwargs)#

Send a message retraction (XEP-0424) from this XMPP Entity.

Parameters:

legacy_msg_id (slidge.util.types.LegacyMessageType) – Legacy ID of the message to delete
thread (Optional[slidge.util.types.LegacyThreadType]) –

async send_file(file_path=None, legacy_msg_id=None, *, data_stream=None, data=None, file_url=None, file_name=None, content_type=None, reply_to=None, when=None, caption=None, legacy_file_id=None, thread=None, **kwargs)#

Send a single file from this XMPP Entity.

Parameters:

file_path (Optional[Union[pathlib.Path, str]]) – Path to the attachment
data_stream (Optional[IO[bytes]]) – Alternatively, a stream of bytes (such as a File object)
data (Optional[bytes]) – Alternatively, a bytes object
file_url (Optional[str]) – Alternatively, a URL
file_name (Optional[str]) – How the file should be named.
content_type (Optional[str]) – MIME type, inferred from filename if not given
legacy_msg_id (Optional[slidge.util.types.LegacyMessageType]) – If you want to be able to transport read markers from the gateway user to the legacy network, specify this
reply_to (Optional[slidge.util.types.MessageReference]) – Quote another message (XEP-0461)
when (Optional[datetime.datetime]) – when the file was sent, for a “delay” tag (XEP-0203)
caption (Optional[str]) – an optional text that is linked to the file
legacy_file_id (Optional[Union[str, int]]) – A unique identifier for the file on the legacy network. Plugins should try their best to provide it, to avoid duplicates.
thread (Optional[slidge.util.types.LegacyThreadType]) –

Return type:

tuple[Optional[str], list[slixmpp.Message]]

ack(legacy_msg_id, **kwargs)#

Send an “acknowledged” message marker (XEP-0333) from this XMPP Entity.

Parameters:: legacy_msg_id (slidge.util.types.LegacyMessageType) – The message this marker refers to

received(legacy_msg_id, **kwargs)#

Send a “received” message marker (XEP-0333) from this XMPP Entity. If called on a LegacyContact, also send a delivery receipt marker (XEP-0184).

Parameters:: legacy_msg_id (slidge.util.types.LegacyMessageType) – The message this marker refers to

displayed(legacy_msg_id, **kwargs)#

Send a “displayed” message marker (XEP-0333) from this XMPP Entity.

Parameters:: legacy_msg_id (slidge.util.types.LegacyMessageType) – The message this marker refers to

online(status=None, last_seen=None)#

Send an “online” presence from this contact to the user.

Parameters:

status (Optional[str]) – Arbitrary text, details of the status, eg: “Listening to Britney Spears”
last_seen (Optional[datetime.datetime]) – For XEP-0319

away(status=None, last_seen=None)#

Send an “away” presence from this contact to the user.

This is a global status, as opposed to LegacyContact.inactive() which concerns a specific conversation, ie a specific “chat window”

Parameters:

status (Optional[str]) – Arbitrary text, details of the status, eg: “Gone to fight capitalism”
last_seen (Optional[datetime.datetime]) – For XEP-0319

extended_away(status=None, last_seen=None)#

Send an “extended away” presence from this contact to the user.

This is a global status, as opposed to LegacyContact.inactive() which concerns a specific conversation, ie a specific “chat window”

Parameters:

status (Optional[str]) – Arbitrary text, details of the status, eg: “Gone to fight capitalism”
last_seen (Optional[datetime.datetime]) – For XEP-0319

busy(status=None, last_seen=None)#

Send a “busy” (ie, “dnd”) presence from this contact to the user,

Parameters:

status (Optional[str]) – eg: “Trying to make sense of XEP-0100”
last_seen (Optional[datetime.datetime]) – For XEP-0319

offline(status=None, last_seen=None)#

Send an “offline” presence from this contact to the user.

Parameters:

status (Optional[str]) – eg: “Trying to make sense of XEP-0100”
last_seen (Optional[datetime.datetime]) – For XEP-0319

async available_emojis(legacy_msg_id=None)#

Override this to restrict the subset of reactions this recipient can handle.

Returns:: A set of emojis or None if any emoji is allowed
Parameters:: legacy_msg_id (Optional[slidge.util.types.LegacyMessageType]) –
Return type:: Optional[set[str]]

class slidge.contact.LegacyRoster(session)#

Virtual roster of a gateway user, that allows to represent all of their contacts as singleton instances (if used properly and not too bugged).

Every BaseSession instance will have its own LegacyRoster instance accessible via the BaseSession.contacts attribute.

Typically, you will mostly use the LegacyRoster.by_legacy_id() function to retrieve a contact instance.

You might need to override LegacyRoster.legacy_id_to_jid_username() and/or LegacyRoster.jid_username_to_legacy_id() to incorporate some custom logic if you need some characters when translation JID user parts and legacy IDs.

Parameters:: session (slidge.core.session.BaseSession) –

async by_legacy_id(legacy_id, *args, **kwargs)#

Retrieve a contact by their legacy_id

If the contact was not instantiated before, it will be created using slidge.LegacyRoster.legacy_id_to_jid_username() to infer their legacy user ID.

Parameters:

legacy_id (slidge.util.types.LegacyUserIdType) –
args – arbitrary additional positional arguments passed to the contact constructor. Requires subclassing LegacyContact.__init__ to accept those. This is useful for networks where you fetch the contact list and information about these contacts in a single request
kwargs – arbitrary keyword arguments passed to the contact constructor

Returns:

Return type:

slidge.util.types.LegacyContactType

async legacy_id_to_jid_username(legacy_id)#

Convert a legacy ID to a valid ‘user’ part of a JID

Should be overridden for cases where the str conversion of the legacy_id is not enough, e.g., if it is case-sensitive or contains forbidden characters not covered by XEP-0106.

Parameters:: legacy_id (slidge.util.types.LegacyUserIdType) –
Return type:: str

async jid_username_to_legacy_id(jid_username)#

Convert a JID user part to a legacy ID.

Should be overridden in case legacy IDs are not strings, or more generally for any case where the username part of a JID (unescaped with to the mapping defined by XEP-0106) is not enough to identify a contact on the legacy network.

Default implementation is an identity operation

Parameters:: jid_username (str) – User part of a JID, ie “user” in “user@example.com”
Returns:: An identifier for the user on the legacy network.
Return type:: slidge.util.types.LegacyUserIdType

async fill()#

Populate slidge’s “virtual roster”.

Override this and in it, await self.by_legacy_id(contact_id) for the every legacy contacts of the user for which you’d like to set an avatar, nickname, vcard…

Await Contact.add_to_roster() in here to add the contact to the user’s XMPP roster.

slidge.contact#

Package Contents#

Classes#

`slidge.contact`#