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:
|
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.
Publishing avatars:
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()
ordisable_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
, whosenotify
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.
-
signal
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 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()
raisesNotImplementedError
.
-
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:
-
Helpers¶
How to work with avatar descriptors¶
One you have retrieved the avatar descriptor list, the correct way to handle it in the application:
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 onnormalized_id
.If
can_get_image_bytes_via_xmpp
is true, try to retrieve the image byget_image_bytes()
; if it is false try to retrieve the object at the URLurl
.