# `avatar` — User avatar support (XEP-0084)

This module provides support for publishing and retrieving user avatars as per User Avatar.

## Services

The following service is provided by this subpackage:

`AvatarService`(client, **kwargs) | Access and publish User Avatars (XEP-0084).

The detailed documentation of the classes follows:

class `aioxmpp.``AvatarService`

  Access and publish User Avatars (XEP-0084). Fallback to vCard based avatars (XEP-0153) if no PEP avatar is available.

  This service provides an interface for accessing the avatar of other entities in the network, getting notifications on avatar changes and publishing an avatar for this entity.

  Changed in version 0.10: Support for vCard-Based Avatars was added.

  Observing avatars:

  Note

  `AvatarService` only caches the metadata, not the actual image data. This is the job of the caller.

  signal `on_metadata_changed`(jid, metadata)

    Fires when avatar metadata changes.

    Parameters:

    - jid – The JID which the avatar belongs to.
    - metadata (a sequence of `AbstractAvatarDescriptor` instances) – The new metadata descriptors.

  coroutine `get_avatar_metadata`(jid, *, require_fresh=False, disable_pep=False)

    Retrieve a list of avatar descriptors.

    Parameters:

    - jid (`aioxmpp.JID`) – the JID for which to retrieve the avatar metadata.
    - require_fresh (`bool`) – if true, do not return results from the avatar metadata chache, but retrieve them again from the server.
    - disable_pep (`bool`) – if true, do not try to retrieve the avatar via pep, only try the vCard fallback. This usually only useful when querying avatars via MUC, where the PEP request would be invalid (since it would be for a full jid).

    Returns: | an iterable of avatar descriptors.
    Return type: | a `list` of `AbstractAvatarDescriptor` instances

    Returning an empty list means that the avatar not set.

    We mask a `XMPPCancelError` in the case that it is `feature-not-implemented` or `item-not-found` and return an empty list of avatar descriptors, since this is semantically equivalent to not having an avatar.

    Note

    It is usually an error to get the avatar for a full jid, normally, the avatar is set for the bare jid of a user. The exception are vCard avatars over MUC, where the IQ requests for the vCard may be translated by the MUC server. It is recommended to use the disable_pep option in that case.

  coroutine `subscribe`(jid)

    Explicitly subscribe to metadata change notifications for jid.

  Publishing avatars:

  coroutine `publish_avatar_set`(avatar_set)

    Make avatar_set the current avatar of the jid associated with this connection.

    If `synchronize_vcard` is true and PEP is available the vCard is only synchronized if the PEP update is successful.

    This means publishing the `image/png` avatar data and the avatar metadata set in pubsub. The avatar_set must be an instance of `AvatarSet`. If `synchronize_vcard` is true the avatar is additionally published in the user vCard.

  coroutine `disable_avatar`()

    Temporarily disable the avatar.

    If `synchronize_vcard` is true, the vCard avatar is disabled (even if disabling the PEP avatar fails).

    This is done by setting the avatar metadata node empty and if `synchronize_vcard` is true, downloading the vCard, removing the avatar data and re-uploading the vCard.

    This method does not error if neither protocol is active.

    Raises: | aioxmpp.errors.GatherError – if an exception is raised by the spawned tasks.

  coroutine `wipe_avatar`()

    Remove all avatar data stored on the server.

    If `synchronize_vcard` is true, the vCard avatar is disabled even if disabling the PEP avatar fails.

    This is equivalent to `disable_avatar()` for vCard-based avatars, but will also remove the data PubSub node for PEP avatars.

    This method does not error if neither protocol is active.

    Raises: | aioxmpp.errors.GatherError – if an exception is raised by the spawned tasks.

  Configuration:

  `synchronize_vcard`

    Set this property to true to enable publishing the a vCard avatar.

    This property defaults to false. For the setting true to have effect, you have to publish your avatar with `publish_avatar_set()` or `disable_avatar()` after this switch has been set to true.

  `advertise_vcard`

    Set this property to false to disable advertisement of the vCard avatar via presence broadcast.

    Note, that this reduces traffic, since it makes the presence stanzas smaller and we no longer have to recalculate the hash, this also disables vCard advertisement for all other ressources of the bare local jid, by the business rules of XEP-0153.

    Note that, when enabling this feature again the vCard has to be fetched from the server to recalculate the hash.

  `avatar_pep`

    The PEP descriptor for claiming the avatar metadata namespace. The value is a `RegisteredPEPNode`, whose `notify` property can be used to disable or enable the notification feature.

  `metadata_cache_size` = 200

    Maximum number of cache entries in the avatar metadata cache.

    This is mostly a measure to prevent malicious peers from exhausting memory by spamming vCard based avatar metadata for different resources.

    New in version 0.10.

