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.

Jabber IDs

class aioxmpp.structs.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.structs.PresenceState(available=False, show=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)

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)

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

The string which is used for matching two lanugage tags. This is the lower-cased version of the print_str.

print_str

The stringified language tag.

class aioxmpp.structs.LanguageRange(*, tag=None)

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)

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()

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

The string which is used for matching two lanugage tags. This is the lower-cased version of the print_str.

print_str

The stringified language tag.

class aioxmpp.structs.LanguageMap

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)

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)

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)

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.