djblets.avatars.services.base¶

The base avatar service class implementation.

class AvatarService(settings_manager_class)[source]¶

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

The avatar service’s ID.

This must be unique for every avatar service subclass.

name = None[source]¶

The avatar service’s human-readable name.

template_name = 'avatars/avatar.html'[source]¶

The template for rendering the avatar as HTML.

config_form_class = None[source]¶

consent_requirement_id = None[source]¶

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

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

Initialize the avatar service.

Parameters:

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

classmethod is_configurable()[source]¶

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

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

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

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

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

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

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

__annotations__ = {}¶