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_])[source]

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()[source]

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 eight bytes of random data, encoded as base64.

Note

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

make_error(error)[source]

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.stanza.Message(*[, from_][, to][, id_][, type_])[source]

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 "chat", "groupchat", "error", "headline" and "normal".

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()[source]

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.stanza.IQ(*[, from_][, to][, id_][, type_])[source]

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 "error", "result", "set" and "get".

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)[source]
class aioxmpp.stanza.Presence(*[, from_][, to][, id_][, type_])[source]

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 "error", "probe", "subscribe", "subscribed", "unavailable", "unsubscribe", "unsubscribed" and None, where None signifies the absence of the type attribute.

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])[source]

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

type_

The type of the error. Valid values are "auth", "cancel", "continue", "modify" and "wait".

condition

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

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

A xso.XSO.Child which can be used to register support for application-specific errors.

For messages

class aioxmpp.stanza.Thread[source]

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[source]

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[source]

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[source]

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)[source]

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

partial_obj

The IQ instance which has not been parsed completely. The attributes of the instance are already there, everything else is not guaranteed to be there.

ev_args

The XSO parsing event arguments which caused the parsing to fail.

class aioxmpp.stanza.PayloadParsingError(partial_obj, ev_args)[source]

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.

class aioxmpp.stanza.UnknownIQPayload(partial_obj, ev_args)[source]

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