djblets.avatars.services.base¶
The base avatar service class implementation.
- class AvatarService(settings_manager_class)¶
Bases:
object
A service that provides avatar support.
At the very least, subclasses must set:
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.
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
) – TheAvatarSettingsManager
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:
- 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:
- 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 beNone
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 beNone
.The URLs must be safe, or rendering errors will occur. Explicitly sanitize them and use
django.utils.html.mark_safe()
.- Return type:
- 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 beNone
.'3x'
: The user’s avatar at three times the resolution. This may beNone
.
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:
- 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 beNone
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:
- 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:
- __annotations__ = {}¶