pep/slixmpp
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Merge branch 'muc-improvements-reloaded' into 'master'

Browse source 
Muc improvements reloaded

See merge request poezio/slixmpp!123
This commit is contained in:
mathieui 2021-02-08 23:11:08 +01:00
commit 1c4e06d510
7 changed files with 657 additions and 298 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
docs/api/plugins/xep_0045.rst
View file

@ -5,6 +5,7 @@ XEP-0045: Multi-User Chat
.. module:: slixmpp.plugins.xep_0045
.. autoclass:: XEP_0045
:member-order: bysource
:members:
:exclude-members: session_bind, plugin_init, plugin_end

4
docs/api/xmlstream/stanzabase.rst
View file

@ -99,8 +99,8 @@ of an interface defined by the parent.
.. seealso::
- :ref:`create-stanza-plugins`
- :ref:`create-extension-plugins`
- :ref:`override-parent-interfaces`
- :ref:`is_extension`
- :ref:`overrides`
Registering Stanza Plugins

2
docs/conf.py
View file

@ -51,7 +51,7 @@ master_doc = 'index'
# General information about the project.
project = u'Slixmpp'
year = datetime.datetime.now().year
copyright = u'{}, Nathan Fritz, Lance Stout'.format(year)
copyright = u'{}, Mathieu Pasquet, Maxime Buquet, Emmanuel Gil Peyrot, Florent Le Coz'.format(year)
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the

493
docs/event_index.rst
View file

