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[source]

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.

async get_avatar_metadata(jid, *, require_fresh=False, disable_pep=False)[source]

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 cache, 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.

async subscribe(jid)[source]

Explicitly subscribe to metadata change notifications for jid.

Publishing avatars:

async publish_avatar_set(avatar_set)[source]

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.

async disable_avatar()[source]

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.

async wipe_avatar()[source]

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 resources 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[source]

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)[source]

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[source]

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

The following attributes 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:

async get_image_bytes()[source]

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

Returns

the image contents

Return type

bytes

Raises

Helpers

aioxmpp.avatar.normalize_id(id_)[source]

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.