djblets.avatars.services¶

Djblets Avatar Services.

class AvatarService(settings_manager_class)¶

Bases: object

A service that provides avatar support.

At the very least, subclasses must set:

avatar_service_id
name

as well as override the get_avatar_urls_uncached() method.

get_etag_data() has a default implementation but it should be overridden for caching.

avatar_service_id = None¶

The avatar service’s ID.

This must be unique for every avatar service subclass.

name = None¶: The avatar service’s human-readable name.

template_name = 'avatars/avatar.html'¶: The template for rendering the avatar as HTML.

config_form_class = None¶

consent_requirement_id = None¶

The ID of a consent requirement governing use of this avatar service.

If provided, and if consent requirements are enforced by the application, then the service will only be used for a user if consent has been granted.

hidden = False¶

Whether or not the avatar service is hidden from users.

Hidden avatar services are not exposed to users and are intended to be used only internally, such as with extensions providing bots.

__init__(settings_manager_class)¶

Initialize the avatar service.

Parameters:: settings_manager_class (type) – The AvatarSettingsManager subclass to use for managing settings.

classmethod is_configurable()¶

Return whether or not the service is configurable.

Returns:: Whether or not the service is configurable.
Return type:: bool

get_configuration_form(user, *args, **kwargs)¶

Return an instantiated configuration form.

Parameters:

user (django.contrib.auth.models.User) – The user.
*args (tuple) – Additional positional arguments to pass to the configuration form constructor.
**kwargs (dict) – Additional keyword arguments to pass to the configuration form constructor.

Returns:

The form, instantiated with the user’s configuration, or None if the service is not configurable (i.e., does not have a configuration form).

Return type:

djblets.avatars.forms.AvatarServiceConfigForm

get_avatar_urls(request, user, size)¶

Render the avatar URLs for the given user.

The result of calls to this method will be cached on the request for the specified user, service, and size, if a request is provided.

Parameters:

request (django.http.HttpRequest) – The HTTP request. This can be None if not available.
user (django.contrib.auth.models.User) – The user for whom the avatar URLs are to be retrieved.
size (int) – The requested avatar size (height and width) in pixels.

Returns:

A dictionary mapping resolutions to URLs as django.utils.safestring.SafeText objects The dictionary must support at least the following resolutions:

'1x':: The user’s regular avatar.
'2x':: The user’s avatar at twice the resolution.
'3x':: The user’s avatar at three times the resolution.

Any key except for '1x' may be None.

The URLs must be safe, or rendering errors will occur. Explicitly sanitize them and use django.utils.html.mark_safe().

Return type:

dict

get_avatar_urls_uncached(user, size)¶

Return the avatar URLs for the given user.

Subclasses must override this to provide the actual URLs.

Parameters:

user (django.contrib.auth.models.User) – The user for whom the avatar URLs are to be retrieved.
size (int, optional) – The requested avatar size (height and width) in pixels.

Returns:

A dictionary of the URLs for the requested user. The dictionary will have the following keys:

'1x': The user’s regular avatar.
'2x': The user’s avatar at twice the resolution (e.g., for retina displays). This may be None.
'3x': The user’s avatar at three times the resolution. This may be None.

The URLs returned by this function must be safe, i.e., they should be able to be injected into HTML without being sanitized. They should be marked safe explicitly via django.utils.html.mark_safe().

Return type:

dict

render(request, user, size, template_name=None)¶

Render a user’s avatar to HTML.

By default, this is rendered with the template specified by the template_name attribute. This behaviour can be overridden by subclasses.

Parameters:

request (django.http.HttpRequest) – The HTTP request. This can be None if not available.
user (django.contrib.auth.models.User) – The user for whom the avatar is to be rendered.
size (int) – The requested avatar size (height and width) in pixels.
template_name (unicode, optional) – The name of the template to use for rendering.

Returns:

The rendered avatar HTML.

Return type:

unicode

cleanup(user)¶

Clean up state when a user no longer uses this service.

Subclasses may use this to clean up database state or remove files. By default, this method does nothing.

Parameters:: user (django.contrib.auth.models.User) – The user who is no longer using the service.

get_etag_data(user)¶

Return ETag data for the user’s avatar.

ETags (Entity Tags) are used in caching HTTP request results. The data returned by this function should be a list of unicode strings that uniquely represent the avatar service and its configuration.

Subclasses must implement this method.

Parameters:: user (django.contrib.auth.models.User) – The user.
Returns:: The uniquely identifying information for the user’s avatar.
Return type:: list of unicode

class FallbackService(settings_manager_class)¶

Bases: AvatarService

An avatar service used as a fallback.

This will display a simple avatar showing the first two characters of the user’s username, displayed on top of a background with a color based on the username.

This will automatically be used as a fallback if no other avatar backends are usable for the user.

avatar_service_id = 'fallback'¶

The avatar service’s ID.

This must be unique for every avatar service subclass.

name = 'Fallback'¶: The avatar service’s human-readable name.

template_name = 'avatars/fallback.html'¶: The template for rendering the avatar as HTML.

hidden = True¶

Whether or not the avatar service is hidden from users.

Hidden avatar services are not exposed to users and are intended to be used only internally, such as with extensions providing bots.

render(request, user, size, template_name=None)¶

Render a user’s avatar to HTML.

Parameters:

request (django.http.HttpRequest) – The HTTP request.
user (django.contrib.auth.models.User) – The user for whom the avatar is to be rendered.
size (int) – The requested avatar size (height and width) in pixels.
template_name (unicode, optional) – The name of the template to use for rendering.

