# Slixmpp classes

class slixmpp.Message(*args, recv=False, **kwargs)

  XMPP’s <message> stanzas are a “push” mechanism to send information to other XMPP entities without requiring a response.

  Chat clients will typically use <message> stanzas that have a type of either “chat” or “groupchat”.

  When handling a message event, be sure to check if the message is an error response.

  Example <message> stanzas:

      <message to="user1@example.com" from="user2@example.com">
        <body>Hi!</body>
      </message>

      <message type="groupchat" to="room@conference.example.com">
        <body>Hi everyone!</body>
      </message>

  Stanza Interface:

    - body: The main contents of the message.

    - subject: An optional description of the message’s contents.

    - mucroom: (Read-only) The name of the MUC room that sent the message.

    - mucnick: (Read-only) The MUC nickname of message’s sender.

  Attributes:

    - types: May be one of: normal, chat, headline, groupchat, or error.

  chat()

    Set the message type to ‘chat’.

  del_mucnick()

    Dummy method to prevent deletion.

  del_mucroom()

    Dummy method to prevent deletion.

  del_parent_thread()

    Delete the message thread’s parent reference.

  get_mucnick() → str

    Return the nickname of the MUC user that sent the message.

    Read-only stanza interface.

    Return type:

      str

  get_mucroom()

    Return the name of the MUC room where the message originated.

    Read-only stanza interface.

    Return type:

      str

  get_parent_thread()

    Return the message thread’s parent thread.

    Return type:

      str

  get_type() → Literal['chat', 'error', 'groupchat', 'headline', 'normal']

    Return the message type.

    Overrides default stanza interface behavior.

    Returns ‘normal’ if no type attribute is present.

    Return type:

      str

  interfaces: ClassVar[Set[str]] = {'body', 'from', 'id', 'mucnick', 'mucroom', 'parent_thread', 'subject', 'thread', 'to', 'type'}

    The set of keys that the stanza provides for accessing and manipulating the underlying XML object. This set may be augmented with the `plugin_attrib` value of any registered stanza plugins.

  lang_interfaces: ClassVar[Set[str]] = {'body', 'thread'}

    Added in version 1.1.2.

  name: ClassVar[str] = 'message'

    The XML tag name of the element, not including any namespace prefixes. For example, an `ElementBase` object for `<message />` would use `name = 'message'`.

  namespace: str = 'jabber:client'

    The default XMPP client namespace

  normal()

    Set the message type to ‘normal’.

  plugin_attrib: ClassVar[str] = 'message'

    For `ElementBase` subclasses which are intended to be used as plugins, the `plugin_attrib` value defines the plugin name. Plugins may be accessed by using the `plugin_attrib` value as the interface. An example using `plugin_attrib = 'foo'`:

        register_stanza_plugin(Message, FooPlugin)
        msg = Message()
        msg['foo']['an_interface_from_the_foo_plugin']

  reply(body=None, clear=True)

    Create a message reply.

    Overrides StanzaBase.reply.

    Sets proper ‘to’ attribute if the message is from a MUC, and adds a message body if one is given.

    Parameters:

      - body (str) – Optional text content for the message.

      - clear (bool) – Indicates if existing content should be removed before replying. Defaults to True.

    Return type:

      `Message`

  set_mucnick(value)

    Dummy method to prevent modification.

  set_mucroom(value)

    Dummy method to prevent modification.

  set_parent_thread(value)

    Add or change the message thread’s parent thread.

    Parameters:

      value (str) – identifier of the thread

  sub_interfaces: ClassVar[Set[str]] = {'body', 'thread'}

    A subset of `interfaces` which maps interfaces to direct subelements of the underlying XML object. Using this set, the text of these subelements may be set, retrieved, or removed without needing to define custom methods.

class slixmpp.Presence(*args, recv: bool = False, **kwargs)

  XMPP’s <presence> stanza allows entities to know the status of other clients and components. Since it is currently the only multi-cast stanza in XMPP, many extensions add more information to <presence> stanzas to broadcast to every entry in the roster, such as capabilities, music choices, or locations (XEP-0115: Entity Capabilities and XEP-0163: Personal Eventing Protocol).

  Since <presence> stanzas are broadcast when an XMPP entity changes its status, the bulk of the traffic in an XMPP network will be from <presence> stanzas. Therefore, do not include more information than necessary in a status message or within a <presence> stanza in order to help keep the network running smoothly.

  Example <presence> stanzas:

      <presence />

      <presence from="user@example.com">
        <show>away</show>
        <status>Getting lunch.</status>
        <priority>5</priority>
      </presence>

      <presence type="unavailable" />

      <presence to="user@otherhost.com" type="subscribe" />

  Stanza Interface:

    - priority: A value used by servers to determine message routing.

    - show: The type of status, such as away or available for chat.

    - status: Custom, human readable status message.

  Attributes:

    - types: One of: available, unavailable, error, probe, subscribe, subscribed, unsubscribe, and unsubscribed.

    - showtypes: One of: away, chat, dnd, and xa.

  del_type()

    Remove both the type attribute and the <show> element.

  get_priority()

    Return the value of the <presence> element as an integer.

    Return type:

      int

  get_type() → str

    Return the value of the <presence> stanza’s type attribute, or the value of the <show> element if valid.

  interfaces: ClassVar[Set[str]] = {'from', 'id', 'priority', 'show', 'status', 'to', 'type'}

    The set of keys that the stanza provides for accessing and manipulating the underlying XML object. This set may be augmented with the `plugin_attrib` value of any registered stanza plugins.

  lang_interfaces: ClassVar[Set[str]] = {'status'}

    Added in version 1.1.2.

  name: ClassVar[str] = 'presence'

    The XML tag name of the element, not including any namespace prefixes. For example, an `ElementBase` object for `<message />` would use `name = 'message'`.

  namespace: str = 'jabber:client'

    The default XMPP client namespace

  plugin_attrib: ClassVar[str] = 'presence'

    For `ElementBase` subclasses which are intended to be used as plugins, the `plugin_attrib` value defines the plugin name. Plugins may be accessed by using the `plugin_attrib` value as the interface. An example using `plugin_attrib = 'foo'`:

        register_stanza_plugin(Message, FooPlugin)
        msg = Message()
        msg['foo']['an_interface_from_the_foo_plugin']

  reply(clear=True)

    Create a new reply <presence/> stanza from `self`.

    Overrides StanzaBase.reply.

    Parameters:

      clear (bool) – Indicates if the stanza contents should be removed before replying. Defaults to True.

  set_priority(value: int)

    Set the entity’s priority value. Some server use priority to determine message routing behavior.

    Bot clients should typically use a priority of 0 if the same JID is used elsewhere by a human-interacting client.

    Parameters:

      value (int) – An integer value greater than or equal to 0.

  set_show(show: str)

    Set the value of the <show> element.

    Parameters:

      show (str) – Must be one of: away, chat, dnd, or xa.

  set_type(value: str)

    Set the type attribute’s value, and the <show> element if applicable.

    Parameters:

      value (str) – Must be in either self.types or self.showtypes.

  sub_interfaces: ClassVar[Set[str]] = {'priority', 'show', 'status'}

    A subset of `interfaces` which maps interfaces to direct subelements of the underlying XML object. Using this set, the text of these subelements may be set, retrieved, or removed without needing to define custom methods.

