slidge.group

Everything related to groups.

Classes

MucType

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

LegacyBookmarks

This is instantiated once per BaseSession

LegacyParticipant

A legacy participant of a legacy group chat.

LegacyMUC

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

Package Contents

class slidge.group.MucType

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

GROUP = 0

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

CHANNEL = 1

A public group, aka an anonymous channel.

CHANNEL_NON_ANONYMOUS = 2

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

class slidge.group.LegacyBookmarks(session)

This is instantiated once per BaseSession

Parameters:

session (slidge.core.session.BaseSession)

async legacy_id_to_jid_username(legacy_id)

The default implementation calls str() on the legacy_id and escape characters according to XEP-0106.

You can override this class and implement a more subtle logic to raise an XMPPError early

Parameters:

legacy_id (slidge.util.types.LegacyGroupIdType)

Returns:

async jid_username_to_legacy_id(username)
Parameters:

username (str)

Returns:

abstract 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 BaseSession.login()

async remove(muc, reason='You left this group from the official client.', kick=True)

Delete everything about a specific group.

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

Parameters:
  • muc (slidge.group.room.LegacyMUC) – The MUC to remove.

  • reason – Optionally, a reason why this group was removed.

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

Return type:

None

class slidge.group.LegacyParticipant(muc, nickname=None, is_user=False, is_system=False, role='participant', affiliation='member')

A legacy participant of a legacy group chat.

Parameters:
  • muc (slidge.group.room.LegacyMUC)

  • nickname (Optional[str])

  • role (slidge.util.types.MucRole)

  • affiliation (slidge.util.types.MucAffiliation)

send_initial_presence(full_jid, nick_change=False, presence_id=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.

Parameters:
  • full_jid (slixmpp.JID) – Set this to only send to a specific user XMPP resource.

  • nick_change – Used when the user joins and the MUC renames them (code 210)

  • presence_id (Optional[str]) – set the presence ID. used internally by slidge

leave()

Call this when the participant leaves the room

kick(reason=None)

Call this when the participant is kicked from the room

Parameters:

reason (str | None)

ban(reason=None)

Call this when the participant is banned from the room

Parameters:

reason (str | None)

class slidge.group.LegacyMUC(session, legacy_id, jid)

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

MUC instances are obtained by calling slidge.group.bookmarks.LegacyBookmarks() on the user’s slidge.core.session.BaseSession.

Parameters:
  • session (slidge.core.session.BaseSession)

  • legacy_id (slidge.util.types.LegacyGroupIdType)

  • jid (slixmpp.JID)

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

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

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

HAS_SUBJECT = 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 User tries to set the room subject.

abstract 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 slidge.core.mixins.avatar.AvatarMixin.set_avatar() or attempt to modify the :attr:.avatar property.

abstract backfill(after=None, before=None)
Async:

Parameters:
  • after (Optional[slidge.util.types.HoleBound])

  • before (Optional[slidge.util.types.HoleBound])

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.

Parameters:
  • after (Optional[slidge.util.types.HoleBound]) – 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.

  • before (Optional[slidge.util.types.HoleBound]) – Fetch messages before this one. If None, fetch all messages up to the most recent one

async fill_participants()

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.

Return type:

AsyncIterator[slidge.group.participant.LegacyParticipant]

async get_user_participant(**kwargs)

Get the participant representing the gateway user

Parameters:

kwargs – additional parameters for the Participant construction (optional)

Returns:

Return type:

slidge.util.types.LegacyParticipantType

async get_participant(nickname, raise_if_not_found=False, fill_first=False, store=True, **kwargs)

Get a participant by their nickname.

In non-anonymous groups, you probably want to use LegacyMUC.get_participant_by_contact() instead.

Parameters:
  • nickname (str) – Nickname of the participant (used as resource part in the MUC)

  • 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)

  • fill_first – Ensure LegacyMUC.fill_participants() has been called first (internal use by slidge, plugins should not need that)

  • store – persistently store the user in the list of MUC participants

  • kwargs – additional parameters for the Participant construction (optional)

Returns:

Return type:

slidge.util.types.LegacyParticipantType

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:

Return type:

slidge.util.types.LegacyParticipantType

async get_participant_by_contact(c, **kwargs)

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

Parameters:
  • c (slidge.contact.contact.LegacyContact) – The LegacyContact instance corresponding to this contact

  • kwargs – additional parameters for the Participant construction (optional)

Returns:

Return type:

slidge.util.types.LegacyParticipantType

remove_participant(p, kick=False, ban=False, reason=None)

Call this when a participant leaves the room

Parameters:
  • p (slidge.util.types.LegacyParticipantType) – The participant

  • kick – Whether the participant left because they were kicked

  • ban – Whether the participant left because they were banned

  • reason (str | None) – Optionally, a reason why the participant was removed.

async kick_resource(r)

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

Parameters:

r (str) – The resource to kick

async add_to_bookmarks(auto_join=True, invite=False, preserve=True)

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

Parameters:
  • 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.

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

  • preserve – preserve auto-join and bookmarks extensions set by the user outside slidge

abstract on_avatar(data, mime)
Async:

Parameters:
  • data (Optional[bytes])

  • mime (Optional[str])

Return type:

Optional[Union[int, str]]

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.

Parameters:
  • data (Optional[bytes]) – image data or None if the user meant to remove the avatar

  • mime (Optional[str]) – the mime type of the image. Since this is provided by the XMPP client, there is no guarantee that this is valid or correct.

Returns:

A unique avatar identifier, which will trigger slidge.group.room.LegacyMUC.set_avatar(). Alternatively, None, if LegacyMUC.set_avatar() is meant to be awaited somewhere else.

Return type:

Optional[Union[int, str]]

abstract on_set_affiliation(contact, affiliation, reason, nickname)
Async:

Parameters:
  • contact (slidge.contact.contact.LegacyContact)

  • affiliation (slidge.util.types.MucAffiliation)

  • reason (Optional[str])

  • nickname (Optional[str])

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

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

Parameters:
  • contact (slidge.contact.contact.LegacyContact) – The contact whose affiliation change is requested

  • affiliation (slidge.util.types.MucAffiliation) – The new affiliation

  • reason (Optional[str]) – A reason for this affiliation change

  • nickname (Optional[str])

abstract on_kick(contact, reason)
Async:

Parameters:
  • contact (slidge.contact.contact.LegacyContact)

  • reason (Optional[str])

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

Parameters:
  • contact (slidge.contact.contact.LegacyContact) – Contact to be kicked

  • reason (Optional[str]) – A reason for this kick

abstract on_set_config(name, description)
Async:

Parameters:
  • name (Optional[str])

  • description (Optional[str])

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 title and/or description of this instance.

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

Parameters:
  • name (Optional[str]) – The new name of the room.

  • description (Optional[str]) – The new description of the room.

abstract on_destroy_request(reason)
Async:

Parameters:

reason (Optional[str])

Triggered when the user requests room destruction.

Parameters:

reason (Optional[str]) – Optionally, a reason for the destruction

abstract on_set_subject(subject)
Async:

Parameters:

subject (str)

Return type:

None

Triggered when the user requests changing the room subject.

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

Parameters:

subject (str) – The new subject for this room.

Return type:

None