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).

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.

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)

Retrieve a list of avatar descriptors for jid.

The avatar descriptors are returned as a list of instances of AbstractAvatarDescriptor. An empty list means that the avatar is unset.

If require_fresh is true, we will not lookup the avatar metadata from the cache, but make a new pubsub request.

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.

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.

This means publishing the image/png avatar data and the avatar metadata set in pubsub. The avatar_set must be an instance of AvatarSet.

coroutine disable_avatar()

Temporarily disable the avatar.

This is done by setting the avatar metadata node empty.

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.

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 an avatar source retrieved from pubsub.

mime_type[source]

The MIME type of the image data.

id_[source]

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

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

normalized_id[source]

The SHA1 of the image data decoded to a bytes object.

This is supposed to be used for caching.

nbytes[source]

The size of the avatar image data in bytes.

remote_jid[source]

The remote JID this avatar belongs to.

width[source]

The width of the avatar image in pixels.

This is None if this information is not supplied.

height[source]

The height of the avatar image in pixels.

This is None if this information is not supplied.

has_image_data_in_pubsub[source]

Whether the image can be retrieved from PubSub.

url[source]

The URL where the avatar image data can be found.

This is None if has_image_data_in_pubsub is true.

If has_image_data_in_pubsub is true, the image can be retrieved by the following coroutine:

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.