presence — Peer presence bookkeeping¶
This module provides a Service to track the presence of peers, no matter whether they are in the roster or not.
New in version 0.4.
- class aioxmpp.presence.Service(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 enqueue_stanza(), 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)¶
Return the stanza of the resource with the most available presence.
The resources are sorted using the ordering defined on PresenceState.
- 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 recieved 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.
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.
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.