matridge.contact
================

.. py:module:: matridge.contact


Classes
-------

.. autoapisummary::

   matridge.contact.Contact
   matridge.contact.Roster


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

.. py:class:: Contact(session, legacy_id, jid_username)

   Bases: :py:obj:`slidge.LegacyContact`\ [\ :py:obj:`str`\ ]


   We don't implement direct messages but the what's parsed here will propagate
   to MUC participants.

   :param session: The session this contact is part of
   :param legacy_id: The contact's legacy ID
   :param jid_username: User part of this contact's 'puppet' JID.
       NB: case-insensitive, and some special characters are not allowed


   .. py:attribute:: session
      :type:  matridge.session.Session


   .. 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:method:: update_presence(p)


.. py:class:: Roster(session)

   Bases: :py:obj:`slidge.LegacyRoster`\ [\ :py:obj:`str`\ , :py:obj:`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 :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:attribute:: session
      :type:  matridge.session.Session


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



