slidge.group
============

.. py:module:: slidge.group

.. autoapi-nested-parse::

   Everything related to groups.





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

.. py:class:: MucType

   Bases: :py:obj:`enum.IntEnum`


   The type of group, private, public, anonymous or not.


   .. py:attribute:: GROUP
      :value: 0


      A private group, members-only and non-anonymous, eg a family group.



   .. py:attribute:: CHANNEL
      :value: 1


      A public group, aka an anonymous channel.



   .. py:attribute:: CHANNEL_NON_ANONYMOUS
      :value: 2


      A public group where participants' legacy IDs are visible to everybody.



.. py:class:: LegacyBookmarks(session: slidge.util.types.AnySession)

   Bases: :py:obj:`slidge.util.jid_escaping.EscapeMixin`, :py:obj:`slidge.util.lock.NamedLockMixin`, :py:obj:`slidge.util.SubclassableOnce`, :py:obj:`Generic`\ [\ :py:obj:`slidge.util.types.LegacyMUCType`\ ]


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


   .. py:method:: fill() -> None
      :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:method:: remove(muc: slidge.util.types.AnyMUC, reason: str = 'You left this group from the official client.', kick: bool = True) -> None
      :async:


      Delete everything about a specific group.

      This should be called when the user leaves the group from the official
      app.

      :param muc: The MUC to remove.
      :param reason: Optionally, a reason why this group was removed.
      :param kick: Whether the user should be kicked from this group. Set this
          to False in case you do this somewhere else in your code, eg, on
          receiving the confirmation that the group was deleted.



   .. py:method:: fetch_space_metadata(legacy_id: str) -> slidge.util.types.SpaceMetadata
      :abstractmethod:

      :async:


      Fetch metadata associated to a space.

      This is called once per slidge runtime. It should return metadata
      associated to the space identified by its ``legacy_id``.
      If there are updates to this metata, they should be communicated to
      slidge by calling :func:`LegacyBookmarks.update_space_metadata`.

      :param legacy_id: Identifier of the space.

      :return: Metadata associated to the space.



   .. py:method:: update_space_metadata(legacy_id: str, metadata: slidge.util.types.SpaceMetadata) -> None
      :async:


      Updates metadata associated to a space.

      :param legacy_id: Identifier of the space.
      :param name: Metadata associated to this space.



   .. py:method:: legacy_id_to_jid_username(legacy_id: str) -> str
      :async:


      Convert a legacy ID to a valid 'user' part of a JID.

      The default implementation uses :xep:`0106`.

      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: The identifier to convert.
      :return: A valid username part (or "local part") of a JID.



   .. py:method:: jid_username_to_legacy_id(jid_username: str) -> str
      :async:


      Convert a JID user part to a legacy ID.

      The default implementation uses :xep:`0106`.

      Should be overridden in case legacy IDs are not strings, or more
      generally for any case where the username part of a JID
      is not enough to identify a contact on the legacy network.

      :param jid_username: User part of a JID, ie "user" in "user@example.com"
      :return: The string representation of an identifier on the legacy network.



