# `stanza` — XSOs for dealing with stanzas

This module provides `XSO` subclasses which provide access to stanzas and their RFC6120-defined child elements.

Much of what you’ll read here makes much more sense if you have read RFC 6120.

## Top-level classes

class aioxmpp.stanza.StanzaBase(*[, from_][, to][, id_])

  Base for all stanza classes. Usually, you will use the derived classes:

  `Message` | An XMPP message stanza.
  `Presence` | An XMPP presence stanza.
  `IQ` | An XMPP IQ stanza.

  However, some common attributes are defined in this base class:

  from_

    The `JID` of the sending entity.

  to

    The `JID` of the receiving entity.

  lang

    The `xml:lang` value as `LanguageTag`.

  error

    Either `None` or a `Error` instance.

  Note

  The `id_` attribute is not defined in `StanzaBase` as different stanza classes have different requirements with respect to presence of that attribute.

  In addition to these attributes, common methods needed are also provided:

  autoset_id()

    If the `id_` already has a non-false (false is also the empty string!) value, this method is a no-op.

    Otherwise, the `id_` attribute is filled with `RANDOM_ID_BYTES` of random data, encoded by `aioxmpp.utils.to_nmtoken()`.

    Note

    This method only works on subclasses of `StanzaBase` which define the `id_` attribute.

  make_error(error)

    Create a new instance of this stanza (this directly uses `type(self)`, so also works for subclasses without extra care) which has the given error value set as `error`.

    In addition, the `id_`, `from_` and `to` values are transferred from the original (with from and to being swapped). Also, the `type_` is set to `"error"`.

class aioxmpp.Message(*[, from_][, to][, id_][, type_])

  An XMPP message stanza. The keyword arguments can be used to initialize the attributes of the `Message`.

  id_

    The optional ID of the stanza.

  type_

    The type attribute of the stanza. The allowed values are enumerated in `MessageType`.

    Changed in version 0.7: Starting with 0.7, the enumeration `MessageType` is used. Before, strings equal to the XML attribute value character data were used (`"chat"`, `"headline"`, and so on).

    As of 0.7, setting the string equivalents is still supported. However, reading from the attribute always returns the corresponding enumeration members (which still compare equal to their string equivalents).

    Deprecated since version 0.7: The use of the aforementioned string values is deprecated and will lead to `TypeError` and/or `ValueError` being raised when they are written to this attribute. See the Changelog for Version 0.7 for further details on how to upgrade your code efficiently.

  body

    A `LanguageMap` mapping the languages of the different body elements to their text.

    Changed in version 0.5: Before 0.5, this was a `XSOList`.

  subject

    A `LanguageMap` mapping the languages of the different subject elements to their text.

    Changed in version 0.5: Before 0.5, this was a `XSOList`.

  thread

    A `Thread` instance representing the threading information attached to the message or `None` if no threading information is attached.

  Note that some attributes are inherited from `StanzaBase`:

  `from_` | sender `JID`
  `to` | recipient `JID`
  `lang` | `xml:lang` value
  `error` | `Error` instance

  make_reply()

    Create a reply for the message. The `id_` attribute is cleared in the reply. The `from_` and `to` are swapped and the `type_` attribute is the same as the one of the original message.

    The new `Message` object is returned.

class aioxmpp.IQ(*[, from_][, to][, id_][, type_])

  An XMPP IQ stanza. The keyword arguments can be used to initialize the attributes of the `IQ`.

  id_

    The optional ID of the stanza.

  type_

    The type attribute of the stanza. The allowed values are enumerated in `IQType`.

    Changed in version 0.7: Starting with 0.7, the enumeration `IQType` is used. Before, strings equal to the XML attribute value character data were used (`"get"`, `"set"`, and so on).

    As of 0.7, setting the string equivalents is still supported. However, reading from the attribute always returns the corresponding enumeration members (which still compare equal to their string equivalents).

    Deprecated since version 0.7: The use of the aforementioned string values is deprecated and will lead to `TypeError` and/or `ValueError` being raised when they are written to this attribute. See the Changelog for Version 0.7 for further details on how to upgrade your code efficiently.

  payload

    An XSO which forms the payload of the IQ stanza.

  Note that some attributes are inherited from `StanzaBase`:

  `from_` | sender `JID`
  `to` | recipient `JID`
  `lang` | `xml:lang` value
  `error` | `Error` instance

  New payload classes can be registered using:

  classmethod as_payload_class(other_cls)

    Register other_cls as possible `IQ` `payload`. Doing so is required in order to receive IQs with such payload.

class aioxmpp.Presence(*[, from_][, to][, id_][, type_])

  An XMPP presence stanza. The keyword arguments can be used to initialize the attributes of the `Presence`.

  id_

    The optional ID of the stanza.

  type_

    The type attribute of the stanza. The allowed values are enumerated in `PresenceType`.

    Changed in version 0.7: Starting with 0.7, the enumeration `PresenceType` is used. Before, strings equal to the XML attribute value character data were used (`"probe"`, `"unavailable"`, and so on, as well as `None` to indicate the absence of the attribute and thus “available” presence).

    As of 0.7, setting the string equivalents and `None` is still supported. However, reading from the attribute always returns the corresponding enumeration members (which still compare equal to their string equivalents).

    Deprecated since version 0.7: The use of the aforementioned string values (and `None`) is deprecated and will lead to `TypeError` and/or `ValueError` being raised when they are written to this attribute. See the Changelog for Version 0.7 for further details on how to upgrade your code efficiently.

  show

    The `show` value of the stanza, or `None` if no `show` element is present.

  priority

    The `priority` value of the presence. The default here is `0` and corresponds to an absent `priority` element.

  status

    A `LanguageMap` mapping the languages of the different status elements to their text.

    Changed in version 0.5: Before 0.5, this was a `XSOList`.

  Note that some attributes are inherited from `StanzaBase`:

  `from_` | sender `JID`
  `to` | recipient `JID`
  `lang` | `xml:lang` value
  `error` | `Error` instance

## Payload classes

For `Presence` and `Message` as well as `IQ` errors, the standardized payloads also have classes which are used as values for the attributes:

class aioxmpp.stanza.Error(*[, condition][, type_][, text])

  An XMPP stanza error. The keyword arguments can be used to initialize the attributes of the `Error`.

  Parameters:

    - condition (`aioxmpp.ErrorCondition` or `aioxmpp.xso.XSO`) – The error condition as enumeration member or XSO.

    - type (`aioxmpp.ErrorType`) – The type of the error

    - text (`str` or `None`) – The optional error text

  type_

    The type attribute of the stanza. The allowed values are enumerated in `ErrorType`.

    Changed in version 0.7: Starting with 0.7, the enumeration `ErrorType` is used. Before, strings equal to the XML attribute value character data were used (`"cancel"`, `"auth"`, and so on).

    As of 0.7, setting the string equivalents is still supported. However, reading from the attribute always returns the corresponding enumeration members (which still compare equal to their string equivalents).

    Deprecated since version 0.7: The use of the aforementioned string values is deprecated and will lead to `TypeError` and/or `ValueError` being raised when they are written to this attribute. See the Changelog for Version 0.7 for further details on how to upgrade your code efficiently.

  condition

    The standard defined condition which triggered the error. Possible values can be determined by looking at the RFC or the source.

    This is a member of the `aioxmpp.ErrorCondition` enumeration.

    Changed in version 0.10: Starting with 0.10, the enumeration `aioxmpp.ErrorCondition` is used. Before, tuples equal to the tags of the child elements were used (e.g. `(namespaces.stanzas, "bad-request")`).

    As of 0.10, setting the tuple equivalents is still supported. However, reading from the attribute always returns the corresponding enumeration members (which still compare equal to their tuple equivalents).

    Deprecated since version 0.10: The use of the aforementioned tuple values is deprecated and will lead to `TypeError` and/or `ValueError` being raised when they are written to this attribute. See the changelog for notes on the transition.

  condition_obj

    An XSO object representing the child element representing the RFC 6120 defined error condition.

    New in version 0.10.

  text

    The descriptive error text which is part of the error stanza, if any (otherwise `None`).

  Any child elements unknown to the XSO are dropped. This is to support application-specific conditions used by other applications. To register your own use `xso.XSO.register_child()` on `application_condition`:

  application_condition

    Optional child `XSO` which describes the error condition in more application specific detail.

  To register a class as application condition, use:

  classmethod as_application_condition(other_cls)

    Register other_cls as child class for the `application_condition` attribute. Doing so will allows the class to be parsed instead of being discarded.

    See also

    `make_application_error()` — creates and automatically registers a new application error condition.

  Conversion to and from exceptions is supported with the following methods:

  to_exception()

    Convert the error payload to a `XMPPError` subclass.

    Result:

      Newly constructed exception

    Return type:

      `aioxmpp.errors.XMPPError`

    The exact type of the result depends on the `type_` (see `XMPPError` about the existing subclasses).

    The `condition_obj`, `text` and `application_condition` are transferred to the respective attributes of the `XMPPError`.

  classmethod from_exception(exc)

    Construct a new `Error` payload from the attributes of the exception.

    Parameters:

      exc (`aioxmpp.errors.XMPPError`) – The exception to convert

    Result:

      Newly constructed error payload

    Return type:

      `Error`

    Changed in version 0.10: The `aioxmpp.XMPPError.application_defined_condition` is now taken over into the result.

aioxmpp.stanza.make_application_error(name, tag)

  Create and return a class inheriting from `xso.XSO`. The `xso.XSO.TAG` is set to tag and the class’ name will be name.

  In addition, the class is automatically registered with `Error.application_condition` using `as_application_condition()`.

  Keep in mind that if you subclass the class returned by this function, the subclass is not registered with `Error`. In addition, if you do not override the `TAG`, you will not be able to register the subclass as application defined condition as it has the same tag as the class returned by this function, which has already been registered as application condition.

### For messages

class aioxmpp.stanza.Thread

  Threading information, consisting of a thread identifier and an optional parent thread identifier.

  identifier

    Identifier of the thread

  parent

    `None` or the identifier of the parent thread.

class aioxmpp.stanza.Subject

  The subject of a `Message` stanza.

  While it might seem intuitive to refer to the subject using a `ChildText` descriptor, the fact that there might be multiple texts for different languages justifies the use of a separate class.

  lang

    The `xml:lang` of this subject part, as `LanguageTag`.

  text

    The textual content of the subject

class aioxmpp.stanza.Body

  The textual body of a `Message` stanza.

  While it might seem intuitive to refer to the body using a `ChildText` descriptor, the fact that there might be multiple texts for different languages justifies the use of a separate class.

  lang

    The `xml:lang` of this body part, as `LanguageTag`.

  text

    The textual content of the body.

### For presence’

class aioxmpp.stanza.Status

  The status of a `Presence` stanza.

  While it might seem intuitive to refer to the status using a `ChildText` descriptor, the fact that there might be multiple texts for different languages justifies the use of a separate class.

  lang

    The `xml:lang` of this status part, as `LanguageTag`.

  text

    The textual content of the status

## Exceptions

class aioxmpp.stanza.PayloadError(msg, partial_obj, ev_args, descriptor)

  Base class for exceptions raised when stanza payloads cannot be processed.

  This is a subclass of `StanzaError`. `partial_obj` has the additional guarantee that the attributes `StanzaBase.from_`, `StanzaBase.to`, `StanzaBase.type_` and `StanzaBase.id_` are already parsed completely.

class aioxmpp.stanza.PayloadParsingError(partial_obj, ev_args, descriptor)

  A constraint of a sub-object was not fulfilled and the stanza being processed is illegal. The partially parsed stanza object is provided in `partial_obj`.

  This is a subclass of `PayloadError`.

class aioxmpp.stanza.UnknownIQPayload(partial_obj, ev_args, descriptor)

  The payload of an IQ object is unknown. The partial object with attributes but without payload is available through `partial_obj`.

## Module Level Constants

aioxmpp.stanza.RANDOM_ID_BYTES = 15

  The number of bytes of randomness used when generating stanza IDs.