diff options
| -rw-r--r-- | docs/api/plugins/xep_0045.rst | 1 | ||||
| -rw-r--r-- | docs/api/xmlstream/stanzabase.rst | 4 | ||||
| -rw-r--r-- | docs/conf.py | 2 | ||||
| -rw-r--r-- | docs/event_index.rst | 493 | ||||
| -rw-r--r-- | docs/howto/stanzas.rst | 5 | ||||
| -rw-r--r-- | slixmpp/plugins/xep_0045/muc.py | 403 | ||||
| -rw-r--r-- | slixmpp/types.py | 35 |
7 files changed, 651 insertions, 292 deletions
diff --git a/docs/api/plugins/xep_0045.rst b/docs/api/plugins/xep_0045.rst index d4420870..3587bc90 100644 --- a/docs/api/plugins/xep_0045.rst +++ b/docs/api/plugins/xep_0045.rst @@ -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 diff --git a/docs/api/xmlstream/stanzabase.rst b/docs/api/xmlstream/stanzabase.rst index ad43a44a..c061648c 100644 --- a/docs/api/xmlstream/stanzabase.rst +++ b/docs/api/xmlstream/stanzabase.rst @@ -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 diff --git a/docs/conf.py b/docs/conf.py index c68ac882..613864fa 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -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 diff --git a/docs/event_index.rst b/docs/event_index.rst index 8ab18a6a..2a540a34 100644 --- a/docs/event_index.rst +++ b/docs/event_index.rst @@ -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. diff --git a/docs/howto/stanzas.rst b/docs/howto/stanzas.rst index 56dfce79..97178f36 100644 --- a/docs/howto/stanzas.rst +++ b/docs/howto/stanzas.rst @@ -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 ~~~~~~~~~~~~ diff --git a/slixmpp/plugins/xep_0045/muc.py b/slixmpp/plugins/xep_0045/muc.py index db24addf..4507be59 100644 --- a/slixmpp/plugins/xep_0045/muc.py +++ b/slixmpp/plugins/xep_0045/muc.py @@ -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) + 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 + + :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_role_list(self, room: JID, roles: List[Tuple[str, MucRole]], *, + ifrom: Optional[JID] = None, **iqkwargs): + """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) + await iq.send(**iqkwargs) + def invite(self, room: JID, jid: JID, reason: str = '', *, mfrom: Optional[JID] = None): - """ Invite a jid to a room.""" + """ 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.""" + """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 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']] + def jid_in_room(self, room: JID, jid: JID) -> bool: + """Check if a JID is present in a room. - async def get_roles_list(self, room: JID, role: str, *, - ifrom: Optional[JID] = None, **iqkwargs) -> List[str]: - """"Get a list of JIDs with the specified role""" - 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']] + :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 - 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) + def get_nick(self, room: JID, jid: JID) -> Optional[str]: + """Get the nickname of a specific JID in a room. - async def send_role_list(self, room: JID, roles: List[Tuple[str, str]], *, - ifrom: Optional[JID] = None, **iqkwargs) -> Iq: - """Send a role delta list""" - 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) + :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 diff --git a/slixmpp/types.py b/slixmpp/types.py index 44e24a1e..c8ab640c 100644 --- a/slixmpp/types.py +++ b/slixmpp/types.py @@ -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', +] |