.. py:class:: LegacyParticipant(muc: slidge.util.types.AnyMUC, stored: slidge.db.models.Participant, is_system: bool = False, contact: slidge.util.types.LegacyContactType | None = None)

   Bases: :py:obj:`slidge.core.mixins.PresenceMixin`, :py:obj:`slidge.core.mixins.MessageMixin`, :py:obj:`slidge.core.mixins.ChatterDiscoMixin`, :py:obj:`slidge.core.mixins.db.DBMixin`, :py:obj:`slidge.util.SubclassableOnce`, :py:obj:`Generic`\ [\ :py:obj:`slidge.util.types.LegacyContactType`\ ]


   A legacy participant of a legacy group chat.


   .. py:method:: send_initial_presence(full_jid: slixmpp.JID, nick_change: bool = False, presence_id: str | None = None, mav_until: str | None = None) -> None

      Called when the user joins a MUC, as a mechanism
      to indicate to the joining XMPP client the list of "participants".

      Can be called this to trigger a "participant has joined the group" event.

      :param full_jid: Set this to only send to a specific user XMPP resource.
      :param nick_change: Used when the user joins and the MUC renames them (code 210)
      :param presence_id: set the presence ID. used internally by slidge



   .. py:method:: leave() -> None

      Call this when the participant leaves the room



   .. py:method:: kick(reason: str | None = None) -> None

      Call this when the participant is kicked from the room



   .. py:method:: ban(reason: str | None = None) -> None

      Call this when the participant is banned from the room



   .. py:method:: on_set_affiliation(affiliation: slidge.util.types.MucAffiliation, reason: str | None, nickname: str | None) -> None
      :abstractmethod:

      :async:


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

      Examples: promotion them to moderator, 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_kick(reason: str | None) -> None
      :abstractmethod:

      :async:


      Triggered when the user requests changing the role of a contact
      to "none" for this group. Action commonly known as "kick".

      :param contact: Contact to be kicked
      :param reason: A reason for this kick



   .. py:method:: on_invitation(reason: str | None) -> None
      :async:


      Triggered when the user invites this :term:`Contact <Legacy Contact>`
      to a legacy MUC via :xep:`0249`.

      The default implementation calls :meth:`LegacyMUC.on_set_affiliation`
      with the 'member' affiliation. Override if you want to customize this
      behaviour.

      :param muc: The group
      :param reason: Optionally, a reason



   .. py:method:: online(status: str | None = None, last_seen: datetime.datetime | None = None) -> 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: str | None = None, last_seen: datetime.datetime | None = None) -> 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: str | None = None, last_seen: datetime.datetime | None = None) -> 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: str | None = None, last_seen: datetime.datetime | None = None) -> 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: str | None = None, last_seen: datetime.datetime | None = None) -> 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:: invite_to(muc: slidge.util.types.AnyMUC, reason: str | None = None, password: str | None = None, **send_kwargs: object) -> None

      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: object) -> None

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



   .. py:method:: composing(**kwargs: object) -> None

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



   .. py:method:: paused(**kwargs: object) -> None

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



   .. py:method:: inactive(**kwargs: object) -> None

      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: object) -> None

      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:: ack(legacy_msg_id: str, **kwargs: object) -> None

      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: str, **kwargs: object) -> None

      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: str, **kwargs: object) -> None

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

      :param legacy_msg_id: The message this marker refers to



   .. py:method:: send_file(attachment: slidge.util.types.LegacyAttachment | pathlib.Path | str, legacy_msg_id: str | None = None, *, reply_to: slidge.util.types.MessageReference | None = None, when: datetime.datetime | None = None, thread: str | None = None, **kwargs: Any) -> tuple[str | None, list[slixmpp.Message]]
      :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: str, legacy_msg_id: str | None = None, *, when: datetime.datetime | None = None, reply_to: slidge.util.types.MessageReference | None = None, thread: str | None = None, hints: collections.abc.Iterable[slidge.util.types.ProcessingHint] | None = None, carbon: bool = False, archive_only: bool = False, correction: bool = False, correction_event_id: str | None = None, link_previews: list[slidge.util.types.LinkPreview] | None = None, **send_kwargs: object) -> slixmpp.Message | None

      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: str, new_text: str, *, when: datetime.datetime | None = None, reply_to: slidge.util.types.MessageReference | None = None, thread: str | None = None, hints: collections.abc.Iterable[slidge.util.types.ProcessingHint] | None = None, carbon: bool = False, archive_only: bool = False, correction_event_id: str | None = None, link_previews: list[slidge.util.types.LinkPreview] | None = None, **send_kwargs: object) -> None

      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: str, emojis: collections.abc.Iterable[str] = (), thread: str | None = None, **kwargs: object) -> None

      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: str, thread: str | None = None, **kwargs: object) -> None

      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:class:: LegacyMUC(session: slidge.util.types.AnySession, stored: slidge.db.models.Room)

   Bases: :py:obj:`slidge.core.mixins.avatar.AvatarMixin`, :py:obj:`slidge.core.mixins.disco.ChatterDiscoMixin`, :py:obj:`slidge.core.mixins.recipient.RecipientMixin`, :py:obj:`slidge.util.util.SubclassableOnce`, :py:obj:`Generic`\ [\ :py:obj:`slidge.util.types.LegacyParticipantType`\ ]


   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:: 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:: 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:: pop_unread_xmpp_ids_up_to(horizon_xmpp_id: str) -> list[str]

      Return XMPP msg ids sent in this group up to a given XMPP msg id.

      Plugins 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: all messages up to the horizon XMPP id will be marked
      as read in the DB. If the horizon XMPP id is not found, all messages of this
      MUC will be marked as read.

      :param horizon_xmpp_id: The latest message
      :return: A list of XMPP ids if horizon_xmpp_id was not found



   .. py:method:: update_info() -> None
      :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(after: slidge.util.types.HoleBound | None = None, before: slidge.util.types.HoleBound | None = None) -> None
      :abstractmethod:

      :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``, slidge's local archive was empty before start-up,
          ie, no history was ever fetched for this room since the user registered.
          It's up to gateway implementations to decide how far to fetch messages before
          the user registered.
          If not ``None``, slidge has some messages in this archive, and
          the gateway shall try to fetch history up to (and excluding) this message
          to avoid "holes" in the history of this group.
      :param before: Fetch messages before this one.
          If ``None``, the gateway shall fetch all messages up to the most recent one.
          If not ``None``, slidge has already archived some live messages
          it received during its lifetime, and there is no need to query the legacy
          network for any message after (and including) this one.



   .. py:method:: fill_participants() -> collections.abc.AsyncIterator[slidge.util.types.LegacyParticipantType]
      :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:: get_user_participant(*, fill_first: bool = False, store: bool = True, occupant_id: str | None = None) -> slidge.util.types.LegacyParticipantType
      :async:


      Get the participant representing the gateway user

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



   .. py:method:: get_participant(nickname: str) -> slidge.util.types.LegacyParticipantType
                  get_participant(*, occupant_id: str) -> slidge.util.types.LegacyParticipantType
                  get_participant(*, occupant_id: str, create: Literal[False]) -> LegacyParticipantType | None
                  get_participant(*, occupant_id: str, create: Literal[True]) -> slidge.util.types.LegacyParticipantType
                  get_participant(nickname: str, *, occupant_id: str) -> slidge.util.types.LegacyParticipantType
                  get_participant(nickname: str, *, create: Literal[False]) -> LegacyParticipantType | None
                  get_participant(nickname: str, *, create: Literal[True]) -> slidge.util.types.LegacyParticipantType
                  get_participant(nickname: str, *, create: Literal[True], is_user: bool, fill_first: bool, store: bool) -> slidge.util.types.LegacyParticipantType
                  get_participant(nickname: str, *, create: Literal[False], is_user: bool, fill_first: bool, store: bool) -> LegacyParticipantType | None
                  get_participant(nickname: str, *, create: bool, fill_first: bool) -> LegacyParticipantType | None
                  get_participant(nickname: str, *, is_user: Literal[True], fill_first: bool, store: bool, occupant_id: str | None = None) -> slidge.util.types.LegacyParticipantType
      :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 create: By default, a participant is created if necessary. Set this to
          False to return None if participant was not created before.
      :param is_user: Whether this participant is the slidge user.
      :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 occupant_id: optionally, specify the unique ID for this participant, cf
          xep:`0421`
      :return: A participant of this room.



   .. py:method:: get_system_participant() -> slidge.util.types.LegacyParticipantType

      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: slidge.contact.contact.LegacyContact) -> slidge.util.types.LegacyParticipantType
                  get_participant_by_contact(c: slidge.contact.contact.LegacyContact, *, occupant_id: str | None = None) -> slidge.util.types.LegacyParticipantType
                  get_participant_by_contact(c: slidge.contact.contact.LegacyContact, *, create: Literal[False], occupant_id: str | None) -> LegacyParticipantType | None
                  get_participant_by_contact(c: slidge.contact.contact.LegacyContact, *, create: Literal[True], occupant_id: str | None) -> slidge.util.types.LegacyParticipantType
      :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 create: Creates the participant if it does not exist.
      :param occupant_id: Optionally, specify a unique occupant ID (:xep:`0421`) for
          this participant.
      :return:



   .. py:method:: remove_participant(p: slidge.util.types.LegacyParticipantType, kick: bool = False, ban: bool = False, reason: str | None = None) -> None

      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
      :param reason: Optionally, a reason why the participant was removed.



   .. py:method:: kick_resource(r: str) -> None
      :async:


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

      :param r: The resource to kick



   .. py:method:: add_to_bookmarks(auto_join: bool = True, preserve: bool = True, pin: bool | None = None, notify: slixmpp.plugins.xep_0492.stanza.WhenLiteral | None = None) -> None
      :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 preserve: preserve auto-join and bookmarks extensions
          set by the user outside slidge
      :param pin: Pin the group chat bookmark :xep:`0469`. Requires privileged entity.
          If set to ``None`` (default), the bookmark pinning status will be untouched.
      :param notify: Chat notification setting: :xep:`0492`. Requires privileged entity.
          If set to ``None`` (default), the setting will be untouched. Only the "global"
          notification setting is supported (ie, per client type is not possible).



   .. py:method:: on_avatar(data: bytes | None, mime: str | None) -> str | None
      :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_config(name: str | None, description: str | None) -> None
      :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:`LegacyMUC.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: str | None) -> None
      :abstractmethod:

      :async:


      Triggered when the user requests room destruction.

      :param reason: Optionally, a reason for the destruction



   .. py:method:: on_set_subject(subject: str) -> None
      :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:: on_set_thread_subject(thread: str, subject: str) -> None
      :abstractmethod:

      :async:


      Triggered when the user requests changing the subject of a specific thread.

      :param thread: Legacy identifier of the thread
      :param subject: The new subject for this thread.



   .. py:method:: on_moderate(legacy_msg_id: str, reason: str | None) -> None
      :abstractmethod:

      :async:


      Triggered when the user attempts to retract a message that was sent in
      a MUC using :xep:`0425`.

      If retraction is not possible, this should raise the appropriate
      XMPPError with a human-readable message.

      NB: the legacy module is responsible for calling
      :func:`LegacyParticipant.moderate` when this is successful, because
      slidge will acknowledge the moderation IQ, but will not send the
      moderation message from the MUC automatically.

      :param legacy_msg_id: The legacy ID of the message to be retracted
      :param reason: Optionally, a reason for the moderation, given by the
          user-moderator.



   .. py:method:: on_leave() -> None
      :abstractmethod:

      :async:


      Triggered when the user leaves a group via the dedicated slidge command
      or the :xep:`0077` ``<remove />`` mechanism.

      This should be interpreted as definitely leaving the group.



   .. py:method:: get_archived_messages(msg_id: str) -> collections.abc.Iterator[slidge.util.archive_msg.HistoryMessage]

      Query the slidge archive for messages sent in this group

      :param msg_id: Message ID of the message in question. Can be either a legacy ID
          or an XMPP ID.
      :return: Iterator over messages. A single legacy ID can map to several messages,
          because of multi-attachment messages.



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


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

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



   .. py:method:: set_avatar(avatar: slidge.util.types.Avatar | pathlib.Path | str | None = None, delete: bool = False) -> None
      :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() -> slidge.db.meta.JSONSerializable | None

      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: slidge.db.meta.JSONSerializable) -> None

      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:: available_emojis(legacy_msg_id: str | None = None) -> set[str] | None
      :abstractmethod:

      :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:method:: on_message(message: slidge.util.types.XMPPMessage) -> str | None
      :abstractmethod:

      :async:


      Triggered when the user sends a message to this :term:`Recipient`.



   .. py:method:: on_sticker(sticker: slidge.util.types.Sticker) -> str | None
      :abstractmethod:

      :async:


      Triggered when the user sends a sticker to this :term:`Recipient`.

      :param sticker: The sticker sent by the user.

      :return: An ID of some sort that can be used later to ack and mark the
          message as read by the user



   .. py:method:: on_chat_state(chat_state: slidge.util.types.ChatState, thread: str | None) -> None
      :abstractmethod:

      :async:


      Triggered when the user sends a chat state (:xep:`0085`) to this
      :term:`Recipient`.

      :param chat_state: The sticker sent by the user.



   .. py:method:: on_displayed(legacy_msg_id: str, thread: str | None) -> None
      :abstractmethod:

      :async:


      Triggered when the user sends a read marker (:xep:`0333`) to this
      :term:`Recipient`.

      This is only possible if a valid ``legacy_msg_id`` was passed when
      transmitting a message from a legacy chat to the user, eg in
      :meth:`slidge.contact.LegacyContact.send_text`
      or
      :meth:`slidge.group.LegacyParticipant.send_text`.

      :param legacy_msg_id: Identifier of the message/
      :param thread:



   .. py:method:: on_react(legacy_msg_id: str, emojis: list[str], thread: str | None) -> None
      :abstractmethod:

      :async:


      Triggered when the user sends an emoji reaction (:xep:`0444`) to
      this :term:`Recipient`.

      :param legacy_msg_id: ID of the message the user reacts to
      :param emojis: Unicode characters representing reactions to the message ``legacy_msg_id``.
          An empty list means "no reaction", ie, remove all reactions if any were present before
      :param thread:



   .. py:method:: on_retract(legacy_msg_id: str, thread: str | None) -> None
      :abstractmethod:

      :async:


      Triggered when the user retracts (:xep:`0424`) a message.

      :param legacy_msg_id: Legacy ID of the retracted message
      :param thread:



