Skip to content
Back to top
View this page
Edit this page

# slidge.contact

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

## Package Contents

class slidge.contact.LegacyContact(session: slidge.util.types.AnySession, stored: slidge.db.models.Contact)

  Bases: `slidge.core.mixins.AvatarMixin`, `slidge.core.mixins.disco.ContactAccountDiscoMixin`, `slidge.core.mixins.FullCarbonMixin`, `slidge.core.mixins.recipient.RecipientMixin`, `slidge.util.SubclassableOnce`

  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.

  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.

  property client_type: slidge.util.types.ClientType

    The client type of this contact, cf https://xmpp.org/registrar/disco-categories.html#client

    Default is “pc”.

  pop_unread_xmpp_ids_up_to(horizon_xmpp_id: str) → list[str]

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

    Legacy modules 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 cleared, to avoid sending the same read mark twice.

    Parameters:

      horizon_xmpp_id – The latest message

    Returns:

      A list of XMPP ids up to horizon_xmpp_id, included

  property name: str

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

  set_vcard(/, full_name: str | None = None, given: str | None = None, surname: datetime.date | None = None, birthday: str | None = None, phone: collections.abc.Iterable[str] = None, phones: str | None = (), note: str | None = None, url: str | None = None, email: str | None = None, country: str | None = None, locality: str | None = None, pronouns=None) → None

    Update xep:0292 data for this contact.

    Use this for additional metadata about this contact to be available to XMPP clients. The “note” argument is a text of arbitrary size and can be useful when no other field is a good fit.

  async add_to_roster(force: bool = False) → None

    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: str | None = None) → None

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

    Parameters:

      text – Optional message from the friend to the user

  reject_friend_request(text: str | None = None) → 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 message from the non-friend to the user

  async on_friend_request(text: str = '') → None

    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: str = '') → None

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

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

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

  async fetch_vcard() → None

    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:

  property avatar: slidge.util.types.Avatar | None

    This property can be used to set or unset the avatar.

    Unlike the awaitable `set_avatar()`, it schedules the update for later execution and is not blocking

  async set_avatar(avatar: slidge.util.types.Avatar | pathlib.Path | str | None = None, delete: bool = False) → None

    Set an avatar for this entity

    Parameters:

      - avatar – The avatar. Should ideally come with a legacy network-wide unique ID

      - delete – If the avatar is provided as a Path, whether to delete it once used or not.

  serialize_extra_attributes() → slidge.db.meta.JSONSerializable | None

    If you want custom attributes of your instance to be stored persistently to the DB, here is where you have to return them as a dict to be used in deserialize_extra_attributes().

  deserialize_extra_attributes(data: slidge.db.meta.JSONSerializable) → None

    This is where you get the dict that you passed in serialize_extra_attributes().

    ⚠ Since it is serialized as json, dictionary keys are converted to strings! Be sure to convert to other types if necessary.

  invite_to(muc: slidge.util.types.AnyMUC, reason: str | None = None, password: str | None = None, **send_kwargs: object) → None

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

    Parameters:

      - muc – the muc the user is invited to

      - reason – a text explaining why the user should join this muc

      - password – maybe this will make sense later? not sure

      - send_kwargs – additional kwargs to be passed to _send() (internal use by slidge)

  active(**kwargs: object) → None

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

  composing(**kwargs: object) → None

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

  paused(**kwargs: object) → None

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

  inactive(**kwargs: object) → None

    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: object) → None

    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.

  async send_file(attachment: slidge.util.types.LegacyAttachment | pathlib.Path | str, legacy_msg_id: str | None = None, *, reply_to: slidge.util.types.MessageReference | None = None, when: datetime.datetime | None = None, thread: str | None = None, **kwargs: Any) → tuple[str | None, list[slixmpp.Message]]

    Send a single file from this XMPP Entity.

    Parameters:

      - attachment – The file to send. Ideally, a `LegacyAttachment` with a unique `legacy_file_id` attribute set, to optimise potential future reuses. It can also be: - a `pathlib.Path` instance to point to a local file, or - a `str`, representing a fetchable HTTP URL.

      - legacy_msg_id – If you want to be able to transport read markers from the gateway user to the legacy network, specify this

      - reply_to – Quote another message (XEP-0461)

      - when – when the file was sent, for a “delay” tag (XEP-0203)

      - thread

  send_text(body: str, legacy_msg_id: str | None = None, *, when: datetime.datetime | None = None, reply_to: slidge.util.types.MessageReference | None = None, thread: str | None = None, hints: collections.abc.Iterable[slidge.util.types.ProcessingHint] | None = None, carbon: bool = False, archive_only: bool = False, correction: bool = False, correction_event_id: str | None = None, link_previews: list[slidge.util.types.LinkPreview] | None = None, **send_kwargs: object) → slixmpp.Message | None

    Send a text message from this XMPP Entity.

    Parameters:

      - body – Content of the message

      - legacy_msg_id – If you want to be able to transport read markers from the gateway user to the legacy network, specify this

      - when – when the message was sent, for a “delay” tag (XEP-0203)

      - reply_to – Quote another message (XEP-0461)

      - hints

      - thread

      - 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 – 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 – 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: str, new_text: str, *, when: datetime.datetime | None = None, reply_to: slidge.util.types.MessageReference | None = None, thread: str | None = None, hints: collections.abc.Iterable[slidge.util.types.ProcessingHint] | None = None, carbon: bool = False, archive_only: bool = False, correction_event_id: str | None = None, link_previews: list[slidge.util.types.LinkPreview] | None = None, **send_kwargs: object) → None

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

    Uses last message correction (XEP-0308)

    Parameters:

      - new_text – New content of the message

      - legacy_msg_id – The legacy message ID of the message to correct

      - when – when the message was sent, for a “delay” tag (XEP-0203)

      - reply_to – Quote another message (XEP-0461)

      - hints

      - thread

      - 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 – 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 – A little of sender (or server, or gateway)-generated previews of URLs linked in the body.

  react(legacy_msg_id: str, emojis: collections.abc.Iterable[str] = (), thread: str | None = None, **kwargs: object) → None

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

    Parameters:

      - legacy_msg_id – The message which the reaction refers to.

      - emojis – An iterable of emojis used as reactions

      - thread

  retract(legacy_msg_id: str, thread: str | None = None, **kwargs: object) → None

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

    Parameters:

      - legacy_msg_id – Legacy ID of the message to delete

      - thread

  ack(legacy_msg_id: str, **kwargs: object) → None

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

    Parameters:

      legacy_msg_id – The message this marker refers to

  received(legacy_msg_id: str, **kwargs: object) → None

    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 – The message this marker refers to

  displayed(legacy_msg_id: str, **kwargs: object) → None

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

    Parameters:

      legacy_msg_id – The message this marker refers to

  online(status: str | None = None, last_seen: datetime.datetime | None = None) → None

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

    Parameters:

      - status – Arbitrary text, details of the status, eg: “Listening to Britney Spears”

      - last_seen – For XEP-0319

  away(status: str | None = None, last_seen: datetime.datetime | None = None) → 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 – Arbitrary text, details of the status, eg: “Gone to fight capitalism”

      - last_seen – For XEP-0319

  extended_away(status: str | None = None, last_seen: datetime.datetime | None = None) → 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 – Arbitrary text, details of the status, eg: “Gone to fight capitalism”

      - last_seen – For XEP-0319

  busy(status: str | None = None, last_seen: datetime.datetime | None = None) → None

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

    Parameters:

      - status – eg: “Trying to make sense of XEP-0100”

      - last_seen – For XEP-0319

  offline(status: str | None = None, last_seen: datetime.datetime | None = None) → None

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

    Parameters:

      - status – eg: “Trying to make sense of XEP-0100”

      - last_seen – For XEP-0319

  abstractmethod available_emojis(legacy_msg_id: str | None = None) → set[str] | None
    Async:

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

    Returns:

      A set of emojis or None if any emoji is allowed

  abstractmethod on_message(message: slidge.util.types.XMPPMessage) → str | None
    Async:

    Triggered when the user sends a message to this Recipient.

  abstractmethod on_sticker(sticker: slidge.util.types.Sticker) → str | None
    Async:

    Triggered when the user sends a sticker to this Recipient.

    Parameters:

      sticker – The sticker sent by the user.

    Returns:

      An ID of some sort that can be used later to ack and mark the message as read by the user

  abstractmethod on_chat_state(chat_state: slidge.util.types.ChatState, thread: str | None) → None
    Async:

    Triggered when the user sends a chat state (XEP-0085) to this Recipient.

    Parameters:

      chat_state – The sticker sent by the user.

  abstractmethod on_displayed(legacy_msg_id: str, thread: str | None) → None
    Async:

    Triggered when the user sends a read marker (XEP-0333) to this Recipient.

    This is only possible if a valid `legacy_msg_id` was passed when transmitting a message from a legacy chat to the user, eg in `slidge.contact.LegacyContact.send_text()` or `slidge.group.LegacyParticipant.send_text()`.

    Parameters:

      - legacy_msg_id – Identifier of the message/

      - thread

  abstractmethod on_react(legacy_msg_id: str, emojis: list[str], thread: str | None) → None
    Async:

    Triggered when the user sends an emoji reaction (XEP-0444) to this Recipient.

    Parameters:

      - legacy_msg_id – ID of the message the user reacts to

      - emojis – Unicode characters representing reactions to the message `legacy_msg_id`. An empty list means “no reaction”, ie, remove all reactions if any were present before

      - thread

  abstractmethod on_retract(legacy_msg_id: str, thread: str | None) → None
    Async:

    Triggered when the user retracts (XEP-0424) a message.

    Parameters:

      - legacy_msg_id – Legacy ID of the retracted message

      - thread

class slidge.contact.LegacyRoster(session: slidge.util.types.AnySession)

  Bases: `slidge.util.lock.NamedLockMixin`, `slidge.util.jid_escaping.EscapeMixin`, `slidge.util.SubclassableOnce`, `Generic`[`slidge.util.types.LegacyContactType`]

  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.

  async by_legacy_id(/, legacy_id) → slidge.util.types.LegacyContactType

    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

    Returns:

  async fill() → collections.abc.AsyncIterator[slidge.util.types.LegacyContactType]

    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 legacy_id_to_jid_username(legacy_id: str) → str

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

    The default implementation uses XEP-0106.

    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 – The identifier to convert.

    Returns:

      A valid username part (or “local part”) of a JID.

  async jid_username_to_legacy_id(jid_username: str) → str

    Convert a JID user part to a legacy ID.

    The default implementation uses XEP-0106.

    Should be overridden in case legacy IDs are not strings, or more generally for any case where the username part of a JID is not enough to identify a contact on the legacy network.

    Parameters:

      jid_username – User part of a JID, ie “user” in “user@example.com”

    Returns:

      The string representation of an identifier on the legacy network.