@ -1,406 +1,581 @@
Event Index
===========
Slixmpp relies on events and event handlers to act on received data from
the server. Some of those events come from the very base of Slixmpp such
as :class:`~.BaseXMPP` or :class:`~.XMLStream`, while most of them are
emitted from plugins which add their own listeners.
There are often multiple events running for a single stanza, with
different levels of granularity, so code must take care of not
processing the same stanza twice.
.. glossary::
:sorted:
connected
- **Data:** ``{}``
- **Source:** :py:class:`~slixmpp.xmlstream.XMLstream`
- **Source:** :py:class:`~.xmlstream.XMLstream`
Signal that a connection has been made with the XMPP server, but a session
has not yet been established.
connection_failed
- **Data:** ``{}`` or ``Failure Stanza`` if available
- **Source:** :py:class:`~slixmpp.xmlstream.XMLstream`
- **Source:** :py:class:`~.xmlstream.XMLstream`
Signal that a connection can not be established after number of attempts.
changed_status
- **Data:** :py:class:`~slixmpp.Presence`
- **Source:** :py:class:`~slixmpp.roster.item.RosterItem`
- **Data:** :py:class:`~.Presence`
- **Source:** :py:class:`~.roster.item.RosterItem`
Triggered when a presence stanza is received from a JID with a show type
different than the last presence stanza from the same JID.
changed_subscription
- **Data:** :py:class:`~slixmpp.Presence`
- **Source:** :py:class:`~slixmpp.BaseXMPP`
- **Data:** :py:class:`~.Presence`
- **Source:** :py:class:`~.BaseXMPP`
Triggered whenever a presence stanza with a type of ``subscribe``,
``subscribed``, ``unsubscribe``, or ``unsubscribed`` is received.
Note that if the values ``xmpp.auto_authorize`` and ``xmpp.auto_subscribe``
are set to ``True`` or ``False``, and not ``None``, then Slixmpp will
are set to ``True`` or ``False``, and not ``None``, then will
either accept or reject all subscription requests before your event handlers
are called. Set these values to ``None`` if you wish to make more complex
subscription decisions.
chatstate_active
- **Data:** :py:class:`~slixmpp.Message`
- **Source:** :py:class:`~slixmpp.plugins.xep_0085.xep_0085`
- **Data:** :py:class:`~.Message`
- **Source:** :py:class:`~.XEP_0085`
When a message containing an ``<active/>`` chatstate is received.
chatstate_composing
- **Data:** :py:class:`~slixmpp.Message`
- **Source:** :py:class:`~slixmpp.plugins.xep_0085.xep_0085`
- **Data:** :py:class:`~.Message`
- **Source:** :py:class:`~.XEP_0085`
When a message containing a ``<composing/>`` chatstate is received.
chatstate_gone
- **Data:** :py:class:`~slixmpp.Message`
- **Source:** :py:class:`~slixmpp.plugins.xep_0085.xep_0085`
- **Data:** :py:class:`~.Message`
- **Source:** :py:class:`~.XEP_0085`
When a message containing a ``<gone/>`` chatstate is received.
chatstate_inactive
- **Data:** :py:class:`~slixmpp.Message`
- **Source:** :py:class:`~slixmpp.plugins.xep_0085.xep_0085`
- **Data:** :py:class:`~.Message`
- **Source:** :py:class:`~.XEP_0085`
When a message containing an ``<inactive/>`` chatstate is received.
chatstate_paused
- **Data:** :py:class:`~slixmpp.Message`
- **Source:** :py:class:`~slixmpp.plugins.xep_0085.xep_0085`
- **Data:** :py:class:`~.Message`
- **Source:** :py:class:`~.XEP_0085`
When a message containing a ``<paused/>`` chatstate is received.
disco_info
- **Data:** :py:class:`~slixmpp.plugins.xep_0030.stanza.DiscoInfo`
- **Source:** :py:class:`~slixmpp.plugins.xep_0030.disco.xep_0030`
- **Data:** :py:class:`~.DiscoInfo`
- **Source:** :py:class:`~.disco.XEP_0030`
Triggered whenever a ``disco#info`` result stanza is received.
disco_items
- **Data:** :py:class:`~slixmpp.plugins.xep_0030.stanza.DiscoItems`
- **Source:** :py:class:`~slixmpp.plugins.xep_0030.disco.xep_0030`
- **Data:** :py:class:`~.DiscoItems`
- **Source:** :py:class:`~.disco.XEP_0030`
Triggered whenever a ``disco#items`` result stanza is received.
disconnected
- **Data:** ``{}``
- **Source:** :py:class:`~slixmpp.xmlstream.XMLstream`
- **Data:** ``str``, the reason for the disconnect (if any)
- **Source:** :py:class:`~.XMLstream`
Signal that the connection with the XMPP server has been lost.
entity_time
- **Data:**
- **Source:**
failed_auth
- **Data:** ``{}``
- **Source:** :py:class:`~slixmpp.ClientXMPP`, :py:class:`~slixmpp.plugins.xep_0078.xep_0078`
- **Source:** :py:class:`~.ClientXMPP`, :py:class:`~.XEP_0078`
Signal that the server has rejected the provided login credentials.
gmail_notify
- **Data:** ``{}``
- **Source:** :py:class:`~slixmpp.plugins.gmail_notify.gmail_notify`
- **Source:** :py:class:`~.plugins.gmail_notify.gmail_notify`
Signal that there are unread emails for the Gmail account associated with the current XMPP account.
gmail_messages
- **Data:** :py:class:`~slixmpp.Iq`
- **Source:** :py:class:`~slixmpp.plugins.gmail_notify.gmail_notify`
- **Data:** :py:class:`~.Iq`
- **Source:** :py:class:`~.plugins.gmail_notify.gmail_notify`
Signal that there are unread emails for the Gmail account associated with the current XMPP account.
got_online
- **Data:** :py:class:`~slixmpp.Presence`
- **Source:** :py:class:`~slixmpp.roster.item.RosterItem`
- **Data:** :py:class:`~.Presence`
- **Source:** :py:class:`~.roster.item.RosterItem`
If a presence stanza is received from a JID which was previously marked as
offline, and the presence has a show type of '``chat``', '``dnd``', '``away``',
or '``xa``', then this event is triggered as well.
got_offline
- **Data:** :py:class:`~slixmpp.Presence`
- **Source:** :py:class:`~slixmpp.roster.item.RosterItem`
- **Data:** :py:class:`~.Presence`
- **Source:** :py:class:`~.roster.item.RosterItem`
Signal that an unavailable presence stanza has been received from a JID.
groupchat_invite
- **Data:** :py:class:`~slixmpp.Message`
- **Source:** :py:class:`~slixmpp.plugins.xep_0045.XEP_0045`
- **Data:** :py:class:`~.Message`
- **Source:** :py:class:`~.XEP_0045`
When a Mediated MUC invite is received.
groupchat_direct_invite
- **Data:** :py:class:`~slixmpp.Message`
- **Source:** :py:class:`~slixmpp.plugins.xep_0249.direct`
- **Data:** :py:class:`~.Message`
- **Source:** :py:class:`~.XEP_0249`
When a Direct MUC invite is received.
groupchat_message
- **Data:** :py:class:`~slixmpp.Message`
- **Source:** :py:class:`~slixmpp.plugins.xep_0045.xep_0045`
- **Data:** :py:class:`~.Message`
- **Source:** :py:class:`~.XEP_0045`
Triggered whenever a message is received from a multi-user chat room.
groupchat_presence
- **Data:** :py:class:`~slixmpp.Presence`
- **Source:** :py:class:`~slixmpp.plugins.xep_0045.xep_0045`
- **Data:** :py:class:`~.Presence`
- **Source:** :py:class:`~.XEP_0045`
Triggered whenever a presence stanza is received from a user in a multi-user chat room.
groupchat_subject
- **Data:** :py:class:`~slixmpp.Message`
- **Source:** :py:class:`~slixmpp.plugins.xep_0045.xep_0045`
- **Data:** :py:class:`~.Message`
- **Source:** :py:class:`~.XEP_0045`
Triggered whenever the subject of a multi-user chat room is changed, or announced when joining a room.
killed
- **Data:**
- **Source:**
- **Data:** ``{}``
- **Source:** :class:`~.XMLStream`
last_activity
- **Data:**
- **Source:**
When the stream is aborted.
message
- **Data:** :py:class:`~slixmpp.Message`
- **Source:** :py:class:`BaseXMPP <slixmpp.BaseXMPP>`
- **Data:** :py:class:`~.Message`
- **Source:** :py:class:`BaseXMPP <.BaseXMPP>`
Makes the contents of message stanzas available whenever one is received. Be
sure to check the message type in order to handle error messages.
message_error
- **Data:** :py:class:`~slixmpp.Message`
- **Source:** :py:class:`BaseXMPP <slixmpp.BaseXMPP>`
- **Data:** :py:class:`~.Message`
- **Source:** :py:class:`BaseXMPP <.BaseXMPP>`
Makes the contents of message stanzas available whenever one is received.
Only handler messages with an ``error`` type.
message_form
- **Data:** :py:class:`~slixmpp.plugins.xep_0004.Form`
- **Source:** :py:class:`~slixmpp.plugins.xep_0004.xep_0004`
- **Data:** :py:class:`~.Form`
- **Source:** :py:class:`~.XEP_0004`
Currently the same as :term:`message_xform`.
message_xform
- **Data:** :py:class:`~slixmpp.plugins.xep_0004.Form`
- **Source:** :py:class:`~slixmpp.plugins.xep_0004.xep_0004`
- **Data:** :py:class:`~.Form`
- **Source:** :py:class:`~.XEP_0004`
Triggered whenever a data form is received inside a message.
muc::[room]::got_offline
- **Data:** :py:class:`~slixmpp.Presence`
- **Source:** :py:class:`~slixmpp.plugins.xep_0045.XEP_0045`
- **Data:** :py:class:`~.Presence`
- **Source:** :py:class:`~.XEP_0045`
- **Name parameters:** ``room``, the room this is coming from.
Triggered whenever we receive an unavailable presence from a MUC occupant.
muc::[room]::got_online
- **Data:** :py:class:`~slixmpp.Presence`
- **Source:** :py:class:`~slixmpp.plugins.xep_0045.XEP_0045`
- **Data:** :py:class:`~.Presence`
- **Source:** :py:class:`~.XEP_0045`
- **Name parameters:** ``room``, the room this is coming from.
Triggered whenever we receive a presence from a MUC occupant
we do not have in the local cache.
muc::[room]::message
- **Data:** :py:class:`~slixmpp.Message`
- **Source:** :py:class:`~slixmpp.plugins.xep_0045.XEP_0045`
- **Data:** :py:class:`~.Message`
- **Source:** :py:class:`~.XEP_0045`
- **Name parameters:** ``room``, the room this is coming from.
Triggered whenever we receive a message from a MUC we are in.
muc::[room]::presence
- **Data:** :py:class:`~slixmpp.Presence`
- **Source:** :py:class:`~slixmpp.plugins.xep_0045.XEP_0045`
- **Data:** :py:class:`~.Presence`
- **Source:** :py:class:`~.XEP_0045`
- **Name parameters:** ``room``, the room this is coming from.
muc::[room]::self-presence
- **Data:** :class:`~.Presence`
- **Source:** :class:`~.XEP_0045`
- **Name parameters:** ``room``, the room this is coming from.
Triggered whenever we receive a presence with status code ``110``
(for example on MUC join, or nick change).
muc::[room]::presence-error
- **Data:** :class:`~.Presence`
- **Source:** :class:`~.XEP_0045`
- **Name parameters:** ``room``, the room this is coming from.
Triggered whenever we receive a presence of ``type="error"`` from
a MUC.
presence_available
- **Data:** :py:class:`~slixmpp.Presence`
- **Source:** :py:class:`~slixmpp.BaseXMPP`
- **Data:** :py:class:`~.Presence`
- **Source:** :py:class:`~.BaseXMPP`
A presence stanza with a type of '``available``' is received.
presence_error
- **Data:** :py:class:`~slixmpp.Presence`
- **Source:** :py:class:`~slixmpp.BaseXMPP`
- **Data:** :py:class:`~.Presence`
- **Source:** :py:class:`~.BaseXMPP`
A presence stanza with a type of '``error``' is received.
presence_form
- **Data:** :py:class:`~slixmpp.plugins.xep_0004.Form`
- **Source:** :py:class:`~slixmpp.plugins.xep_0004.xep_0004`
- **Data:** :py:class:`~.Form`
- **Source:** :py:class:`~.XEP_0004`
This event is present in the XEP-0004 plugin code, but is currently not used.
presence_probe
- **Data:** :py:class:`~slixmpp.Presence`
- **Source:** :py:class:`~slixmpp.BaseXMPP`
- **Data:** :py:class:`~.Presence`
- **Source:** :py:class:`~.BaseXMPP`
A presence stanza with a type of '``probe``' is received.
presence_subscribe
- **Data:** :py:class:`~slixmpp.Presence`
- **Source:** :py:class:`~slixmpp.BaseXMPP`
- **Data:** :py:class:`~.Presence`
- **Source:** :py:class:`~.BaseXMPP`
A presence stanza with a type of '``subscribe``' is received.
presence_subscribed
- **Data:** :py:class:`~slixmpp.Presence`
- **Source:** :py:class:`~slixmpp.BaseXMPP`
- **Data:** :py:class:`~.Presence`
- **Source:** :py:class:`~.BaseXMPP`
A presence stanza with a type of '``subscribed``' is received.
presence_unavailable
- **Data:** :py:class:`~slixmpp.Presence`
- **Source:** :py:class:`~slixmpp.BaseXMPP`
- **Data:** :py:class:`~.Presence`
- **Source:** :py:class:`~.BaseXMPP`
A presence stanza with a type of '``unavailable``' is received.
presence_unsubscribe
- **Data:** :py:class:`~slixmpp.Presence`
- **Source:** :py:class:`~slixmpp.BaseXMPP`
- **Data:** :py:class:`~.Presence`
- **Source:** :py:class:`~.BaseXMPP`
A presence stanza with a type of '``unsubscribe``' is received.
presence_unsubscribed
- **Data:** :py:class:`~slixmpp.Presence`
- **Source:** :py:class:`~slixmpp.BaseXMPP`
- **Data:** :py:class:`~.Presence`
- **Source:** :py:class:`~.BaseXMPP`
A presence stanza with a type of '``unsubscribed``' is received.
roster_update
- **Data:** :py:class:`~slixmpp.stanza.Roster`
- **Source:** :py:class:`~slixmpp.ClientXMPP`
- **Data:** :py:class:`~.Roster`
- **Source:** :py:class:`~.ClientXMPP`
An IQ result containing roster entries is received.
sent_presence
- **Data:** ``{}``
- **Source:** :py:class:`~slixmpp.roster.multi.Roster`
- **Source:** :py:class:`~.roster.multi.Roster`
Signal that an initial presence stanza has been written to the XML stream.
session_end
- **Data:** ``{}``
- **Source:** :py:class:`~slixmpp.xmlstream.XMLstream`
- **Source:** :py:class:`~.xmlstream.XMLstream`
Signal that a connection to the XMPP server has been lost and the current
stream session has ended. Currently equivalent to :term:`disconnected`, but
implementations of `XEP-0198: Stream Management <http://xmpp.org/extensions/xep-0198.html>`_
distinguish between the two events.
stream session has ended. Equivalent to :term:`disconnected`, unless the
`XEP-0198: Stream Management <http://xmpp.org/extensions/xep-0198.html>`_
plugin is loaded.
Plugins that maintain session-based state should clear themselves when
this event is fired.
session_start
- **Data:** ``{}``
- **Source:** :py:class:`ClientXMPP <slixmpp.ClientXMPP>`,
:py:class:`ComponentXMPP <slixmpp.ComponentXMPP>`
:py:class:`XEP-0078 <slixmpp.plugins.xep_0078>`
- **Source:** :py:class:`.ClientXMPP`,
:py:class:`~.ComponentXMPP`,
:py:class:`~.XEP-0078`
Signal that a connection to the XMPP server has been made and a session has been established.
session_resumed
- **Data:** ``{}``
- **Source:** :class:`~.XEP_0198`
When Stream Management manages to resume an ongoing session
after reconnecting.
socket_error
- **Data:** ``Socket`` exception object
- **Source:** :py:class:`~slixmpp.xmlstream.XMLstream`
- **Source:** :py:class:`~.xmlstream.XMLstream`
stream_error
- **Data:** :py:class:`~slixmpp.stanza.StreamError`
- **Source:** :py:class:`~slixmpp.BaseXMPP`
- **Data:** :py:class:`~.StreamError`
- **Source:** :py:class:`~.BaseXMPP`
reactions
- **Data:** :py:class:`~slixmpp.Message`
- **Source:** :py:class:`~slixmpp.plugins.xep_0444.XEP_0444`
- **Data:** :py:class:`~.Message`
- **Source:** :py:class:`~.XEP_0444`
When a message containing reactions is received.
carbon_received
- **Data:** :py:class:`~slixmpp.Message`
- **Source:** :py:class:`~slixmpp.plugins.xep_0280.XEP_0280`
- **Data:** :py:class:`~.Message`
- **Source:** :py:class:`~.XEP_0280`
When a carbon for a received message is received.
carbon_sent
- **Data:** :py:class:`~slixmpp.Message`
- **Source:** :py:class:`~slixmpp.plugins.xep_0280.XEP_0280`
- **Data:** :py:class:`~.Message`
- **Source:** :py:class:`~.XEP_0280`
When a carbon for a sent message (from another of our resources) is received.
marker
- **Data:** :py:class:`~slixmpp.Message`
- **Source:** :py:class:`~slixmpp.plugins.xep_0333.XEP_0333`
- **Data:** :py:class:`~.Message`
- **Source:** :py:class:`~.XEP_0333`
Whenever a chat marker is received (any of them).
marker_received
- **Data:** :py:class:`~slixmpp.Message`
- **Source:** :py:class:`~slixmpp.plugins.xep_0333.XEP_0333`
- **Data:** :py:class:`~.Message`
- **Source:** :py:class:`~.XEP_0333`
Whenever a ``<received/>`` chat marker is received.
marker_displayed
- **Data:** :py:class:`~slixmpp.Message`
- **Source:** :py:class:`~slixmpp.plugins.xep_0333.XEP_0333`
- **Data:** :py:class:`~.Message`
- **Source:** :py:class:`~.XEP_0333`
Whenever a ``<displayed/>`` chat marker is received.
marker_acknowledged
- **Data:** :py:class:`~slixmpp.Message`
- **Source:** :py:class:`~slixmpp.plugins.xep_0333.XEP_0333`
- **Data:** :py:class:`~.Message`
- **Source:** :py:class:`~.XEP_0333`
Whenever an ``<acknowledged/>`` chat marker is received.
attention
- **Data:** :py:class:`~slixmpp.Message`
- **Source:** :py:class:`~slixmpp.plugins.xep_0224.XEP_0224`
- **Data:** :py:class:`~.Message`
- **Source:** :py:class:`~.XEP_0224`
Whenever a message containing an attention payload is received.
message_correction
- **Data:** :py:class:`~slixmpp.Message`
- **Source:** :py:class:`~slixmpp.plugins.xep_0308.XEP_0308`
- **Data:** :py:class:`~.Message`
- **Source:** :py:class:`~.XEP_0308`
Whenever a message containing a correction is received.
receipt_received
- **Data:** :py:class:`~slixmpp.Message`
- **Source:** :py:class:`~slixmpp.plugins.xep_0184.XEP_0184`
- **Data:** :py:class:`~.Message`
- **Source:** :py:class:`~.XEP_0184`
Whenever a message receipt is received.
jingle_message_propose
- **Data:** :py:class:`~slixmpp.Message`
- **Source:** :py:class:`~slixmpp.plugins.xep_0353.XEP_0353`
- **Data:** :py:class:`~.Message`
- **Source:** :py:class:`~.XEP_0353`
jingle_message_retract
- **Data:** :py:class:`~slixmpp.Message`
- **Source:** :py:class:`~slixmpp.plugins.xep_0353.XEP_0353`
- **Data:** :py:class:`~.Message`
- **Source:** :py:class:`~.XEP_0353`
jingle_message_accept
- **Data:** :py:class:`~slixmpp.Message`
- **Source:** :py:class:`~slixmpp.plugins.xep_0353.XEP_0353`
- **Data:** :py:class:`~.Message`
- **Source:** :py:class:`~.XEP_0353`
jingle_message_proceed
- **Data:** :py:class:`~slixmpp.Message`
- **Source:** :py:class:`~slixmpp.plugins.xep_0353.XEP_0353`
- **Data:** :py:class:`~.Message`
- **Source:** :py:class:`~.XEP_0353`
jingle_message_reject
- **Data:** :py:class:`~slixmpp.Message`
- **Source:** :py:class:`~slixmpp.plugins.xep_0353.XEP_0353`
- **Data:** :py:class:`~.Message`
- **Source:** :py:class:`~.XEP_0353`
room_activity
- **Data:** :py:class:`~slixmpp.Presence`
- **Source:** :py:class:`~slixmpp.plugins.xep_0437.XEP_0437`
- **Data:** :py:class:`~.Presence`
- **Source:** :py:class:`~.XEP_0437`
When a room activity stanza is received by a client.
room_activity_bare
- **Data:** :py:class:`~slixmpp.Presence`
- **Source:** :py:class:`~slixmpp.plugins.xep_0437.XEP_0437`
- **Data:** :py:class:`~.Presence`
- **Source:** :py:class:`~.XEP_0437`
When an empty room activity stanza is received
(typically by a component).
sm_enabled
- **Data:** :py:class:`~slixmpp.plugins.xep_0198.stanza.Enabled`
- **Source:** :py:class:`~slixmpp.plugins.xep_0198.XEP_0198`
- **Data:** :py:class:`~.stanza.Enabled`
- **Source:** :py:class:`~.XEP_0198`
When Stream Management is successfully enabled.
sm_disabled
- **Data:**
- **Source:** :py:class:`~slixmpp.plugins.xep_0198.XEP_0198`
- **Data:** ``{}``
- **Source:** :py:class:`~.XEP_0198`
When Stream Management gets disabled (when disconnected).
ibb_stream_start
- **Data:** :py:class:`~slixmpp.plugins.xep_0047.stream.IBBBytestream`
- **Source:** :py:class:`~slixmpp.plugins.xep_0047.XEP_0047`
- **Data:** :py:class:`~.stream.IBBBytestream`
- **Source:** :py:class:`~.XEP_0047`
When a stream is successfully opened with a remote peer.
ibb_stream_end
- **Data:** :py:class:`~slixmpp.plugins.xep_0047.stream.IBBBytestream`
- **Source:** :py:class:`~slixmpp.plugins.xep_0047.XEP_0047`
- **Data:** :py:class:`~.stream.IBBBytestream`
- **Source:** :py:class:`~.XEP_0047`
When an opened stream closes.
ibb_stream_data
- **Data:** :py:class:`~slixmpp.plugins.xep_0047.stream.IBBBytestream`
- **Source:** :py:class:`~slixmpp.plugins.xep_0047.XEP_0047`
- **Data:** :py:class:`~.stream.IBBBytestream`
- **Source:** :py:class:`~.XEP_0047`
When data is received on an opened stream.
stream:[stream id]:[peer jid]
- **Data:** :py:class:`~slixmpp.plugins.xep_0047.stream.IBBBytestream`
- **Source:** :py:class:`~slixmpp.plugins.xep_0047.XEP_0047`
- **Data:** :py:class:`~.stream.IBBBytestream`
- **Source:** :py:class:`~.XEP_0047`
- **Name parameters:** ``stream id``, the id of the stream,
and ``peer jid`` the JID of the entity the stream is established
with.
When a stream is opened (with specific sid and jid parameters).
command
- **Data:** :py:class:`~slixmpp.Iq`
- **Source:** :py:class:`~slixmpp.plugins.xep_0050.XEP_0050`
- **Data:** :py:class:`~.Iq`
- **Source:** :py:class:`~.XEP_0050`
When an ad-hoc command is received.
command_[action]
- **Data:** :py:class:`~slixmpp.Iq`
- **Source:** :py:class:`~slixmpp.plugins.xep_0050.XEP_0050`
- **Data:** :py:class:`~.Iq`
- **Source:** :py:class:`~.XEP_0050`
- **Name parameters:** ``action``, the action referenced in
the command payload.
When a command with the specific action is received.
pubsub_publish
- **Data:** :py:class:`~slixmpp.Message`
- **Source:** :py:class:`~slixmpp.plugins.xep_0060.XEP_0060`
- **Data:** :py:class:`~.Message`
- **Source:** :py:class:`~.XEP_0060`
When a pubsub event of type ``publish`` is received.
pubsub_retract
- **Data:** :py:class:`~slixmpp.Message`
- **Source:** :py:class:`~slixmpp.plugins.xep_0060.XEP_0060`
- **Data:** :py:class:`~.Message`
- **Source:** :py:class:`~.XEP_0060`
When a pubsub event of type ``retract`` is received.
pubsub_purge
- **Data:** :py:class:`~slixmpp.Message`
- **Source:** :py:class:`~slixmpp.plugins.xep_0060.XEP_0060`
- **Data:** :py:class:`~.Message`
- **Source:** :py:class:`~.XEP_0060`
When a pubsub event of type ``purge`` is received.
pubsub_delete
- **Data:** :py:class:`~slixmpp.Message`
- **Source:** :py:class:`~slixmpp.plugins.xep_0060.XEP_0060`
- **Data:** :py:class:`~.Message`
- **Source:** :py:class:`~.XEP_0060`
When a pubsub event of type ``delete`` is received.
pubsub_config
- **Data:** :py:class:`~slixmpp.Message`
- **Source:** :py:class:`~slixmpp.plugins.xep_0060.XEP_0060`
- **Data:** :py:class:`~.Message`
- **Source:** :py:class:`~.XEP_0060`
When a pubsub event of type ``config`` is received.
pubsub_subscription
- **Data:** :py:class:`~slixmpp.Message`
- **Source:** :py:class:`~slixmpp.plugins.xep_0060.XEP_0060`
- **Data:** :py:class:`~.Message`
- **Source:** :py:class:`~.XEP_0060`
When a pubsub event of type ``subscription`` is received.
Dedicated PubSub Events
=======================
The :class:`~.XEP_0060` plugin (and :class:`~.XEP_0163` plugin, which uses
the former) allows other plugins to map specific namespaces in
PubSub notifications to a dedicated name prefix.
The current list of plugin prefixes is the following:
- ``bookmarks``: :class:`~.XEP_0048`
- ``user_location``: :class:`~.XEP_0080`
- ``avatar_metadata``: :class:`~.XEP_0084`
- ``avatar_data``: :class:`~.XEP_0084`
- ``user_mood``: :class:`~.XEP_0107`
- ``user_activity``: :class:`~.XEP_0108`
- ``user_tune``: :class:`~.XEP_0118`
- ``reachability``: :class:`~.XEP_0152`
- ``user_nick``: :class:`~.XEP_0163`
- ``user_gaming``: :class:`~.XEP_0196`
- ``mix_participant_info``: :class:`~.XEP_0369`
- ``mix_channel_info``: :class:`~.XEP_0369`
.. glossary::
:sorted:
[plugin]_publish
- **Data:** :py:class:`~.Message`
- **Source:** :py:class:`~.XEP_0060`
When a pubsub event of type ``publish`` is received.
[plugin]_retract
- **Data:** :py:class:`~.Message`
- **Source:** :py:class:`~.XEP_0060`
When a pubsub event of type ``retract`` is received.
[plugin]_purge
- **Data:** :py:class:`~.Message`
- **Source:** :py:class:`~.XEP_0060`
When a pubsub event of type ``purge`` is received.
[plugin]_delete
- **Data:** :py:class:`~.Message`
- **Source:** :py:class:`~.XEP_0060`
When a pubsub event of type ``delete`` is received.
[plugin]_config
- **Data:** :py:class:`~.Message`
- **Source:** :py:class:`~.XEP_0060`
When a pubsub event of type ``config`` is received.
[plugin]_subscription
- **Data:** :py:class:`~.Message`
- **Source:** :py:class:`~.XEP_0060`
When a pubsub event of type ``subscription`` is received.

