matteridge.contact

Classes

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

Functions

noop()

Module Contents

async matteridge.contact.noop()

class matteridge.contact.Contact(session, legacy_id, jid_username, user=None)

Bases: matteridge.util.UserMixin, slidge.LegacyContact[str]

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 (matteridge.session.Session) – The session this contact is part of

• legacy_id (str) – 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

• user (Optional[mattermost_api_reference_client.models.User])

session: matteridge.session.Session

STATUS_FETCH_MINIMUM_INTERVAL

STATUS_API_FETCH_MINIMUM_INTERVAL

MARKS = False

REPLIES = False

_status: matteridge.events.StatusType = 'online'

_last_seen: datetime.datetime | None = None

_custom_status: str | None = None

_custom_status_expire_task

_last_status_fetch: datetime.datetime | None = None

_last_api_status_fetch: datetime.datetime | None = None

mm

mm_user = None

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

update_websocket_status(status)

Parameters:

status (matteridge.events.StatusType)

update_custom_status(c=None)

Parameters:

c (Optional[mattermost_api_reference_client.models.UpdateUserCustomStatusJsonBody])

async fetch_ws_status()

async fetch_api_status()

async _reset_custom_status(sleep)

Parameters:

sleep (float)

update_api_status(status)

Parameters:

status (mattermost_api_reference_client.models.Status)

_update_presence()

async direct_channel_id()

async mm_id()

async update_info(user=None)

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.

Parameters:

user (Optional[mattermost_api_reference_client.models.User])

class matteridge.contact.Roster(session)

Bases: slidge.LegacyRoster[str, Contact]

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)

session: matteridge.session.Session

STATUS_POLL_INTERVAL = 300

property mm

async by_jid(jid)

async by_legacy_id(legacy_id, user=None, *a, **kw)

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 (str)

• 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

• user (Optional[mattermost_api_reference_client.models.User])

Returns:

Return type:

Contact

async update_statuses()

async by_mm_user_id(user_id, user=None)

Parameters:

• user_id (str)

• user (Optional[mattermost_api_reference_client.models.User])

Return type:

Contact

async by_direct_channel_id(channel_id)

Parameters:

channel_id (str)

Return type:

Optional[Contact]

async fill()

Populate slidge’s “virtual roster”.

This should yield contacts that are meant to be added to the user’s roster, typically by using await self.by_legacy_id(contact_id). Setting the contact nicknames, avatar, etc. should be in LegacyContact.update_info()

It’s not mandatory to override this method, but it is recommended way to populate “friends” of the user. Calling await (await self.by_legacy_id(contact_id)).add_to_roster() accomplishes the same thing, but doing it in here allows to batch DB queries and is better performance-wise.

async known_user_ids(only_friends=False, including_me=True)