:orphan:

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

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


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

Classes
~~~~~~~

.. autoapisummary::

   slidge.contact.roster.LegacyRoster




.. py:exception:: ContactIsUser




   Common base class for all non-exit exceptions.

   .. py:method:: add_note()

      Exception.add_note(note) --
      add a note to the exception


   .. py:method:: with_traceback()

      Exception.with_traceback(tb) --
      set self.__traceback__ to tb and return self.



.. 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, *args, **kwargs)
      :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:
      :param 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
      :param kwargs: arbitrary keyword arguments passed to the contact constructor
      :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".

      Override this and in it, ``await self.by_legacy_id(contact_id)``
      for the every legacy contacts of the user for which you'd like to
      set an avatar, nickname, vcard…

      Await ``Contact.add_to_roster()`` in here to add the contact to the
      user's XMPP roster.