class slixmpp.Iq(*args, recv=False, **kwargs)

  XMPP <iq> stanzas, or info/query stanzas, are XMPP’s method of requesting and modifying information, similar to HTTP’s GET and POST methods.

  Each <iq> stanza must have an ‘id’ value which associates the stanza with the response stanza. XMPP entities must always be given a response <iq> stanza with a type of ‘result’ after sending a stanza of type ‘get’ or ‘set’.

  Most uses cases for <iq> stanzas will involve adding a <query> element whose namespace indicates the type of information desired. However, some custom XMPP applications use <iq> stanzas as a carrier stanza for an application-specific protocol instead.

  Example <iq> Stanzas:

      <iq to="user@example.com" type="get" id="314">
        <query xmlns="http://jabber.org/protocol/disco#items" />
      </iq>

      <iq to="user@localhost" type="result" id="17">
        <query xmlns='jabber:iq:roster'>
          <item jid='otheruser@example.net'
                name='John Doe'
                subscription='both'>
            <group>Friends</group>
          </item>
        </query>
      </iq>

  Stanza Interface:

    - query: The namespace of the <query> element if one exists.

  Attributes:

    - types: May be one of: get, set, result, or error.

  del_query()

    Remove the <query> element.

  get_query()

    Return the namespace of the <query> element.

    Return type:

      str

  interfaces: ClassVar[Set[str]] = {'from', 'id', 'query', 'to', 'type'}

    The set of keys that the stanza provides for accessing and manipulating the underlying XML object. This set may be augmented with the `plugin_attrib` value of any registered stanza plugins.

  name: ClassVar[str] = 'iq'

    The XML tag name of the element, not including any namespace prefixes. For example, an `ElementBase` object for `<message />` would use `name = 'message'`.

  namespace: str = 'jabber:client'

    The default XMPP client namespace

  plugin_attrib: ClassVar[str] = 'iq'

    For `ElementBase` subclasses which are intended to be used as plugins, the `plugin_attrib` value defines the plugin name. Plugins may be accessed by using the `plugin_attrib` value as the interface. An example using `plugin_attrib = 'foo'`:

        register_stanza_plugin(Message, FooPlugin)
        msg = Message()
        msg['foo']['an_interface_from_the_foo_plugin']

  plugin_attrib_map: ClassVar[Dict[str, Type[ElementBase]]] = {'error': <class 'slixmpp.stanza.error.Error'>, 'roster': <class 'slixmpp.stanza.roster.Roster'>}

    A mapping of the `plugin_attrib` values of registered plugins to their respective classes.

  plugin_iterables: ClassVar[Set[Type[ElementBase]]] = {}

    The set of stanza classes that can be iterated over using the ‘substanzas’ interface. Classes are added to this set when registering a plugin with `iterable=True`:

        register_stanza_plugin(DiscoInfo, DiscoItem, iterable=True)

    Added in version 1.0-Beta5.

  plugin_overrides: ClassVar[Dict[str, str]] = {}

    A map of interface operations to the overriding functions. For example, after overriding the `set` operation for the interface `body`, `plugin_overrides` would be:

        {'set_body': <some function>}

  plugin_tag_map: ClassVar[Dict[str, Type[ElementBase]]] = {'{jabber:client}error': <class 'slixmpp.stanza.error.Error'>, '{jabber:iq:roster}query': <class 'slixmpp.stanza.roster.Roster'>}

    A mapping of root element tag names (in `'{namespace}elementname'` format) to the plugin classes responsible for them.

  reply(clear=True)

    Create a new <iq> stanza replying to `self`.

    Overrides StanzaBase.reply

    Sets the ‘type’ to ‘result’ in addition to the default StanzaBase.reply behavior.

    Parameters:

      clear (bool) – Indicates if existing content should be removed before replying. Defaults to True.

  send(callback=None, timeout=None)

    Send an <iq> stanza over the XML stream.

    A callback handler can be provided that will be executed when the Iq stanza’s result reply is received.

    Returns a future which result will be set to the result Iq if it is of type ‘get’ or ‘set’ (when it is received), or a future with the result set to None if it has another type.

    Overrides StanzaBase.send

    Parameters:

      - callback (function) – Optional reference to a stream handler function. Will be executed when a reply stanza is received.

      - timeout (int) – The length of time (in seconds) to wait for a response before raising an IqTimeout

    Return type:

      asyncio.Future

  set_payload(value)

    Set the XML contents of the <iq> stanza.

    Parameters:

      value (list or XML object) – An XML object or a list of XML objects to use as the <iq> stanza’s contents

  set_query(value)

    Add or modify a <query> element.

    Query elements are differentiated by their namespace.

    Parameters:

      value (str) – The namespace of the <query> element.

  unhandled()

    Send a feature-not-implemented error if the stanza is not handled.

    Overrides StanzaBase.unhandled.