slidge.room¶

Everything related to rooms.

Package Contents¶

class slidge.room.RoomType¶

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.room.LegacyBookmarks[RoomT: slidge.util.types.AnyRoom](session: slidge.util.types.AnySession)¶

This is instantiated once per BaseSession

abstractmethod on_creation_request(name: str, legacy_ids: list[str]) → str¶

Async:

Called when the user requests the creation of a room via the dedicated Command.

Parameters:

name – Name of the room.
legacy_ids – list of contacts legacy ids that should be members

of the new room.

Returns:: Legacy ID of the newly created room.

async remove(muc: slidge.util.types.AnyRoom, reason: str = 'You left this group from the official client.', kick: bool = True) → None¶

Delete everything about a specific group.

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

Parameters:

muc – The Room 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.

get(legacy_id: str) → ChildT | None¶: Get a Contact or Room that has been created before.

async create(legacy_id: str) → ChildT¶

Create a new Contact, Space or Space.

This must raise if legacy id does not map to something existing.

A typical pattern is to have a method constructing a Contact or a Room from a “metadata struct” provided by the legacy network, in the spirit of:

class LegacyRoster[Contact]:
    def create(self, legacy_id: str) -> Contact:
        meta = self._session.legacy_client.fetch_contact(legacy_id)
        if meta is None:
            raise XMPPError("item-not-found", f"No contact {legacy_id!r}")
        return await self.get_or_create_by_meta(meta)

    def get_or_create_by_meta(self, meta: legacy_lib.ContactMetadata) -> Contact:
        contact = self.get(meta.id) or self._create(legacy_id)
        contact.set_meta(meta)
        return contact

async get_or_create(legacy_id: str) → ChildT¶: Get an existing Recipient or create() it if it does not exist, by calling .

async fill() → collections.abc.AsyncIterator[ChildT]¶: This is called once on startup, and should yield recipients with updated metadata.

class slidge.room.LegacyParticipant[LegacyContactType: slidge.contact.LegacyContact, T: slidge.util.types.ExtraAttrMapping](muc: slidge.util.types.AnyRoom, stored: slidge.db.models.Participant, is_system: bool = False, contact: LegacyContactType | None = None)¶

A legacy participant of a legacy group chat.

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 Room, 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 – Set this to only send to a specific user XMPP resource.
nick_change – Used when the user joins and the Room renames them (code 210)
presence_id – set the presence ID. used internally by slidge

leave() → None¶: Call this when the participant leaves the room

kick(reason: str | None = None) → None¶: Call this when the participant is kicked from the room

ban(reason: str | None = None) → None¶: Call this when the participant is banned from the room

abstractmethod on_set_affiliation(affiliation: slidge.util.types.MucAffiliation, reason: str | None, nickname: str | None) → None¶

Async:

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

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

Parameters:

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

abstractmethod on_kick(reason: str | None) → None¶

Async:

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

Parameters:

contact – Contact to be kicked
reason – A reason for this kick

async on_invitation(reason: str | None) → None¶

Triggered when the user invites this Contact to a legacy Room via XEP-0249.

The default implementation calls LegacyRoom.on_set_affiliation() with the ‘member’ affiliation. Override if you want to customize this behaviour.

Parameters:

muc – The group
reason – Optionally, a reason

displayed(legacy_msg_id: str, **kwargs: object) → None¶

Send a “displayed” message marker (XEP-0333) from this XMPP Entity.

Parameters:: legacy_msg_id – The message this marker refers to

Send an invitation to join a group (XEP-0249) from this XMPP Entity.

Parameters:

muc – the muc the user is invited to
reason – a text explaining why the user should join this muc
password – maybe this will make sense later? not sure
session – session for the user being invited. Defaults to self._session and MUST be provided if that is None.
send_kwargs – additional kwargs to be passed to _send() (internal use by slidge)

active(**kwargs: object) → None¶: Send an “active” chat state (XEP-0085) from this XMPP Entity.

