slidge.group
#
Everything related to groups.
Package Contents#
Classes#
The type of group, private, public, anonymous or not. |
|
This is instantiated once per |
|
A legacy participant of a legacy group chat. |
|
A room, a.k.a. a Multi-User Chat. |
- 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:
- abstract async fill()#
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()
- class slidge.group.LegacyParticipant(muc, nickname=None, is_user=False, is_system=False)#
A legacy participant of a legacy group chat.
- Parameters:
muc (slidge.group.room.LegacyMUC) –
nickname (Optional[str]) –
- 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()#
Call this when the participant is kicked from the room
- ban()#
Call this when the participant is banned from the room
- online(status=None, last_seen=None)#
Send an “online” presence from this contact to the user.
- Parameters:
status (Optional[str]) – Arbitrary text, details of the status, eg: “Listening to Britney Spears”
last_seen (Optional[datetime.datetime]) – For XEP-0319
- away(status=None, last_seen=None)#
Send an “away” presence from this contact to the user.
This is a global status, as opposed to
LegacyContact.inactive()
which concerns a specific conversation, ie a specific “chat window”- Parameters:
status (Optional[str]) – Arbitrary text, details of the status, eg: “Gone to fight capitalism”
last_seen (Optional[datetime.datetime]) – For XEP-0319
- extended_away(status=None, last_seen=None)#
Send an “extended away” presence from this contact to the user.
This is a global status, as opposed to
LegacyContact.inactive()
which concerns a specific conversation, ie a specific “chat window”- Parameters:
status (Optional[str]) – Arbitrary text, details of the status, eg: “Gone to fight capitalism”
last_seen (Optional[datetime.datetime]) – For XEP-0319
- busy(status=None, last_seen=None)#
Send a “busy” (ie, “dnd”) presence from this contact to the user,
- Parameters:
status (Optional[str]) – eg: “Trying to make sense of XEP-0100”
last_seen (Optional[datetime.datetime]) – For XEP-0319
- offline(status=None, last_seen=None)#
Send an “offline” presence from this contact to the user.
- Parameters:
status (Optional[str]) – eg: “Trying to make sense of XEP-0100”
last_seen (Optional[datetime.datetime]) – For XEP-0319
- invite_to(muc, reason=None, password=None, **send_kwargs)#
Send an invitation to join a group (XEP-0249) from this XMPP Entity.
- Parameters:
muc (slidge.group.LegacyMUC) – the muc the user is invited to
reason (Optional[str]) – a text explaining why the user should join this muc
password (Optional[str]) – maybe this will make sense later? not sure
send_kwargs – additional kwargs to be passed to _send() (internal use by slidge)
- active(**kwargs)#
Send an “active” chat state (XEP-0085) from this XMPP Entity.
- composing(**kwargs)#
Send a “composing” (ie “typing notification”) chat state (XEP-0085) from this XMPP Entity.
- paused(**kwargs)#
Send a “paused” (ie “typing paused notification”) chat state (XEP-0085) from this XMPP Entity.
- inactive(**kwargs)#
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)#
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, **kwargs)#
Send an “acknowledged” message marker (XEP-0333) from this XMPP Entity.
- Parameters:
legacy_msg_id (slidge.util.types.LegacyMessageType) – The message this marker refers to
- received(legacy_msg_id, **kwargs)#
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 (slidge.util.types.LegacyMessageType) – The message this marker refers to
- displayed(legacy_msg_id, **kwargs)#
Send a “displayed” message marker (XEP-0333) from this XMPP Entity.
- Parameters:
legacy_msg_id (slidge.util.types.LegacyMessageType) – The message this marker refers to
- send_text(body, legacy_msg_id=None, *, when=None, reply_to=None, thread=None, hints=None, carbon=False, archive_only=False, correction=False, correction_event_id=None, link_previews=None, **send_kwargs)#
Send a text message from this XMPP Entity.
- Parameters:
body (str) – Content of the message
legacy_msg_id (Optional[slidge.util.types.LegacyMessageType]) – If you want to be able to transport read markers from the gateway user to the legacy network, specify this
when (Optional[datetime.datetime]) – when the message was sent, for a “delay” tag (XEP-0203)
reply_to (Optional[slidge.util.types.MessageReference]) – Quote another message (XEP-0461)
hints (Optional[Iterable[slidge.util.types.ProcessingHint]]) –
thread (Optional[slidge.util.types.LegacyThreadType]) –
carbon – (only used if called on a
LegacyContact
) Set this toTrue
if this is actually a message sent to theLegacyContact
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 (Optional[slidge.util.types.LegacyMessageType]) – 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 (Optional[list[slidge.util.types.LinkPreview]]) – A little of sender (or server, or gateway)-generated previews of URLs linked in the body.
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()
- correct(legacy_msg_id, new_text, *, when=None, reply_to=None, thread=None, hints=None, carbon=False, archive_only=False, correction_event_id=None, link_previews=None, **send_kwargs)#
Modify a message that was previously sent by this XMPP Entity.
Uses last message correction (XEP-0308)
- Parameters:
new_text (str) – New content of the message
legacy_msg_id (slidge.util.types.LegacyMessageType) – The legacy message ID of the message to correct
when (Optional[datetime.datetime]) – when the message was sent, for a “delay” tag (XEP-0203)
reply_to (Optional[slidge.util.types.MessageReference]) – Quote another message (XEP-0461)
hints (Optional[Iterable[slidge.util.types.ProcessingHint]]) –
thread (Optional[slidge.util.types.LegacyThreadType]) –
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.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()
correction_event_id (Optional[slidge.util.types.LegacyMessageType]) – 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 (Optional[list[slidge.util.types.LinkPreview]]) – A little of sender (or server, or gateway)-generated previews of URLs linked in the body.
- react(legacy_msg_id, emojis=(), thread=None, **kwargs)#
Send a reaction (XEP-0444) from this XMPP Entity.
- Parameters:
legacy_msg_id (slidge.util.types.LegacyMessageType) – The message which the reaction refers to.
emojis (Iterable[str]) – An iterable of emojis used as reactions
thread (Optional[slidge.util.types.LegacyThreadType]) –
- retract(legacy_msg_id, thread=None, **kwargs)#
Send a message retraction (XEP-0424) from this XMPP Entity.
- Parameters:
legacy_msg_id (slidge.util.types.LegacyMessageType) – Legacy ID of the message to delete
thread (Optional[slidge.util.types.LegacyThreadType]) –
- async send_file(file_path=None, legacy_msg_id=None, *, data_stream=None, data=None, file_url=None, file_name=None, content_type=None, reply_to=None, when=None, caption=None, legacy_file_id=None, thread=None, **kwargs)#
Send a single file from this XMPP Entity.
- Parameters:
file_path (Optional[Union[pathlib.Path, str]]) – Path to the attachment
data_stream (Optional[IO[bytes]]) – Alternatively, a stream of bytes (such as a File object)
data (Optional[bytes]) – Alternatively, a bytes object
file_url (Optional[str]) – Alternatively, a URL
file_name (Optional[str]) – How the file should be named.
content_type (Optional[str]) – MIME type, inferred from filename if not given
legacy_msg_id (Optional[slidge.util.types.LegacyMessageType]) – If you want to be able to transport read markers from the gateway user to the legacy network, specify this
reply_to (Optional[slidge.util.types.MessageReference]) – Quote another message (XEP-0461)
when (Optional[datetime.datetime]) – when the file was sent, for a “delay” tag (XEP-0203)
caption (Optional[str]) – an optional text that is linked to the file
legacy_file_id (Optional[Union[str, int]]) – A unique identifier for the file on the legacy network. Plugins should try their best to provide it, to avoid duplicates.
thread (Optional[slidge.util.types.LegacyThreadType]) –
- Return type:
- 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’sslidge.core.session.BaseSession
.- Parameters:
session (slidge.core.session.BaseSession) –
legacy_id (slidge.util.types.LegacyGroupIdType) –
jid (slixmpp.JID) –
- property avatar_id: slidge.util.types.AvatarIdType | None#
The unique ID of this entity’s avatar.
- Return type:
Optional[slidge.util.types.AvatarIdType]
- property avatar: slidge.util.types.AvatarIdType | None#
This property can be used to set the avatar, but
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.- Return type:
Optional[slidge.util.types.AvatarIdType]
- 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 callingfill_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 thefill_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 async update_info()#
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 async backfill(oldest_message_id=None, oldest_message_date=None)#
Override this if the legacy network provide server-side archive. In it, send history messages using
self.get_participant().send*
, with thearchive_only=True
kwarg.You only need to fetch messages older than
oldest_message_id
.- Parameters:
oldest_message_id (Optional[slidge.util.types.LegacyMessageType]) – The oldest message ID already present in the archive
oldest_message_date (Optional[datetime.datetime]) – The oldest message date already present in the archive
- abstract async fill_participants()#
In here, call self.get_participant(), self.get_participant_by_contact(), of self.get_user_participant() to make an initial list of participants.
- 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.LegacyContact) – The
LegacyContact
instance corresponding to this contactkwargs – additional parameters for the
Participant
construction (optional)
- Returns:
- Return type:
slidge.util.types.LegacyParticipantType
- async get_participants()#
Get all known participants of the group, ensure
LegacyMUC.fill_participants()
has been awaited once before. Plugins should not use that, internal slidge use only. :return:
- remove_participant(p, kick=False, ban=False)#
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
- 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 async on_avatar(data, mime)#
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:
- Returns:
A unique avatar identifier, which will trigger
slidge.group.room.LegacyMUC.set_avatar()
. Alternatively, None, ifLegacyMUC.set_avatar()
is meant to be awaited somewhere else.- Return type:
- abstract async on_set_affiliation(contact, affiliation, reason, nickname)#
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).
- Parameters:
contact (slidge.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 async on_set_config(name, description)#
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/ordescription
of this instance.If
HAS_DESCRIPTION
is set to False, description will always beNone
.
- abstract async on_destroy_request(reason)#
Triggered when the user requests room destruction.
- Parameters:
reason (Optional[str]) – Optionally, a reason for the destruction
- abstract async on_set_subject(subject)#
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
- async set_avatar(a, avatar_unique_id=None, blocking=False, cancel=True)#
Set an avatar for this entity
- Parameters:
a (Optional[slidge.util.types.AvatarType]) –
avatar_unique_id (Optional[slidge.util.types.LegacyFileIdType]) –
blocking –
cancel –
- Return type:
None