Returns:

The rendered avatar HTML.

Return type:

django.utils.safestring.SafeText

get_bg_color(user)¶

Return a background color for the avatar.

This will compute a basic HSL color for the avatar, based on the username.

Parameters:: user (django.contrib.auth.models.User) – The user to generate the color for.
Returns:: The resulting HSL color definition.
Return type:: unicode

get_avatar_urls_uncached(user, size)¶

Return the Gravatar URLs for the requested user.

Parameters:

user (django.contrib.auth.models.User) – The user whose avatar URLs are to be fetched.
size (int) – The size (in pixels) the avatar is to be rendered at.

Returns: dict: A dictionary containing the URLs of the user’s avatars at normal- and high-DPI.

get_etag_data(user)¶

Return the ETag data for the user’s avatar.

Parameters:: user (django.contrib.auth.models.User) – The user.
Returns:: The uniquely identifying information for the user’s avatar.
Return type:: list of unicode

class FileUploadService(settings_manager_class)¶

Bases: AvatarService

An avatar service for uploaded images.

avatar_service_id = 'file-upload'¶

The avatar service’s ID.

This must be unique for every avatar service subclass.

name = 'File Upload'¶: The avatar service’s human-readable name.

config_form_class¶: alias of FileUploadServiceForm

property file_path_prefix¶

The storage location for uploaded avatars.

This will be prepended to the path of all uploaded files. By default, it is controlled by the UPLOADED_AVATARS_PATH setting.

get_unique_filename(filename)¶

Create a unique filename.

The unique filename will be the original filename suffixed with a generated UUID.

Parameters:: filename (unicode) – The filename, excluding the extension.
Returns:: The unique filename.
Return type:: unicode

get_avatar_urls_uncached(user, size)¶

Return the avatar URLs for the requested user.

Parameters:

user (django.contrib.auth.models.User) – The user whose avatar URLs are to be fetched.
size (int) – The size (in pixels) the avatar is to be rendered at.

Returns: dict: A dictionary containing the URLs of the user’s avatars at normal- and high-DPI.

cleanup(user)¶

Clean up the uploaded file.

This will delete the uploaded file from the storage.

Parameters:: user (django.contrib.auth.models.User) – The user.

get_etag_data(user)¶

Return the ETag data for the user’s avatar.

Parameters:: user (django.contrib.auth.models.User) – The user.
Returns:: The uniquely identifying information for the user’s avatar.
Return type:: list of unicode

class GravatarService(settings_manager_class)¶

Bases: AvatarService

An avatar service for providing Gravatars.

avatar_service_id = 'gravatar'¶

The avatar service’s ID.

This must be unique for every avatar service subclass.

name = 'Gravatar'¶: The avatar service’s human-readable name.

consent_requirement_id = 'gravatar'¶

The ID of a consent requirement governing use of this avatar service.

If provided, and if consent requirements are enforced by the application, then the service will only be used for a user if consent has been granted.

get_avatar_urls_uncached(user, size)¶

Return the Gravatar URLs for the requested user.

Parameters:

user (django.contrib.auth.models.User) – The user whose avatar URLs are to be fetched.
size (int) – The size (in pixels) the avatar is to be rendered at.

Returns: dict: A dictionary containing the URLs of the user’s avatars at normal- and high-DPI.

get_etag_data(user)¶

Return the ETag data for the user’s avatar.

Parameters:: user (django.contrib.auth.models.User) – The user.
Returns:: The uniquely identifying information for the user’s avatar.
Return type:: list of unicode

class URLAvatarService(settings_manager_class)¶

Bases: AvatarService

An avatar service for settings absolute URLs for avatars.

This avatar service is not available to users and is meant to be used by bots from extensions to provide their own avatars.

Automation users can be configured to use this service with the following code:

from djblets.avatars.services import URLAvatarService


avatar_services = get_avatar_service_registry()
service = avatar_services.get_avatar_service(
    URLAvatarService.avatar_service_id)

service.setup(
    user,
    {
        '1x': 'http://example.com/static/avatar.png',
        '2x': 'http://example.com/static/avatar@2x.png',
    })

avatar_service_id = 'url'¶

The avatar service’s ID.

This must be unique for every avatar service subclass.

name = 'URL Avatar Service'¶: The avatar service’s human-readable name.

hidden = True¶

Whether or not the avatar service is hidden from users.

Hidden avatar services are not exposed to users and are intended to be used only internally, such as with extensions providing bots.

setup(user, urls)¶

Set up this avatar service for the given user.

The user will be configured to use this service as their avatar service and the given URLs will be used for their avatars.

Parameters:

user (django.contrib.auth.models.User) – The user to set the URLs for.
urls (dict) – A dictionary mapping resolutions (‘1x’, ‘2x’, etc.) to absolute URLs.

get_avatar_urls_uncached(user, size)¶

Return the avatar URLs for the requested user.

Parameters:

user (django.contrib.auth.models.User) – The user whose avatar URLs are to be fetched.
size (int) – The size (in pixels) the avatar is to be rendered at.

Returns:

A dictionary mapping resolutions (‘1x’, ‘2x’, etc.) to the user’s avatar URLs.

Return type:

dict

get_etag_data(user)¶

Return the ETag data for the user’s avatar.

Parameters:: user (django.contrib.auth.models.User) – The user.
Returns:: The uniquely identifying information for the user’s avatar.
Return type:: list of unicode