# `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.