Module Contents#



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





class, legacy_id, jid_username)[source]#

Bases: Generic[slidge.util.types.LegacyUserIdType], slidge.core.mixins.FullCarbonMixin, slidge.core.mixins.recipient.ReactionRecipientMixin, slidge.core.mixins.recipient.ThreadRecipientMixin

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.

  • session (slidge.core.session.BaseSession) – The session this contact is part of

  • legacy_id (slidge.util.types.LegacyUserIdType) – The contact’s legacy ID

  • jid_username (str) – User part of this contact’s ‘puppet’ JID. NB: case-insensitive, and some special characters are not allowed

property name[source]#

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

property avatar[source]#

An image that represents this contact

session: slidge.core.session.BaseSession[source]#
RESOURCE: str = 'slidge'[source]#

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.

mtype = 'chat'[source]#
_can_send_carbon = True[source]#
is_group = False[source]#
STRIP_SHORT_DELAY = True[source]#

Return repr(self).

_send(stanza, carbon=False, **send_kwargs)[source]#

stanza (Union[slixmpp.Message, slixmpp.Presence]) –


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.


horizon_xmpp_id (str) – The latest message


A list of XMPP ids or None if horizon_xmpp_id was not found

async set_avatar(a, avatar_unique_id=None, blocking=False)[source]#

Set the avatar for this contact

  • a (Optional[slidge.util.types.AvatarType]) – Any avatar format supported by slidge

  • avatar_unique_id (Optional[Union[int, str]]) – If possible, provide a unique ID to cache the avatar. If it is not provided, the SHA-1 of the avatar will be used, unless it is an HTTP url. In this case, the url will be used, along with etag or last modified HTTP headers, to avoid fetching uselessly. Beware of legacy plugin where URLs are not stable.

  • blocking – if True, will await setting the avatar, if False, launch in a task


set_vcard(/, full_name = None, given = None, surname = None, birthday = None, phone = None, phones = (), note = None, url = None, email = None, country = None, locality=None)[source]#
  • full_name (Optional[str]) –

  • given (Optional[str]) –

  • surname (Optional[]) –

  • birthday (Optional[str]) –

  • phone (Iterable[str]) –

  • phones (Optional[str]) –

  • note (Optional[str]) –

  • url (Optional[str]) –

  • email (Optional[str]) –

  • country (Optional[str]) –

async add_to_roster()[source]#

Add this contact to the user roster using XEP-0356

async __broadcast_pubsub_items()[source]#
async _set_roster(**kw)[source]#
async on_added_to_roster_no_privilege()[source]#

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()[source]#

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

async fetch_vcard()[source]#

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:[source]#

stanza (Union[slixmpp.Message, slixmpp.Presence]) –[source]#