:orphan:

:py:mod:`slidge.group.room`
===========================

.. py:module:: slidge.group.room


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

Classes
~~~~~~~

.. autoapisummary::

   slidge.group.room.LegacyMUC




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




   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:property:: avatar_id
      :type: Optional[slidge.util.types.AvatarIdType]

      The unique ID of this entity's avatar.


   .. py:property:: avatar
      :type: Optional[slidge.util.types.AvatarIdType]

      This property can be used to set the avatar, but
      :py:meth:`~.AvatarMixin.set_avatar()` should be preferred because you can
      provide a unique ID for the avatar for efficient caching.
      Setting this is OKish in case the avatar type is a URL or a local path
      that can act as a legacy ID.

      Python's ``property`` is abused here to maintain backwards
      compatibility, but when getting it you actually get the avatar legacy
      ID.


   .. py:attribute:: STABLE_ARCHIVE
      :value: False

      Because legacy events like reactions, editions, etc. don't all map to a stanza
      with a proper legacy ID, slidge usually cannot guarantee the stability of the archive
      across restarts.

      Set this to True if you know what you're doing, but realistically, this can't
      be set to True until archive is permanently stored on disk by slidge.

      This is just a flag on archive responses that most clients ignore anyway.


   .. py:attribute:: KEEP_BACKFILLED_PARTICIPANTS
      :value: False

      Set this to ``True`` if the participant list is not full after calling
      ``fill_participants()``. This is a workaround for networks with huge
      participant lists which do not map really well the MUCs where all presences
      are sent on join.
      It allows to ensure that the participants that last spoke (within the
      ``fill_history()`` method are effectively participants, thus making possible
      for XMPP clients to fetch their avatars.


   .. py:attribute:: HAS_DESCRIPTION
      :value: True

      Set this to false if the legacy network does not allow setting a description
      for the group. In this case the description field will not be present in the
      room configuration form.


   .. py:attribute:: HAS_SUBJECT
      :value: True

      Set this to false if the legacy network does not allow setting a subject
      (sometimes also called topic) for the group. In this case, as a subject is
      recommended by :xep:`0045` ("SHALL"), the description (or the group name as
      ultimate fallback) will be used as the room subject.
      By setting this to false, an error will be returned when the :term:`User`
      tries to set the room subject.


   .. py:method:: update_info()
      :abstractmethod:
      :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:: backfill(oldest_message_id = None, oldest_message_date = None)
      :abstractmethod:
      :async:

      Override this if the legacy network provide server-side archive.
      In it, send history messages using ``self.get_participant().send*``,
      with the ``archive_only=True`` kwarg.

      You only need to fetch messages older than ``oldest_message_id``.

      :param oldest_message_id: The oldest message ID already present in the archive
      :param oldest_message_date: The oldest message date already present in the archive


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

      In here, call self.get_participant(), self.get_participant_by_contact(),
      of self.get_user_participant() to make an initial list of participants.


   .. py:method:: get_user_participant(**kwargs)
      :async:

      Get the participant representing the gateway user

      :param kwargs: additional parameters for the :class:`.Participant`
          construction (optional)
      :return:


   .. py:method:: get_participant(nickname, raise_if_not_found=False, fill_first=False, store=True, **kwargs)
      :async:

      Get a participant by their nickname.

      In non-anonymous groups, you probably want to use
      :meth:`.LegacyMUC.get_participant_by_contact` instead.

      :param nickname: Nickname of the participant (used as resource part in the MUC)
      :param raise_if_not_found: Raise XMPPError("item-not-found") if they are not
          in the participant list (internal use by slidge, plugins should not
          need that)
      :param fill_first: Ensure :meth:`.LegacyMUC.fill_participants()` has been called first
           (internal use by slidge, plugins should not need that)
      :param store: persistently store the user in the list of MUC participants
      :param kwargs: additional parameters for the :class:`.Participant`
          construction (optional)
      :return:


   .. py:method:: get_system_participant()

      Get a pseudo-participant, representing the room itself

      Can be useful for events that cannot be mapped to a participant,
      e.g. anonymous moderation events, or announces from the legacy
      service
      :return:


   .. py:method:: get_participant_by_contact(c, **kwargs)
      :async:

      Get a non-anonymous participant.

      This is what should be used in non-anonymous groups ideally, to ensure
      that the Contact jid is associated to this participant

      :param c: The :class:`.LegacyContact` instance corresponding to this contact
      :param kwargs: additional parameters for the :class:`.Participant`
          construction (optional)
      :return:


   .. py:method:: get_participants()
      :async:

      Get all known participants of the group, ensure :meth:`.LegacyMUC.fill_participants`
      has been awaited once before. Plugins should not use that, internal
      slidge use only.
      :return:


   .. py:method:: remove_participant(p, kick=False, ban=False)

      Call this when a participant leaves the room

      :param p: The participant
      :param kick: Whether the participant left because they were kicked
      :param ban: Whether the participant left because they were banned


   .. py:method:: kick_resource(r)
      :async:

      Kick a XMPP client of the user. (slidge internal use)

      :param r: The resource to kick


   .. py:method:: add_to_bookmarks(auto_join=True, invite=False, preserve=True)
      :async:

      Add the MUC to the user's XMPP bookmarks (:xep:`0402')

      This requires that slidge has the IQ privileged set correctly
      on the XMPP server

      :param auto_join: whether XMPP clients should automatically join
          this MUC on startup. In theory, XMPP clients will receive
          a "push" notification when this is called, and they will
          join if they are online.
      :param invite: send an invitation to join this MUC emanating from
          the gateway. While this should not be strictly necessary,
          it can help for clients that do not support :xep:`0402`, or
          that have 'do not honor bookmarks auto-join' turned on in their
          settings.
      :param preserve: preserve auto-join and bookmarks extensions
          set by the user outside slidge


   .. py:method:: on_avatar(data, mime)
      :abstractmethod:
      :async:

      Called when the user tries to set the avatar of the room from an XMPP
      client.

      If the set avatar operation is completed, should return a legacy image
      unique identifier. In this case the MUC avatar will be immediately
      updated on the XMPP side.

      If data is not None and this method returns None, then we assume that
      self.set_avatar() will be called elsewhere, eg triggered by a legacy
      room update event.

      :param data: image data or None if the user meant to remove the avatar
      :param mime: the mime type of the image. Since this is provided by
          the XMPP client, there is no guarantee that this is valid or
          correct.
      :return: A unique avatar identifier, which will trigger
          :py:meth:`slidge.group.room.LegacyMUC.set_avatar`. Alternatively, None, if
          :py:meth:`.LegacyMUC.set_avatar` is meant to be awaited somewhere else.


   .. py:method:: on_set_affiliation(contact, affiliation, reason, nickname)
      :abstractmethod:
      :async:

      Triggered when the user requests changing the affiliation of a contact
      for this group,

      Examples: promotion them to moderator, kick (affiliation=none),
      ban (affiliation=outcast).

      :param contact: The contact whose affiliation change is requested
      :param affiliation: The new affiliation
      :param reason: A reason for this affiliation change
      :param nickname:


   .. py:method:: on_set_config(name, description)
      :abstractmethod:
      :async:

      Triggered when the user requests changing the room configuration.
      Only title and description can be changed at the moment.

      The legacy module is responsible for updating :attr:`.title` and/or
      :attr:`.description` of this instance.

      If :attr:`.HAS_DESCRIPTION` is set to False, description will always
      be ``None``.

      :param name: The new name of the room.
      :param description: The new description of the room.


   .. py:method:: on_destroy_request(reason)
      :abstractmethod:
      :async:

      Triggered when the user requests room destruction.

      :param reason: Optionally, a reason for the destruction


   .. py:method:: on_set_subject(subject)
      :abstractmethod:
      :async:

      Triggered when the user requests changing the room subject.

      The legacy module is responsible for updating :attr:`.subject` of this
      instance.

      :param subject: The new subject for this room.


   .. py:method:: set_avatar(a, avatar_unique_id = None, blocking=False, cancel=True)
      :async:

      Set an avatar for this entity

      :param a:
      :param avatar_unique_id:
      :param blocking:
      :param cancel:


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