## Data Representation

The following class is used to describe the possible locations of an avatar image:

class `aioxmpp.avatar.``AvatarSet`

  A list of sources of an avatar.

  Exactly one of the sources must include image data in the `image/png` format. The others provide the location of the image data as an URL.

  Adding pointer avatar data is not yet supported.

  `add_avatar_image`(mime_type, *, id_=None, image_bytes=None, width=None, height=None, url=None, nbytes=None)

    Add a source of the avatar image.

    All sources of an avatar image added to an avatar set must be the same image, in different formats and sizes.

    Parameters:

    - mime_type – The MIME type of the avatar image.
    - id – The SHA1 of the image data.
    - nbytes – The size of the image data in bytes.
    - image_bytes – The image data, this must be supplied only in one call.
    - url – The URL of the avatar image.
    - height – The height of the image in pixels (optional).
    - width – The width of the image in pixels (optional).

    id_ and nbytes may be omitted if and only if image_data is given and mime_type is `image/png`. If they are supplied and image data is given, they are checked to match the image data.

    It is the caller’s responsibility to assure that the provided links exist and the files have the correct SHA1 sums.

class `aioxmpp.avatar.service.``AbstractAvatarDescriptor`

  Description of the properties of and how to retrieve a specific avatar.

  The following attribues are available for all instances:

  `remote_jid`

    The remote JID this avatar belongs to.

  `id_`

    The SHA1 of the image encoded as hexadecimal number in ASCII.

    This is the original value returned from the underlying protocol and should be used for any further interaction with the underlying protocol.

  `normalized_id`

    The normalized SHA1 of the image data.

    This is supposed to be used for caching and comparison.

  `can_get_image_bytes_via_xmpp`

    Return whether `get_image_bytes()` raises `NotImplementedError`.

  `has_image_data_in_pubsub`

    Whether the image can be retrieved from PubSub.

    Deprecated since version 0.10: Use `can_get_image_bytes_via_xmpp` instead.

    As we support vCard based avatars now the name of this is misleading.

    This attribute will be removed in aioxmpp 1.0

  The following attributes may be `None` and are supposed to be used as hints for selection of the avatar to download:

  `nbytes`

    The size of the avatar image data in bytes.

  `width`

    The width of the avatar image in pixels.

    This is `None` if this information is not supplied.

  `height`

    The height of the avatar image in pixels.

    This is `None` if this information is not supplied.

  `mime_type`

    The MIME type of the image data.

  If this attribute is not `None` it is an URL that points to the location of the avatar image:

  `url`

    The URL where the avatar image data can be found.

    This may be `None` if the avatar is not given as an URL of the image data.

  The image data belonging to the descriptor can be retrieved by the following coroutine:

  coroutine `get_image_bytes`()

    Try to retrieve the image data corresponding to this avatar descriptor.

    Returns: | the image contents
    Return type: | `bytes`

    Raises:

    - NotImplementedError – if we do not implement the capability to retrieve the image data of this type. It is guaranteed to not raise `NotImplementedError` if `can_get_image_bytes_via_xmpp` is true.
    - RuntimeError – if the image data described by this descriptor is not at the specified location.
    - aiomxpp.XMPPCancelError – if trying to retrieve the image data causes an XMPP error.

## Helpers

`aioxmpp.avatar.``normalize_id`(id_)

  Normalize a SHA1 sum encoded as hexadecimal number in ASCII.

  This does nothing but lowercase the string as to enable robust comparison.

## How to work with avatar descriptors

One you have retrieved the avatar descriptor list, the correct way to handle it in the application:

1. Select the avatar you prefer based on the `can_get_image_bytes_via_xmpp`, and metadata information (`mime_type`, `width`, `height`, `nbytes`). If you cache avatar images it might be a good choice to choose an avatar image you already have cached based on `normalized_id`.
2. If `can_get_image_bytes_via_xmpp` is true, try to retrieve the image by `get_image_bytes()`; if it is false try to retrieve the object at the URL `url`.