presence — Peer presence bookkeeping

This module provides a PresenceClient service to track the presence of peers, no matter whether they are in the roster or not.

New in version 0.4.

class aioxmpp.PresenceClient(client, **kwargs)

The presence service tracks all incoming presence information (this does not include subscription management stanzas, as these are handled by aioxmpp.roster). It is independent of the roster, as directed presence is independent of the roster and still needs to be tracked accordingly.

No method to send directed presence is provided; it would basically just take a stanza and enqueue it in the clients stream, thus being a mere wrapper around send(), without any benefit.

The service provides access to presence information summarized by bare JID or for each full JID individually. An index over the resources of a bare JID is available.

If an error presence is received for a JID, it replaces all known presence information. It is returned for all queries, no matter for which resource the query is. As soon as a non-error presence is received for any resource of the bare JID, the error is cleared.

get_most_available_stanza(peer_jid)

Obtain the stanza describing the most-available presence of the contact.

Parameters

peer_jid (aioxmpp.JID) – Bare JID of the contact.

Return type

aioxmpp.Presence or None

Returns

The presence stanza of the most available resource or None if there is no available resource.

The “most available” resource is the one whose presence state orderest highest according to PresenceState.

If there is no available resource for a given peer_jid, None is returned.

get_peer_resources(peer_jid)

Return a dict mapping resources of the given bare peer_jid to the presence state last received for that resource.

Unavailable presence states are not included. If the bare JID is in a error state (i.e. an error presence stanza has been received), the returned mapping is empty.

get_stanza(peer_jid)

Return the last presence received for the given bare or full peer_jid. If the last presence was unavailable, the return value is None, as if no presence was ever received.

If no presence was ever received for the given bare JID, None is returned.

On presence changes of peers, signals are emitted:

signal on_bare_available(stanza)

Fires when the first resource of a peer becomes available.

signal on_bare_unavailable(stanza)

Fires when the last resource of a peer becomes unavailable or enters error state.

signal on_available(full_jid, stanza)

Fires when a resource becomes available at full_jid. The stanza which caused the availability is handed over as second argument.

This signal always fires after on_bare_available().

signal on_changed(full_jid, stanza)

Fires when a the presence of the resource at full_jid changes, but does not become unavailable or available. The stanza which caused the change is handed over as second argument.

signal on_unavailable(full_jid, stanza)

Fires when the resource at full_jid becomes unavailable, with the stanza causing the unavailability as second argument.

This signal always fires before on_bare_unavailable().

Note

If the resource became unavailable due to an error, the full_jid will not match the from_ attribute of the stanza, as the error is coming from the bare JID.

The three signals on_available(), on_changed() and on_unavailable() never fire for the same stanza.

New in version 0.4.

Changed in version 0.8: This class was formerly known as aioxmpp.presence.Service. It is still available under that name, but the alias will be removed in 1.0.

class aioxmpp.PresenceServer(client, **kwargs)

Manage the presence broadcast by the client.

The PresenceServer manages broadcasting and re-broadcasting the presence of the client as needed.

The presence state is initialised to an unavailable presence. Unavailable presences are not emitted when the stream is established.

Presence information:

state

The currently set presence state (as aioxmpp.PresenceState) which is broadcast when the client connects and when the presence is re-emitted.

This attribute cannot be written. It does not reflect the actual presence seen by others. For example when the client is in fact offline, others will see unavailable presence no matter what is set here.

status

The currently set textual presence status which is broadcast when the client connects and when the presence is re-emitted.

This attribute cannot be written. It does not reflect the actual presence seen by others. For example when the client is in fact offline, others will see unavailable presence no matter what is set here.

priority

The currently set priority which is broadcast when the client connects and when the presence is re-emitted.

This attribute cannot be written. It does not reflect the actual presence seen by others. For example when the client is in fact offline, others will see unavailable presence no matter what is set here.

make_stanza()

Create and return a presence stanza with the current settings.

Returns

Presence stanza

Return type

aioxmpp.Presence

Changing/sending/watching presence:

set_presence(state, status={}, priority=0)

Change the presence broadcast by the client.

Parameters

• state (aioxmpp.PresenceState) – New presence state to broadcast

• status (dict or str) – New status information to broadcast

• priority (int) – New priority for the resource

Returns

Stanza token of the presence stanza or None if the presence is unchanged or the stream is not connected.

Return type

StanzaToken

If the client is currently connected, the new presence is broadcast immediately.

status must be either a string or something which can be passed to the dict constructor. If it is a string, it is wrapped into a dict using {None: status}. The mapping must map LanguageTag objects (or None) to strings. The information will be used to generate internationalised presence status information. If you do not need internationalisation, simply use the string version of the argument.

resend_presence()

Re-send the currently configured presence.

Returns

Stanza token of the presence stanza or None if the stream is not established.

Return type

StanzaToken

Note

set_presence() automatically broadcasts the new presence if any of the parameters changed.

signal on_presence_changed()

Emits after the presence has been changed in the PresenceServer.

signal on_presence_state_changed(new_state)

Emits after the presence state has been changed in the PresenceServer.

This signal does not emit if other parts of the presence (such as priority or status texts) change, while the presence state itself stays the same.

New in version 0.8.

class aioxmpp.presence.Service

Alias of PresenceClient.

Deprecated since version 0.8: The alias will be removed in 1.0.