`structs` — Simple data holders for common data types¶

These classes provide a way to hold structured data which is commonly encountered in the XMPP realm.

Stanza types¶

class aioxmpp.IQType¶

Enumeration for the RFC 6120 specified IQ stanza types.

See also

type_: Type attribute of Presence stanzas.

Each member has the following meta-information:

is_error¶: True for the ERROR type, false otherwise.

is_request¶: False. See is_response.

is_response¶

True for the ERROR type, false otherwise.

This is intended. Request/Response semantics do not really apply for presence stanzas, except that errors are generally in response to other presence stanzas.

is_presence_state¶

True for the AVAILABLE and UNAVAILABLE types, false otherwise.

Useful to discern presence state notifications from meta-stanzas regarding presence broadcast control.

Note

The is_error, is_request and is_response meta-information attributes share semantics across MessageType, PresenceType and IQType. You are encouraged to exploit this in full duck-typing manner in generic stanza handling code.

The following types are specified. The quotes in the member descriptions are from RFC 6121, Section 4.7.1.

ERROR¶

The "error" Presence type:

An error has occurred regarding processing of a previously sent presence stanza; if the presence stanza is of type “error”, it MUST include an <error/> child element […].

This is the only presence stanza type which is used in direct response to another presence stanza, in the sense that the Stanza ID is preserved in the response.

In addition, ERROR presence stanzas may be seen during presence broadcast if inter-server communication fails.

PROBE¶

The "probe" Presence type:

A request for an entity’s current presence; SHOULD be generated only by a server on behalf of a user.

This should not be seen in client code.

SUBSCRIBE¶: The "subscribe" Presence type:

The sender wishes to subscribe to the recipient’s presence.

SUBSCRIBED¶: The "subscribed" Presence type:

The sender has allowed the recipient to receive their presence.

UNSUBSCRIBE¶: The "unsubscribe" Presence type:

The sender is unsubscribing from the receiver’s presence.

UNSUBSCRIBED¶: The "unsubscribed" Presence type:

The subscription request has been denied or a previously granted subscription has been canceled.

AVAILABLE¶: The Presence type signalled with an absent type attribute:

The absence of a ‘type’ attribute signals that the relevant entity is available for communication […].

UNAVAILABLE¶: The "unavailable" Presence type:

The sender is no longer available for communication.

PresenceType members compare and hash equal to their values. For example:

assert PresenceType.PROBE == "probe"
assert "probe" == PresenceType.PROBE
assert hash(PresenceType.PROBE) == hash("probe")

Deprecated since version 0.7: This behaviour will cease with aioxmpp 1.0, and the first assertion will fail, the second may fail.

Please see the Changelog for Version 0.7 for further details on how to upgrade your code efficiently.

class aioxmpp.ErrorType¶

Enumeration for the RFC 6120 specified stanza error types.

These error types reflect are actually more reflecting the error classes, but the attribute is called “type” nonetheless. For consistency, we are calling it “type” here, too.

The following types are specified. The quotations in the member descriptions are from RFC 6120, Section 8.3.2.

AUTH¶

The "auth" error type:

retry after providing credentials

When converted to an exception, it uses XMPPAuthError.

CANCEL¶

The "cancel" error type:

do not retry (the error cannot be remedied)

When converted to an exception, it uses XMPPCancelError.

CONTINUE¶

The "continue" error type:

proceed (the condition was only a warning)

When converted to an exception, it uses XMPPContinueError.

MODIFY¶

The "modify" error type:

retry after changing the data sent

When converted to an exception, it uses XMPPModifyError.

WAIT¶

The "wait" error type:

retry after waiting (the error is temporary)

When converted to an exception, it uses (guess what) XMPPWaitError.

ErrorType members compare and hash equal to their values. For example:

assert ErrorType.CANCEL == "cancel"
assert "cancel" == ErrorType.CANCEL
assert hash(ErrorType.CANCEL) == hash("cancel")

Deprecated since version 0.7: This behaviour will cease with aioxmpp 1.0, and the first assertion will fail, the second may fail.

Please see the Changelog for Version 0.7 for further details on how to upgrade your code efficiently.

Jabber IDs¶

class aioxmpp.JID(localpart, domain, resource)¶

A Jabber ID (JID). To construct a JID, either use the actual constructor, or use the fromstr() class method.

If strict is false, unassigned codepoints are allowed in any of the parts of the JID. In the future, other deviations from the respective stringprep profiles may be allowed, too.

The idea is to use non-strict when output is received from outside and when it is reflected, following the old principle “be conservative in what you send and liberal in what you receive”. Otherwise, strict checking should be enabled. This brings maximum interoperability.

classmethod fromstr(s, *, strict=True)¶: Obtain a JID object by parsing a JID from the given string s.

Information about a JID:

localpart¶: The localpart, stringprep’d from the argument to the constructor.

domain¶: The domain, stringprep’d from the argument to the constructor.

resource¶: The resource, stringprep’d from the argument to the constructor.

is_bare¶: True if the JID is bare, i.e. has an empty resource part.

is_domain¶: True if the JID is a domain, i.e. if both the localpart and the resource are empty.

JID objects are immutable. To obtain a JID object with a changed property, use one of the following methods:

bare()¶: Return the bare version of this JID as new JID object.

replace(*[, localpart][, domain][, resource])¶: Construct a new JID object, using the values of the current JID. Use the arguments to override specific attributes on the new object.

Presence¶

class aioxmpp.PresenceShow¶