composing(**kwargs: object) → None¶: Send a “composing” (ie “typing notification”) chat state (XEP-0085) from this XMPP Entity.

paused(**kwargs: object) → None¶: Send a “paused” (ie “typing paused notification”) chat state (XEP-0085) from this XMPP Entity.

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

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

ack(legacy_msg_id: str, **kwargs: object) → None¶

Send an “acknowledged” message marker (XEP-0333) from this XMPP Entity.

Parameters:: legacy_msg_id – The message this marker refers to

received(legacy_msg_id: str, **kwargs: object) → None¶

Send a “received” message marker (XEP-0333) from this XMPP Entity. If called on a LegacyContact, also send a delivery receipt marker (XEP-0184).

Parameters:: legacy_msg_id – The message this marker refers to

Send a single file from this XMPP Entity.

Parameters:

attachment – The file to send. Ideally, a LegacyAttachment with a unique legacy_file_id attribute set, to optimise potential future reuses. It can also be: - a pathlib.Path instance to point to a local file, or - a str, representing a fetchable HTTP URL.
legacy_msg_id – If you want to be able to transport read markers from the gateway user to the legacy network, specify this
reply_to – Quote another message (XEP-0461)
when – when the file was sent, for a “delay” tag (XEP-0203)
thread

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, 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 XMPP Entity.

Parameters:

body – Content of the message
legacy_msg_id – If you want to be able to transport read markers from the gateway user to the legacy network, specify this
when – when the message was sent, for a “delay” tag (XEP-0203)
reply_to – Quote another message (XEP-0461)
hints
thread
carbon – (only used if called on a LegacyContact) Set this to True if this is actually a message sent to the LegacyContact by the User. Use this to synchronize outgoing history for legacy official apps.
correction – whether this message is a correction or not
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.
link_previews – A little of sender (or server, or gateway)-generated previews of URLs linked in the body.

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, 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 XMPP Entity.

Uses last message correction (XEP-0308)

Parameters:

new_text – New content of the message
legacy_msg_id – The legacy message ID of the message to correct
when – when the message was sent, for a “delay” tag (XEP-0203)
reply_to – Quote another message (XEP-0461)
hints
thread
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.
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.
link_previews – A little of sender (or server, or gateway)-generated previews of URLs linked in the body.

react(legacy_msg_id: str, emojis: collections.abc.Iterable[str] = (), thread: str | None = None, **kwargs: object) → None¶

Send a reaction (XEP-0444) from this XMPP Entity.

Parameters:

legacy_msg_id – The message which the reaction refers to.
emojis – An iterable of emojis used as reactions
thread

retract(legacy_msg_id: str, thread: str | None = None, **kwargs: object) → None¶

Send a message retraction (XEP-0424) from this XMPP Entity.

Parameters:

legacy_msg_id – Legacy ID of the message to delete
thread

class slidge.room.LegacyRoom[LegacyParticipantT: slidge.util.types.AnyParticipant, T: slidge.util.types.ExtraAttrMapping](session: slidge.core.session.BaseSession[Any, slidge.room.bookmarks.LegacyBookmarks[Self]], stored: slidge.db.models.Room)¶

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

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

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.

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.

abstractmethod on_message(message: slidge.util.types.RoomMessage[LegacyParticipantT]) → str | None¶

Async:

Triggered when the user sends a message to this Room.

Returns:: A message ID of that can be used later to further reference this message (reactions, read marks, etc.).

abstractmethod on_sticker(sticker: slidge.util.types.RoomSticker) → str | None¶

Async:

Triggered when the user sends a sticker to this Room.

Parameters:: sticker – The sticker sent by the user.
Returns:: A message ID of that can be used later to further reference this message (reactions, read marks, etc.).

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 Room will be marked as read.

Parameters:: horizon_xmpp_id – The latest message
Returns:: A list of XMPP ids if horizon_xmpp_id was not found

abstractmethod backfill(after: slidge.util.types.HoleBound | None = None, before: slidge.util.types.HoleBound | None = None) → None¶

Async:

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