5
docs/howto/stanzas.rst
View file

@ -327,6 +327,9 @@ Which will produces the following:
We can see that ``bool_interfaces`` allows to quickly create sub-elements with no
content, without the need to create a custom class or getter/setter.
.. _overrides:
overrides
~~~~~~~~~
@ -350,6 +353,8 @@ parent ``interfaces`` with the same name.
parent = Parent()
parent['toto'] = 'test' # equivalent to parent['sub']['toto'] = "test"
.. _is_extension:
is_extension
~~~~~~~~~~~~

415
slixmpp/plugins/xep_0045/muc.py
View file

@ -9,6 +9,7 @@ import asyncio
import logging
from datetime import datetime
from typing import (
Any,
Dict,
List,
Tuple,
@ -29,6 +30,7 @@ from slixmpp.xmlstream.matcher.stanzapath import StanzaPath
from slixmpp.xmlstream.matcher.xmlmask import MatchXMLMask
from slixmpp.exceptions import IqError, IqTimeout, PresenceError
from slixmpp.plugins.xep_0004 import Form
from slixmpp.plugins.xep_0045 import stanza
from slixmpp.plugins.xep_0045.stanza import (
MUCInvite,
@ -45,6 +47,13 @@ from slixmpp.plugins.xep_0045.stanza import (
MUCActor,
MUCUserItem,
)
from slixmpp.types import (
MucRole,
MucAffiliation,
MucRoomItem,
MucRoomItemKeys,
PresenceArgs,
)
log = logging.getLogger(__name__)
@ -56,7 +65,7 @@ ROLES = ('moderator', 'participant', 'visitor', 'none')
class XEP_0045(BasePlugin):
"""
Implements XEP-0045 Multi-User Chat
XEP-0045 Multi-User Chat
"""
name = 'xep_0045'
@ -64,6 +73,9 @@ class XEP_0045(BasePlugin):
dependencies = {'xep_0030', 'xep_0004'}
stanza = stanza
rooms: Dict[JID, Dict[str, MucRoomItem]]
our_nicks: Dict[JID, str]
def plugin_init(self):
self.rooms = {}
self.our_nicks = {}
@ -82,6 +94,7 @@ class XEP_0045(BasePlugin):
register_stanza_plugin(Iq, MUCAdminQuery)
register_stanza_plugin(Iq, MUCOwnerQuery)
register_stanza_plugin(MUCOwnerQuery, MUCOwnerDestroy)
register_stanza_plugin(MUCOwnerQuery, Form)
register_stanza_plugin(MUCAdminQuery, MUCAdminItem, iterable=True)
# Register handlers
@ -89,7 +102,7 @@ class XEP_0045(BasePlugin):
Callback(
'MUCPresence',
StanzaPath("presence/muc"),
self.handle_groupchat_presence,
self._handle_groupchat_presence,
))
# <x xmlns="http://jabber.org/protocol/muc"/> is only used in
# presence when joining on the client side, and for errors on
@ -99,7 +112,7 @@ class XEP_0045(BasePlugin):
Callback(
'MUCPresenceJoin',
StanzaPath("presence/muc_join"),
self.handle_groupchat_join,
self._handle_groupchat_join,
))
self.xmpp.register_handler(
Callback(
@ -113,37 +126,37 @@ class XEP_0045(BasePlugin):
Callback(
'MUCError',
MatchXMLMask("<message xmlns='%s' type='error'><error/></message>" % self.xmpp.default_ns),
self.handle_groupchat_error_message
self._handle_groupchat_error_message
))
self.xmpp.register_handler(
Callback(
'MUCMessage',
MatchXMLMask("<message xmlns='%s' type='groupchat'><body/></message>" % self.xmpp.default_ns),
self.handle_groupchat_message
self._handle_groupchat_message
))
self.xmpp.register_handler(
Callback(
'MUCSubject',
MatchXMLMask("<message xmlns='%s' type='groupchat'><subject/></message>" % self.xmpp.default_ns),
self.handle_groupchat_subject
self._handle_groupchat_subject
))
self.xmpp.register_handler(
Callback(
'MUCConfig',
StanzaPath('message/muc/status'),
self.handle_config_change
self._handle_config_change
))
self.xmpp.register_handler(
Callback(
'MUCInvite',
StanzaPath('message/muc/invite'),
self.handle_groupchat_invite
self._handle_groupchat_invite
))
self.xmpp.register_handler(
Callback(
'MUCDecline',
StanzaPath('message/muc/decline'),
self.handle_groupchat_decline
self._handle_groupchat_decline
))
def plugin_end(self):
@ -152,7 +165,7 @@ class XEP_0045(BasePlugin):
def session_bind(self, jid):
self.xmpp.plugin['xep_0030'].add_feature(stanza.NS)
def handle_groupchat_invite(self, inv):
def _handle_groupchat_invite(self, inv: Message):
""" Handle an invite into a muc. """
if self.xmpp.is_component:
self.xmpp.event('groupchat_invite', inv)
@ -160,7 +173,7 @@ class XEP_0045(BasePlugin):
if inv['from'] not in self.rooms.keys():
self.xmpp.event("groupchat_invite", inv)
def handle_groupchat_decline(self, decl):
def _handle_groupchat_decline(self, decl: Message):
"""Handle an invitation decline."""
if self.xmpp.is_component:
self.xmpp.event('groupchat_invite', decl)
@ -168,12 +181,12 @@ class XEP_0045(BasePlugin):
if decl['from'] in self.room.keys():
self.xmpp.event('groupchat_decline', decl)
def handle_config_change(self, msg):
def _handle_config_change(self, msg: Message):
"""Handle a MUC configuration change (with status code)."""
self.xmpp.event('groupchat_config_status', msg)
self.xmpp.event('muc::%s::config_status' % msg['from'].bare , msg)
def client_handle_presence(self, pr: Presence):
def _client_handle_presence(self, pr: Presence):
"""As a client, handle a presence stanza"""
got_offline = False
got_online = False
@ -206,61 +219,47 @@ class XEP_0045(BasePlugin):
"""Generate MUC presence error events"""
self.xmpp.event("muc::%s::presence-error" % pr['from'].bare, pr)
def handle_groupchat_presence(self, pr: Presence):
def _handle_groupchat_presence(self, pr: Presence):
""" Handle a presence in a muc."""
if self.xmpp.is_component:
self.xmpp.event('groupchat_presence', pr)
else:
self.client_handle_presence(pr)
self._client_handle_presence(pr)
def handle_groupchat_join(self, pr: Presence):
def _handle_groupchat_join(self, pr: Presence):
"""Received a join presence (as a component)"""
self.xmpp.event('groupchat_join', pr)
def handle_groupchat_message(self, msg: Message) -> None:
def _handle_groupchat_message(self, msg: Message):
""" Handle a message event in a muc.
"""
self.xmpp.event('groupchat_message', msg)
self.xmpp.event("muc::%s::message" % msg['from'].bare, msg)
def handle_groupchat_error_message(self, msg):
def _handle_groupchat_error_message(self, msg: Message):
""" Handle a message error event in a muc.
"""
self.xmpp.event('groupchat_message_error', msg)
self.xmpp.event("muc::%s::message_error" % msg['from'].bare, msg)
def handle_groupchat_subject(self, msg: Message) -> None:
def _handle_groupchat_subject(self, msg: Message):
""" Handle a message coming from a muc indicating
a change of subject (or announcing it when joining the room)
"""
# See poezio#3452. A message containing subject _and_ (body or thread)
# is not a subject change.
if msg['body'] or msg['thread']:
return None
return
self.xmpp.event('groupchat_subject', msg)
def jid_in_room(self, room: JID, jid: JID) -> bool:
for nick in self.rooms[room]:
entry = self.rooms[room][nick]
if entry is not None and entry['jid'].full == jid:
return True
return False
def get_nick(self, room: JID, jid: JID) -> Optional[str]:
for nick in self.rooms[room]:
entry = self.rooms[room][nick]
if entry is not None and entry['jid'].full == jid:
return nick
return None
async def join_muc_wait(self, room: JID, nick: str, *,
password: Optional[str] = None,
maxchars: Optional[int] = None,
maxstanzas: Optional[int] = None,
seconds: Optional[int] = None,
since: Optional[datetime] = None,
presence_options: Optional[Dict[str, str]] = None,
presence_options: Optional[PresenceArgs] = None,
timeout: Optional[int] = None) -> Presence:
"""
Try to join a MUC and block until we are joined or get an error.
@ -268,6 +267,8 @@ class XEP_0045(BasePlugin):
Only one of {maxchars, maxstanzas, seconds, since} will be used, in
that order.
.. versionadded:: 1.8.0
:param password: The optional room password.
:param maxchars: Max number of characters to return from history.
:param maxstanzas: Max number of stanzas to return from history.
@ -303,7 +304,7 @@ class XEP_0045(BasePlugin):
self.our_nicks[room] = nick
stanza.send()
future = asyncio.Future()
future: asyncio.Future = asyncio.Future()
context1 = self.xmpp.event_handler("muc::%s::self-presence" % room, future.set_result)
context2 = self.xmpp.event_handler("muc::%s::presence-error" % room, future.set_result)
with context1, context2:
@ -321,35 +322,118 @@ class XEP_0045(BasePlugin):
return pres
def join_muc(self, room: JID, nick: str, maxhistory="0", password='',
pstatus='', pshow='', pfrom=''):
pstatus='', pshow='', pfrom='') -> asyncio.Future:
""" Join the specified room, requesting 'maxhistory' lines of history.
.. deprecated:: 1.8.0
:meth:`join_muc_wait` will replace this old API starting from version
1.9.0.
"""
stanza = self.xmpp.make_presence(
pto="%s/%s" % (room, nick), pstatus=pstatus,
pshow=pshow, pfrom=pfrom
presence_options = PresenceArgs(
pshow=pshow,
pstatus=pstatus,
pfrom=pfrom,
)
stanza.enable('muc_join')
if password:
stanza['muc_join']['password'] = password
maxchars, maxstanzas = None, None
if maxhistory:
if maxhistory == "0":
stanza['muc_join']['history']['maxchars'] = '0'
maxchars = 9
else:
stanza['muc_join']['history']['maxstanzas'] = str(maxhistory)
self.xmpp.send(stanza)
self.rooms[room] = {}
self.our_nicks[room] = nick
maxstanzas = int(maxhistory)
return asyncio.ensure_future(
self.join_muc_wait(
room=room,
nick=nick,
password=password,
presence_options=presence_options,
maxchars=maxchars,
maxstanzas=maxstanzas,
),
loop=self.xmpp.loop,
)
def leave_muc(self, room: JID, nick: str, msg: str = '', pfrom: Optional[JID] = None):
""" Leave the specified room.
:param room: Room to leave.
:param nick: Your nickname.
:param msg: Presence status to use.
"""
if msg:
self.xmpp.send_presence(
pshow='unavailable',
pto="%s/%s" % (room, nick),
pstatus=msg,
pfrom=pfrom
)
else:
self.xmpp.send_presence(
pshow='unavailable',
pto="%s/%s" % (room, nick),
pfrom=pfrom
)
del self.rooms[room]
def set_subject(self, room: JID, subject: str, *, mfrom: Optional[JID] = None):
"""Set a room’s subject."""
"""Set a room’s subject.
:param room: JID of the room.
:param subject: Room subject to set.
"""
msg = self.xmpp.make_message(room, mfrom=mfrom)
msg['type'] = 'groupchat'
msg['subject'] = subject
msg.send()
async def destroy(self, room: JID, reason='', altroom='', *,
async def get_room_config(self, room: JID, ifrom: Optional[JID] = None,
**iqkwargs) -> Form:
"""Get the room config form in 0004 plugin format.
:param room: Room to get the config form from.
:raises ValueError: When the form is not found.
:returns: A form object.
"""
iq = self.xmpp.make_iq_get(stanza.NS_OWNER, ito=room, ifrom=ifrom)
result = await iq.send(**iqkwargs)
form = result['mucowner_query'].get_plugin('form', check=True)
if form is None:
raise ValueError("Configuration form not found")
return form
async def set_room_config(self, room: JID, config: Form, *,
ifrom: Optional[JID] = None, **iqkwargs):
"""Send a room config form.
:param room: Room to send the form to.
:param config: A filled room form.
"""
query = MUCOwnerQuery()
config['type'] = 'submit'
query.append(config)
iq = self.xmpp.make_iq_set(query, ito=room, ifrom=ifrom)
await iq.send(**iqkwargs)
async def cancel_config(self, room: JID, *,
ifrom: Optional[JID] = None, **iqkwargs):
"""Cancel a requested config form.
:param room: Room to cancel the form for.
"""
query = MUCOwnerQuery()
query['form']['type'] = 'cancel'
iq = self.xmpp.make_iq_set(query, ito=room, ifrom=ifrom)
await iq.send(**iqkwargs)
async def destroy(self, room: JID, reason: str = '', altroom: Optional[JID] = None, *,
ifrom: Optional[JID] = None, **iqkwargs):
"""Destroy a room."""
"""Destroy a room.
:param room: Room JID to destroy.
:param reason: Reason for destroying the room.
:param altroom: An alternate room that users should join.
"""
iq = self.xmpp.make_iq_set(ifrom=ifrom, ito=room)
iq.enable('mucowner_query')
iq['mucowner_query'].enable('destroy')
@ -359,10 +443,17 @@ class XEP_0045(BasePlugin):
iq['mucowner_query']['destroy']['reason'] = reason
await iq.send(**iqkwargs)
async def set_affiliation(self, room: JID, affiliation: str, *, jid: Optional[JID] = None,
async def set_affiliation(self, room: JID, affiliation: MucAffiliation, *,
jid: Optional[JID] = None,
nick: Optional[str] = None, reason: str = '',
ifrom: Optional[JID] = None, **iqkwargs):
""" Change room affiliation."""
""" Change room affiliation for a JID or nickname.
:param room: Room to modify.
:param affiliation: Affiliation to set.
:param jid: User JID to use in the set operation.
:param reason: Reason for the affiliation change.
"""
if affiliation not in AFFILIATIONS:
raise ValueError('%s is not a valid affiliation' % affiliation)
if not any((jid, nick)):
@ -377,12 +468,45 @@ class XEP_0045(BasePlugin):
iq['mucadmin_query']['item']['reason'] = reason
await iq.send(**iqkwargs)
async def set_role(self, room: JID, nick: str, role: str, *,
async def get_affiliation_list(self, room: JID, affiliation: MucAffiliation, *,
ifrom: Optional[JID] = None, **iqkwargs) -> List[JID]:
"""Get a list of JIDs with the specified affiliation
:param room: Room to get affiliations from.
:param affiliation: The affiliation to list.
"""
iq = self.xmpp.make_iq_get(stanza.NS_ADMIN, ito=room, ifrom=ifrom)
iq['mucadmin_query']['item']['affiliation'] = affiliation
result = await iq.send(**iqkwargs)
return [item['jid'] for item in result['mucadmin_query']]
async def send_affiliation_list(self, room: JID,
affiliations: List[Tuple[JID, MucAffiliation]], *,
ifrom: Optional[JID] = None, **iqkwargs):
"""Send an affiliation delta list.
:param room: Room to send the affiliations to.
:param affiliations: List of couples (jid, affiliation) to set.
"""
iq = self.xmpp.make_iq_set(ito=room, ifrom=ifrom)
for jid, affiliation in affiliations:
item = MUCAdminItem()
item['jid'] = jid
item['affiliation'] = affiliation
iq['mucadmin_query'].append(item)
await iq.send(**iqkwargs)
async def set_role(self, room: JID, nick: str, role: MucRole, *,
reason: str = '', ifrom: Optional[JID] = None, **iqkwargs):
""" Change role property of a nick in a room.
Typically, roles are temporary (they last only as long as you are in the
room), whereas affiliations are permanent (they last across groupchat
sessions).
:param room: Room to modify.
:param nick: User nickname to use in the set operation.
:param role: Role to set.
:param reason: Reason for the role change.
"""
if role not in ROLES:
raise ValueError("Role %s does not exist" % role)
@ -393,110 +517,127 @@ class XEP_0045(BasePlugin):
iq['mucadmin_query']['item']['reason'] = reason
await iq.send(**iqkwargs)
def invite(self, room: JID, jid: JID, reason: str = '', *,
mfrom: Optional[JID] = None):
""" Invite a jid to a room."""
msg = self.xmpp.make_message(room, mfrom=mfrom)
msg['muc']['invite']['to'] = jid
if reason:
msg['muc']['invite']['reason'] = reason
self.xmpp.send(msg)
def decline(self, room: JID, jid: JID, reason: str = '', *,
mfrom: Optional[JID] = None):
"""Decline a mediated invitation."""
msg = self.xmpp.make_message(room, mfrom=mfrom)
msg['muc']['decline']['to'] = jid
if reason:
msg['muc']['decline']['reason'] = reason
self.xmpp.send(msg)
def leave_muc(self, room: JID, nick: str, msg='', pfrom=None):
""" Leave the specified room.
"""
if msg:
self.xmpp.send_presence(pshow='unavailable', pto="%s/%s" % (room, nick), pstatus=msg, pfrom=pfrom)
else:
self.xmpp.send_presence(pshow='unavailable', pto="%s/%s" % (room, nick), pfrom=pfrom)
del self.rooms[room]
async def get_room_config(self, room: JID, ifrom=''):
"""Get the room config form in 0004 plugin format """
iq = self.xmpp.make_iq_get(stanza.NS_OWNER, ito=room, ifrom=ifrom)
# For now, swallow errors to preserve existing API
result = await iq.send()
form = result.xml.find('{http://jabber.org/protocol/muc#owner}query/{jabber:x:data}x')
if form is None:
raise ValueError("Configuration form not found")
return self.xmpp.plugin['xep_0004'].build_form(form)
async def cancel_config(self, room: JID, *,
ifrom: Optional[JID] = None, **iqkwargs) -> Iq:
"""Cancel a requested config form"""
query = MUCOwnerQuery()
x = ET.Element('{jabber:x:data}x', type='cancel')
query.append(x)
iq = self.xmpp.make_iq_set(query, ito=room, ifrom=ifrom)
return await iq.send(**iqkwargs)
async def set_room_config(self, room: JID, config, *,
ifrom: Optional[JID] = None, **iqkwargs) -> Iq:
"""Send a room config form"""
query = MUCOwnerQuery()
config['type'] = 'submit'
query.append(config)
iq = self.xmpp.make_iq_set(query, ito=room, ifrom=ifrom)
return await iq.send(**iqkwargs)
async def get_affiliation_list(self, room: JID, affiliation: str, *,
ifrom: Optional[JID] = None, **iqkwargs) -> List[JID]:
""""Get a list of JIDs with the specified affiliation"""
iq = self.xmpp.make_iq_get(stanza.NS_ADMIN, ito=room, ifrom=ifrom)
iq['mucadmin_query']['item']['affiliation'] = affiliation
result = await iq.send(**iqkwargs)
return [item['jid'] for item in result['mucadmin_query']]
async def get_roles_list(self, room: JID, role: str, *,
async def get_roles_list(self, room: JID, role: MucRole, *,
ifrom: Optional[JID] = None, **iqkwargs) -> List[str]:
""""Get a list of JIDs with the specified role"""
""""Get a list of JIDs with the specified role
:param room: Room to get roles from.
:param role: The role to list.
"""
iq = self.xmpp.make_iq_get(stanza.NS_ADMIN, ito=room, ifrom=ifrom)
iq['mucadmin_query']['item']['role'] = role
result = await iq.send(**iqkwargs)
return [item['nick'] for item in result['mucadmin_query']]
async def send_affiliation_list(self, room: JID, affiliations: List[Tuple[JID, str]], *,
ifrom: Optional[JID] = None, **iqkwargs) -> Iq:
"""Send an affiliation delta list"""
iq = self.xmpp.make_iq_set(ito=room, ifrom=ifrom)
for jid, affiliation in affiliations:
item = MUCAdminItem()
item['jid'] = jid
item['affiliation'] = affiliation
iq['mucadmin_query'].append(item)
return await iq.send(**iqkwargs)
async def send_role_list(self, room: JID, roles: List[Tuple[str, MucRole]], *,
ifrom: Optional[JID] = None, **iqkwargs):
"""Send a role delta list.
async def send_role_list(self, room: JID, roles: List[Tuple[str, str]], *,
ifrom: Optional[JID] = None, **iqkwargs) -> Iq:
"""Send a role delta list"""
:param room: Room to send the roles to.
:param roles: List of couples (nick, role) to set.
"""
iq = self.xmpp.make_iq_set(ito=room, ifrom=ifrom)
for nick, affiliation in roles:
item = MUCAdminItem()
item['nick'] = nick
item['affiliation'] = affiliation
iq['mucadmin_query'].append(item)
return await iq.send(**iqkwargs)
await iq.send(**iqkwargs)
def invite(self, room: JID, jid: JID, reason: str = '', *,
mfrom: Optional[JID] = None):
""" Invite a jid to a room (mediated invitation).
:param room: Room to invite the user in.
:param jid: JID of the user to invite.
:param reason: Reason for inviting the user.
"""
msg = self.xmpp.make_message(room, mfrom=mfrom)
msg['muc']['invite']['to'] = jid
if reason:
msg['muc']['invite']['reason'] = reason
self.xmpp.send(msg)
def invite_server(self, room: JID, jid: JID,
invite_from: JID, reason: str = ''):
"""Send a mediated invite to a user, as a MUC service.
.. versionadded:: 1.8.0
:param room: Room to invite the user in.
:param jid: JID of the user to invite.
:param invite_from: JID of the user to send the invitation from.
:param reason: Reason for inviting the user.
"""
if not self.xmpp.is_component:
raise ValueError("Cannot use this method as a client.")
msg = self.xmpp.make_message(jid, mfrom=room)
msg['muc']['invite']['from'] = invite_from
if reason:
msg['muc']['invite']['reason'] = reason
msg.send()
def decline(self, room: JID, jid: JID, reason: str = '', *,
mfrom: Optional[JID] = None):
"""Decline a mediated invitation.
:param room: Room the invitation came from.
:param jid: JID of the user who sent the invitation.
:param reason: Reason for declining.
"""
msg = self.xmpp.make_message(room, mfrom=mfrom)
msg['muc']['decline']['to'] = jid
if reason:
msg['muc']['decline']['reason'] = reason
self.xmpp.send(msg)
def jid_in_room(self, room: JID, jid: JID) -> bool:
"""Check if a JID is present in a room.
:param room: Room to check.
:param jid: JID to check.
"""
for nick in self.rooms[room]:
entry = self.rooms[room][nick]
if not entry.get('jid'):
continue
if entry is not None and entry['jid'].full == jid:
return True
return False
def get_nick(self, room: JID, jid: JID) -> Optional[str]:
"""Get the nickname of a specific JID in a room.
:param room: Room to inspect.
:param jid: JID whose nick to return.
"""
for nick in self.rooms[room]:
entry = self.rooms[room][nick]
if not entry.get('jid'):
continue
if entry is not None and entry['jid'].full == jid:
return nick
return None
def get_joined_rooms(self) -> List[JID]:
return self.rooms.keys()
"""Get the list of rooms we sent a join presence to
and did not explicitly leave.
"""
return list(self.rooms.keys())
def get_our_jid_in_room(self, room_jid: JID) -> str:
""" Return the jid we're using in a room.
"""
return "%s/%s" % (room_jid, self.our_nicks[room_jid])
def get_jid_property(self, room, nick, jid_property):
def get_jid_property(self, room: JID, nick: str,
jid_property: MucRoomItemKeys) -> Any:
""" Get the property of a nick in a room, such as its 'jid' or 'affiliation'
If not found, return None.
:param room: Get the property for this room.
:param nick: Which nickname information to get.
:param jid_property: Property to fetch.
"""
if room in self.rooms and nick in self.rooms[room] and jid_property in self.rooms[room][nick]:
return self.rooms[room][nick][jid_property]
@ -505,10 +646,12 @@ class XEP_0045(BasePlugin):
def get_roster(self, room: JID) -> List[str]:
""" Get the list of nicks in a room.
:param room: Room to list nicks from.
"""
if room not in self.rooms.keys():
raise ValueError("Room %s is not joined" % room)
return self.rooms[room].keys()
return list(self.rooms[room].keys())
def get_users_by_affiliation(self, room: JID, affiliation='member', *, ifrom: Optional[JID] = None):
# Preserve old API

35
slixmpp/types.py
View file

@ -7,15 +7,21 @@
This file contains boilerplate to define types relevant to slixmpp.
"""
from typing import Optional
try:
from typing import (
Literal,
TypedDict,
)
except ImportError:
from typing_extensions import (
Literal,
TypedDict,
)
from slixmpp.jid import JID
PresenceTypes = Literal[
'error', 'probe', 'subscribe', 'subscribed',
'unavailable', 'unsubscribe', 'unsubscribed',
@ -35,3 +41,32 @@ IqTypes = Literal[
"error", "get", "set", "result",
]
MucRole = Literal[
'moderator', 'participant', 'visitor', 'none'
]
MucAffiliation = Literal[
'outcast', 'member', 'admin', 'owner', 'none'
]
class PresenceArgs(TypedDict, total=False):
pfrom: JID
pto: JID
pshow: PresenceShows
ptype: PresenceTypes
pstatus: str
class MucRoomItem(TypedDict, total=False):
jid: JID
role: MucRole
affiliation: MucAffiliation
show: Optional[PresenceShows]
status: str
alt_nick: str
MucRoomItemKeys = Literal[
'jid', 'role', 'affiliation', 'show', 'status', 'alt_nick',
]