def get_avatar_metadata(self, jid, *, require_fresh=False,
                            disable_pep=False):
        """
        Retrieve a list of avatar descriptors.

        :param jid: the JID for which to retrieve the avatar metadata.
        :type jid: :class:`aioxmpp.JID`
        :param require_fresh: if true, do not return results from the
            avatar metadata chache, but retrieve them again from the server.
        :type require_fresh: :class:`bool`
        :param disable_pep: 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).
        :type disable_pep: :class:`bool`

        :returns: an iterable of avatar descriptors.
        :rtype: a :class:`list` of
            :class:`~aioxmpp.avatar.service.AbstractAvatarDescriptor`
            instances

        Returning an empty list means that the avatar not set.

        We mask a :class:`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.
        """

        if require_fresh:
            self._metadata_cache.pop(jid, None)
        else:
            try:
                return self._metadata_cache[jid]
            except KeyError:
                pass

        if disable_pep:
            metadata = []
        else:
            metadata = yield from self._get_avatar_metadata_pep(jid)

        # try the vcard fallback, note: we don't try this
        # if the PEP avatar is disabled!
        if not metadata and jid not in self._has_pep_avatar:
            metadata = yield from self._get_avatar_metadata_vcard(jid)

        # if a notify was fired while we waited for the results, then
        # use the version in the cache, this will mitigate the race
        # condition because if our version is actually newer we will
        # soon get another notify for this version change!
        if jid not in self._metadata_cache:
            self._update_metadata(jid, metadata)
        return self._metadata_cache[jid]
Retrieve a list of avatar descriptors.

        :param jid: the JID for which to retrieve the avatar metadata.
        :type jid: :class:`aioxmpp.JID`
        :param require_fresh: if true, do not return results from the
            avatar metadata chache, but retrieve them again from the server.
        :type require_fresh: :class:`bool`
        :param disable_pep: 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).
        :type disable_pep: :class:`bool`

        :returns: an iterable of avatar descriptors.
        :rtype: a :class:`list` of
            :class:`~aioxmpp.avatar.service.AbstractAvatarDescriptor`
            instances

        Returning an empty list means that the avatar not set.

        We mask a :class:`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.