In it, send history messages using self.participants.get_or_create(...).send_xxxx. This is only called once per slidge run for a given group.

Parameters:

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

async fill_participants() → collections.abc.AsyncIterator[LegacyParticipantT]¶

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

It will only be called once per-room, only when actually needed by an XMPP action (typically joining the room).

get_system_participant() → LegacyParticipantT¶

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:

remove_participant(p: LegacyParticipantT, kick: bool = False, ban: bool = False, reason: str | None = None) → None¶

Call this when a participant leaves the room

Parameters:

p – The participant
kick – Whether the participant left because they were kicked
ban – Whether the participant left because they were banned
reason – Optionally, a reason why the participant was removed.

async kick_resource(r: str) → None¶

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

Parameters:: r – The resource to kick

async remove_from_bookmarks() → None¶

Remove the Room from the user’s XMPP bookmarks (XEP-0402).

Does not actually leave the room on the legacy network, nor apply any other side-effect.

Requires that slidge has the IQ privileged set correctly on the XMPP server.

abstractmethod on_avatar(data: bytes | None, mime: str | None) → str | None¶

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 Room 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 – image data or None if the user meant to remove the avatar
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.

Returns:

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

abstractmethod on_set_config(name: str | None, description: str | None) → None¶

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

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

Parameters:

name – The new name of the room.
description – The new description of the room.

abstractmethod on_destroy_request(reason: str | None) → None¶

Async:

Triggered when the user requests room destruction.

Parameters:: reason – Optionally, a reason for the destruction

abstractmethod on_set_subject(subject: str) → None¶

Async:

Triggered when the user requests changing the room subject.

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

Parameters:: subject – The new subject for this room.

abstractmethod on_set_thread_subject(thread: str, subject: str) → None¶

Async:

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

Parameters:

thread – Legacy identifier of the thread
subject – The new subject for this thread.

abstractmethod on_moderate(legacy_msg_id: str, reason: str | None) → None¶

Async:

Triggered when the user attempts to retract a message that was sent in a Room 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 LegacyParticipant.moderate() when this is successful, because slidge will acknowledge the moderation IQ, but will not send the moderation message from the Room automatically.

Parameters:

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

abstractmethod on_leave() → None¶

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.

get_archived_messages(msg_id: str | list[str]) → collections.abc.Iterator[slidge.db.models.ArchivedMessage]¶

Query the slidge archive for messages sent in this group

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

property avatar: slidge.util.types.Avatar | None¶: This property can be used to set or unset the avatar.

abstractmethod available_emojis(legacy_msg_id: str | None = None) → set[str] | None¶

Async:

Override this to restrict the subset of reactions this recipient can handle.

Returns:: A set of emojis or None if any emoji is allowed

abstractmethod create_thread(xmpp_id: str, root_legacy_id: str) → str¶

Async:

Create a legacy thread rooted at an existing message.

Parameters:: root_legacy_id – legacy_id of the message which shall be the root of the thread.

abstractmethod on_chat_state(chat_state: slidge.util.types.ChatState, thread: str | None) → None¶

Async:

Triggered when the user sends a chat state (XEP-0085) to this Recipient.

Parameters:: chat_state – The sticker sent by the user.

abstractmethod on_displayed(legacy_msg_id: str, thread: str | None) → None¶

Async:

Triggered when the user sends a read marker (XEP-0333) to this 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 slidge.contact.LegacyContact.send_text() or slidge.group.LegacyParticipant.send_text().

Parameters:

legacy_msg_id – Identifier of the message/
thread

abstractmethod on_react(legacy_msg_id: str, emojis: list[str], thread: str | None) → None¶

Async:

Triggered when the user sends an emoji reaction (XEP-0444) to this Recipient.

Parameters:

legacy_msg_id – ID of the message the user reacts to
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
thread

abstractmethod on_retract(legacy_msg_id: str, thread: str | None) → None¶

Async:

Triggered when the user retracts (XEP-0424) a message.

Parameters:

legacy_msg_id – Legacy ID of the retracted message
thread