Enumeration to support the show element of presence stanzas.

The enumeration members support total ordering. The order is defined by relevance and is the following (from lesser to greater): XA, AWAY, NONE, CHAT, DND. The order is intended to be used to extract the most relevant resource e.g. in a roster.

New in version 0.8.

XA = "xa"¶: The entity or resource is away for an extended period (xa = “eXtended Away”).

—RFC 6121, Section 4.7.2.1

EXTENDED_AWAY = "xa"¶: Alias to XA.

AWAY = "away"¶: The entity or resource is temporarily away.

—RFC 6121, Section 4.7.2.1

NONE = None¶: Signifies absence of the show element.

PLAIN = None¶: Alias to NONE.

CHAT = "chat"¶: The entity or resource is actively interested in chatting.

—RFC 6121, Section 4.7.2.1

FREE_FOR_CHAT = "chat"¶: Alias to CHAT.

DND = "dnd"¶: The entity or resource is busy (dnd = “Do Not Disturb”).

—RFC 6121, Section 4.7.2.1

DO_NOT_DISTURB = "dnd"¶: Alias to DND.

class aioxmpp.PresenceState(available=False, show=<PresenceShow.NONE: None>)¶

Hold a presence state of an XMPP resource, as defined by the presence stanza semantics.

available must be a boolean value, which defines whether the resource is available or not. If the resource is available, show may be set to one of "dnd", "xa", "away", None, "chat" (it is a ValueError to attempt to set show to a non-None value if available is false).

PresenceState objects are ordered by their availability and by their show values. Non-availability sorts lower than availability, and for available presence states the order is in the order of valid values given for the show above.

available¶: As per the argument to the constructor, converted to a bool.

show¶: As per the argument to the constructor.

apply_to_stanza(stanza_obj)¶: Apply the properties of this PresenceState to a Presence stanza_obj. The type_ and show attributes of the object will be modified to fit the values in this object.

classmethod from_stanza(stanza_obj, strict=False)¶

Create and return a new PresenceState object which inherits the presence state as advertised in the given Presence stanza.

If strict is True, the value of show is strictly checked, that is, it is required to be None if the stanza indicates an unavailable state.

The default is not to check this.

PresenceState objects are immutable.

Languages¶

class aioxmpp.structs.LanguageTag(*, tag=None)[source]¶

Implementation of a language tag. This may be a fully RFC5646 compliant implementation some day, but for now it is only very simplistic stub.

There is no input validation of any kind.

LanguageTag instances compare and hash case-insensitively.

classmethod fromstr(s)[source]¶: Create a language tag from the given string s.

Note

This is a stub implementation which merely refers to the given string as the print_str and derives the match_str from that.

match_str[source]¶: The string which is used for matching two lanugage tags. This is the lower-cased version of the print_str.

print_str[source]¶: The stringified language tag.

class aioxmpp.structs.LanguageRange(*, tag=None)[source]¶

Implementation of a language range. This may be a fully RFC4647 compliant implementation some day, but for now it is only very simplistic stub.

There is no input validation of any kind.

LanguageRange instances compare and hash case-insensitively.

classmethod fromstr(s)[source]¶: Create a language tag from the given string s.

Note

This is a stub implementation which merely refers to the given string as the print_str and derives the match_str from that.

strip_rightmost()[source]¶

Strip the rightmost part of the language range. If the new rightmost part is a singleton or x (i.e. starts an extension or private use part), it is also stripped.

Return the newly created LanguageRange.

match_str[source]¶: The string which is used for matching two lanugage tags. This is the lower-cased version of the print_str.

print_str[source]¶: The stringified language tag.

class aioxmpp.structs.LanguageMap[source]¶

A dict subclass specialized for holding LanugageTag instances as keys.

In addition to the interface provided by dict, instances of this class also have the following method:

lookup(language_ranges)[source]¶

Perform an RFC4647 language range lookup on the keys in the dictionary. language_ranges must be a sequence of LanguageRange instances.

Return the entry in the dictionary with a key as produced by lookup_language. If lookup_language does not find a match and the mapping contains an entry with key None, that entry is returned, otherwise KeyError is raised.

Functions for working with language tags¶

aioxmpp.structs.basic_filter_languages(languages, ranges)[source]¶

Filter languages using the string-based basic filter algorithm described in RFC4647.

languages must be a sequence of LanguageTag instances which are to be filtered.

ranges must be an iterable which represent the basic language ranges to filter with, in priority order. The language ranges must be given as LanguageRange objects.

Return an iterator of languages which matched any of the ranges. The sequence produced by the iterator is in match order and duplicate-free. The first range to match a language yields the language into the iterator, no other range can yield that language afterwards.

aioxmpp.structs.lookup_language(languages, ranges)[source]¶

Look up a single language in the sequence languages using the lookup mechansim described in RFC4647. If no match is found, None is returned. Otherwise, the first matching language is returned.

languages must be a sequence of LanguageTag objects, while ranges must be an iterable of LanguageRange objects.

`structs` — Simple data holders for common data types¶

Stanza types¶

Jabber IDs¶

Presence¶

Languages¶

Functions for working with language tags¶

aioxmpp

Table Of Contents

Navigation

Related Topics

structs — Simple data holders for common data types¶

Stanza types¶

Jabber IDs¶

Presence¶

Languages¶

Functions for working with language tags¶

aioxmpp

Table Of Contents

Navigation

Related Topics

Quick search

`structs` — Simple data holders for common data types¶