:orphan:

:py:mod:`slidge.contact.contact`
================================

.. py:module:: slidge.contact.contact


Module Contents
---------------

Classes
~~~~~~~

.. autoapisummary::

   slidge.contact.contact.LegacyContact




.. py:class:: 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
   :meth:`.LegacyRoster.by_legacy_id` to ensure that contact instances are
   singletons. The :class:`.LegacyRoster` instance of a session is accessible
   through the :attr:`.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:

   .. code-block:python

       class Session(BaseSession):
           ...

           async def on_cool_chat_network_new_text_message(self, legacy_msg_event):
               contact = self.contacts.by_legacy_id(legacy_msg_event.from)
               contact.send_text(legacy_msg_event.text)

           async def on_cool_chat_network_new_typing_event(self, legacy_typing_event):
               contact = self.contacts.by_legacy_id(legacy_msg_event.from)
               contact.composing()
           ...

   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.

   .. py:property:: name

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


   .. py:attribute:: RESOURCE
      :annotation: :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.


   .. py:attribute:: legacy_id
      :annotation: :slidge.util.types.LegacyUserIdType

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

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


   .. py:method:: 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.

      :param horizon_xmpp_id: The latest message
      :return: A list of XMPP ids or None if horizon_xmpp_id was not found


   .. py:method:: add_to_roster(force=False)
      :async:

      Add this contact to the user roster using :xep:`0356`

      :param force: add even if the contact was already added successfully


   .. py:method:: accept_friend_request(text = None)
      :async:

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

      :param text: Optional message from the friend to the user


   .. py:method:: 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)

      :param text: Optional message from the non-friend to the user


   .. py:method:: on_friend_request(text='')
      :async:

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


   .. py:method:: on_friend_delete(text='')
      :async:

      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)".


   .. py:method:: on_friend_accept()
      :async:

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


   .. py:method:: 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'".


   .. py:method:: update_info()
      :async:

      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
      :py:meth:`slidge.core.mixins.avatar.AvatarMixin.set_avatar` or attempt
      to modify the ``.avatar`` property.


   .. py:method:: fetch_vcard()
      :async:

      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:



