matridge.group
==============

.. py:module:: matridge.group


Classes
-------

.. autoapisummary::

   matridge.group.Participant
   matridge.group.Bookmarks
   matridge.group.MUC


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

.. py:class:: Participant

   Bases: :py:obj:`matridge.util.MatrixMixin`, :py:obj:`slidge.group.LegacyParticipant`


   A legacy participant of a legacy group chat.


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


   .. py:attribute:: muc
      :type:  MUC


.. py:class:: Bookmarks(session)

   Bases: :py:obj:`slidge.group.LegacyBookmarks`


   This is instantiated once per :class:`~slidge.BaseSession`


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


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


      Establish a user's known groups.

      This has to be overridden in plugins with group support and at the
      minimum, this should ``await self.by_legacy_id(group_id)`` for all
      the groups a user is part of.

      Slidge internals will call this on successful :meth:`BaseSession.login`




.. py:class:: MUC(session, legacy_id, jid)

   Bases: :py:obj:`slidge.group.LegacyMUC`\ [\ :py:obj:`str`\ , :py:obj:`str`\ , :py:obj:`Participant`\ , :py:obj:`str`\ ]


   A room, a.k.a. a Multi-User Chat.

   MUC instances are obtained by calling :py:meth:`slidge.group.bookmarks.LegacyBookmarks`
   on the user's :py:class:`slidge.core.session.BaseSession`.


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


   .. py:attribute:: type


   .. py:method:: get_room()
      :async:



   .. py:method:: get_message(msg_id)
      :async:



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


      Fetch information about this group from the legacy network

      This is awaited on MUC instantiation, and should be overridden to
      update the attributes of the group chat, like title, subject, number
      of participants etc.

      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 :attr:.avatar property.



   .. py:method:: fill_participants()
      :async:


      This method should yield the list of all members of this group.

      Typically, use ``participant = self.get_participant()``, self.get_participant_by_contact(),
      of self.get_user_participant(), and update their affiliation, hats, etc.
      before yielding them.



   .. py:method:: backfill(after = None, before = None)
      :async:


      Override this if the legacy network provide server-side group archives.

      In it, send history messages using ``self.get_participant(xxx).send_xxxx``,
      with the ``archive_only=True`` kwarg. This is only called once per slidge
      run for a given group.

      :param after: Fetch messages after this one. If ``None``, it's up to you
          to decide how far you want to go in the archive. If it's not ``None``,
          it means slidge has some messages in this archive and you should really try
          to complete it to avoid "holes" in the history of this group.
      :param before: Fetch messages before this one. If ``None``, fetch all messages
          up to the most recent one



