slidge.contact
==============

.. py:module:: slidge.contact

.. autoapi-nested-parse::

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



Classes
-------

.. autoapisummary::

   slidge.contact.LegacyContact
   slidge.contact.LegacyRoster


Package Contents
----------------

.. py:class:: LegacyContact(session, stored)



   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:attribute:: RESOURCE
      :type:  str
      :value: '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:property:: client_type
      :type: slidge.util.types.ClientType


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

      Default is "pc".



   .. py:method:: pop_unread_xmpp_ids_up_to(horizon_xmpp_id)

      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.

      :param horizon_xmpp_id: The latest message
      :return: A list of XMPP ids up to horizon_xmpp_id, included



   .. py:property:: name
      :type: str


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



   .. py:method:: set_vcard(/, full_name = None, given = None, surname = None, birthday = None, phone = None, phones = (), note = None, url = None, email = None, country = None, locality = None, pronouns=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.



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



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


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

      Unlike the awaitable :method:`.set_avatar`, it schedules the update for
      later execution and is not blocking



   .. py:method:: set_avatar(avatar = None, delete = False)
      :async:


      Set an avatar for this entity

      :param avatar: The avatar. Should ideally come with a legacy network-wide unique
          ID
      :param delete: If the avatar is provided as a Path, whether to delete
          it once used or not.



   .. py:method:: serialize_extra_attributes()

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




   .. py:method:: deserialize_extra_attributes(data)

      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.



   .. py:method:: invite_to(muc, reason = None, password = None, **send_kwargs)

      Send an invitation to join a group (:xep:`0249`) from this :term:`XMPP Entity`.

      :param muc: the muc the user is invited to
      :param reason: a text explaining why the user should join this muc
      :param password: maybe this will make sense later? not sure
      :param send_kwargs: additional kwargs to be passed to _send()
          (internal use by slidge)



   .. py:method:: active(**kwargs)

      Send an "active" chat state (:xep:`0085`) from this
      :term:`XMPP Entity`.



   .. py:method:: composing(**kwargs)

      Send a "composing" (ie "typing notification") chat state (:xep:`0085`)
      from this :term:`XMPP Entity`.



   .. py:method:: paused(**kwargs)

      Send a "paused" (ie "typing paused notification") chat state
      (:xep:`0085`) from this :term:`XMPP Entity`.



   .. py:method:: 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 :term:`XMPP Entity`.



   .. py:method:: 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 :term:`XMPP Entity`.



   .. py:method:: send_file(attachment, legacy_msg_id = None, *, reply_to = None, when = None, thread = None, **kwargs)
      :async:


      Send a single file from this :term:`XMPP Entity`.

      :param attachment: The file to send.
          Ideally, a :class:`.LegacyAttachment` with a unique ``legacy_file_id``
          attribute set, to optimise potential future reuses.
          It can also be:
          - a :class:`pathlib.Path` instance to point to a local file, or
          - a ``str``, representing a fetchable HTTP URL.
      :param legacy_msg_id: If you want to be able to transport read markers from the gateway
          user to the legacy network, specify this
      :param reply_to: Quote another message (:xep:`0461`)
      :param when: when the file was sent, for a "delay" tag (:xep:`0203`)
      :param thread:



   .. py:method:: 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 :term:`XMPP Entity`.

      :param body: Content of the message
      :param legacy_msg_id: If you want to be able to transport read markers from the gateway
          user to the legacy network, specify this
      :param when: when the message was sent, for a "delay" tag (:xep:`0203`)
      :param reply_to: Quote another message (:xep:`0461`)
      :param hints:
      :param thread:
      :param carbon: (only used if called on a :class:`LegacyContact`)
          Set this to ``True`` if this is actually a message sent **to** the
          :class:`LegacyContact` by the :term:`User`.
          Use this to synchronize outgoing history for legacy official apps.
      :param correction: whether this message is a correction or not
      :param 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.
      :param link_previews: A little of sender (or server, or gateway)-generated
          previews of URLs linked in the body.
      :param 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()``



   .. py:method:: 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 :term:`XMPP Entity`.

      Uses last message correction (:xep:`0308`)

      :param new_text: New content of the message
      :param legacy_msg_id: The legacy message ID of the message to correct
      :param when: when the message was sent, for a "delay" tag (:xep:`0203`)
      :param reply_to: Quote another message (:xep:`0461`)
      :param hints:
      :param thread:
      :param 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.
      :param 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()``
      :param 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.
      :param link_previews: A little of sender (or server, or gateway)-generated
          previews of URLs linked in the body.



   .. py:method:: react(legacy_msg_id, emojis = (), thread = None, **kwargs)

      Send a reaction (:xep:`0444`) from this :term:`XMPP Entity`.

      :param legacy_msg_id: The message which the reaction refers to.
      :param emojis: An iterable of emojis used as reactions
      :param thread:



   .. py:method:: retract(legacy_msg_id, thread = None, **kwargs)

      Send a message retraction (:XEP:`0424`) from this :term:`XMPP Entity`.

      :param legacy_msg_id: Legacy ID of the message to delete
      :param thread:



   .. py:method:: ack(legacy_msg_id, **kwargs)

      Send an "acknowledged" message marker (:xep:`0333`) from this :term:`XMPP Entity`.

      :param legacy_msg_id: The message this marker refers to



   .. py:method:: received(legacy_msg_id, **kwargs)

      Send a "received" message marker (:xep:`0333`) from this :term:`XMPP Entity`.
      If called on a :class:`LegacyContact`, also send a delivery receipt
      marker (:xep:`0184`).

      :param legacy_msg_id: The message this marker refers to



   .. py:method:: displayed(legacy_msg_id, **kwargs)

      Send a "displayed" message marker (:xep:`0333`) from this :term:`XMPP Entity`.

      :param legacy_msg_id: The message this marker refers to



   .. py:method:: online(status = None, last_seen = None)

      Send an "online" presence from this contact to the user.

      :param status: Arbitrary text, details of the status, eg: "Listening to Britney Spears"
      :param last_seen: For :xep:`0319`



   .. py:method:: away(status = None, last_seen = None)

      Send an "away" presence from this contact to the user.

      This is a global status, as opposed to :meth:`.LegacyContact.inactive`
      which concerns a specific conversation, ie a specific "chat window"

      :param status: Arbitrary text, details of the status, eg: "Gone to fight capitalism"
      :param last_seen: For :xep:`0319`



   .. py:method:: 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 :meth:`.LegacyContact.inactive`
      which concerns a specific conversation, ie a specific "chat window"

      :param status: Arbitrary text, details of the status, eg: "Gone to fight capitalism"
      :param last_seen: For :xep:`0319`



   .. py:method:: busy(status = None, last_seen = None)

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

      :param status: eg: "Trying to make sense of XEP-0100"
      :param last_seen: For :xep:`0319`



   .. py:method:: offline(status = None, last_seen = None)

      Send an "offline" presence from this contact to the user.

      :param status: eg: "Trying to make sense of XEP-0100"
      :param last_seen: For :xep:`0319`



   .. py:method:: available_emojis(legacy_msg_id = None)
      :async:


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

      :return: A set of emojis or None if any emoji is allowed



.. py:class:: 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 :class:`.BaseSession` instance will have its own :class:`.LegacyRoster` instance
   accessible via the :attr:`.BaseSession.contacts` attribute.

   Typically, you will mostly use the :meth:`.LegacyRoster.by_legacy_id` function to
   retrieve a contact instance.

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


   .. py:method:: by_legacy_id(legacy_id)
      :async:


      Retrieve a contact by their legacy_id

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

      :param legacy_id:
      :return:



   .. py:method:: legacy_id_to_jid_username(legacy_id)
      :async:


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

      :param legacy_id:



   .. py:method:: jid_username_to_legacy_id(jid_username)
      :async:


      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

      :param jid_username: User part of a JID, ie "user" in "user@example.com"
      :return: An identifier for the user on the legacy network.



   .. py:method:: fill()
      :async:


      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
      :meth:`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.




