djblets.avatars.registry¶

A registry for managing avatar services.

class AvatarServiceRegistry[source]¶

A registry for avatar services.

This registry manages a set of avatar services (see djblets.avatars.services.gravatar for an example). The registries are saved to the database and require the use of the djblets.siteconfig app.

Changed in version 1.0.3: The avatar configuration is now retrieved from and immediately written to the current SiteConfiguration, in order to ensure that the list of enabled avatar services and the default service are never stale. This differs from 1.0.0 through 1.0.2, where the callers could make change to the local state without ever risking it being written to the database (which is generally not the desired behavior anyway).

ENABLED_SERVICES_KEY = 'avatars_enabled_services'[source]¶: The key name for the list of enabled services.

ENABLE_CONSENT_CHECKS = 'avatars_enable_consent_checks'[source]¶: The key name for specifying whether consent must be checked.

DEFAULT_SERVICE_KEY = 'avatars_default_service'[source]¶: The key name for the default service.

lookup_error_class[source]¶: alias of djblets.avatars.errors.AvatarServiceNotFoundError

default_avatar_service_classes = [<class 'djblets.avatars.services.gravatar.GravatarService'>, <class 'djblets.avatars.services.url.URLAvatarService'>][source]¶: The default avatar service classes.

fallback_service_class[source]¶: alias of djblets.avatars.services.fallback.FallbackService

settings_manager_class[source]¶: alias of djblets.avatars.settings.AvatarSettingsManager

get_avatar_service(avatar_service_id)[source]¶

Return an instance of the requested avatar service.

The instance will be instantiated with the settings_manager_class.

Parameters: avatar_service_id (unicode) – The unique identifier for the avatar service.
Returns: The requested avatar service, or None if not found.
Return type: djblets.avatars.services.base.AvatarService
Raises: djblets.avatars.errors.DisabledServiceError – The requested service is disabled.

property configurable_services[source]¶

Yield the enabled service instances that have configuration forms.

Yields: tuple – The enabled service instances that have configuration forms.

property enabled_services[source]¶

Return the enabled services.

Returns: The set of enabled avatar services, as djblets.avatars.service.AvatarService instances.
Return type: set

set_enabled_services(services, save=True)[source]¶

Set the enabled services.

If the default service would be disabled by setting the set of enabled services, the default service will be set to None.

Parameters

services (set) – The set of services to set as enabled. Each element must be a subclass of AvatarService.
save (bool, optional) – Whether to save the settings after setting the list of enabled services. The default is to immediately save.

Raises

djblets.avatars.errors.AvatarServiceNotFoundError – This exception is raised when an unknown avatar service is enabled.

property default_service[source]¶

The default avatar service.

Returns: The default avatar service, or None if there isn’t one.
Return type: djblets.avatars.services.AvatarService

property fallback_service[source]¶: The fallback service used if no other services are available.

set_default_service(service, save=True)[source]¶

Set the default avatar service.

Parameters

service (type) – The avatar service to set as default.
save (bool) – Whether or not the registry should be saved to the database afterwards.

Raises

djblets.avatars.errors.AvatarServiceNotFoundError – Raised if the service cannot be found.
djblets.avatars.errors.DisabledServiceError – Raised if the service is not enabled.

has_service(service_id)[source]¶

Return whether or not the avatar service ID is registered.

Parameters: service_id (unicode) – The service’s unique identifier.
Returns: Whether or not the service ID is registered.
Return type: bool

disable_service(service, save=True)[source]¶

Disable an avatar service.

This has no effect if the service is already disabled. If the default service becomes be disabled, it becomes None.

Parameters

service (type) – The service to disable
save (bool, optional) – Whether or not the avatar service registry will be saved to the database after disabling the service. This defaults to True.

Raises

djblets.avatars.errors.AvatarServiceNotFoundError – This is raised if the service is not registered.

disable_service_by_id(service_id, save=True)[source]¶

Disable an avatar service based on its ID.

This allows for disabling services that may or may not be registered, for instance those that were previously added by an extension that is no longer available.

This has no effect if the service is already disabled. If the default service becomes be disabled, it becomes None.

Parameters

service_id (unicode) – The ID of the service to disable.
save (bool, optional) – Whether or not the avatar service registry will be saved to the database after disabling the service. This defaults to True.

Raises

djblets.avatars.errors.AvatarServiceNotFoundError – This is raised if the service is not registered.

enable_service(service, save=True)[source]¶

Enable an avatar service.

Parameters

service (type) – The service to enable. This must be a subclass of AvatarService.
save (bool, optional) – Whether or not the avatar service registry will be saved to the database after enabling the service. This defaults to True.

Raises

djblets.avatars.errors.AvatarServiceNotFoundError – This is raised if the service is not registered.

enable_service_by_id(service_id, save=True)[source]¶

Enable an avatar service.

Parameters

service_id (unicode) – The ID of the service to enable. Callers must take care to ensure this matches a service stored in the registry.
save (bool, optional) – Whether or not the avatar service registry will be saved to the database after enabling the service. This defaults to True.

Raises

djblets.avatars.errors.AvatarServiceNotFoundError – This is raised if the service is not registered.

is_enabled(service)[source]¶

Return whether or not the given avatar service is enabled.

Parameters: service (type) – The service to check. This must be a ubclass of AvatarService.
Returns: Whether or not the service ID is registered.
Return type: bool

unregister(service)[source]¶

Unregister an avatar service.

Note that unregistering a service does not disable it. That must be done manually through disable_service(). Disabling is a persistent operation that affects all server instances now and in the future, while unregistering may occur during the normal shutdown of a particular thread or process (especially if done through an extension).

Parameters: service (type) – The avatar service to unregister.
Raises: djblets.avatars.errors.AvatarServiceNotFoundError – Raised if the specified service cannot be found.

get_defaults()[source]¶

Yield the default avatar services.

Subclasses should override the default_avatar_service_classes attribute instead of this in most cases.

save()[source]¶

Save the avatar configuration to the database.

As the avatar configuration is stored in the SiteConfiguration, this method will save any pending configuration, synchronizing it to all other processes/servers.

If there are pending avatar configuration changes (due to passing save=False to some methods), and there’s a separate call to SiteConfiguration.save() without calling this method, the new avatar configuration will still be saved.

for_user(user, service_id=None, allow_consent_checks=True)[source]¶

Return the requested avatar service for the given user.

The following options will be tried:

The requested avatar service (if it is enabled)
The user’s chosen avatar service (if it is enabled)
The default avatar service (which may be None)

Parameters

user (django.contrib.auth.models.User) – The user to retrieve the avatar service for.
service_id (unicode, optional) – The unique identifier of the service that is to be retrieved. If this is None, the default service will be used.
allow_consent_checks (bool, optional) – Whether to allow consent checks to take place, if required by the application settings and avatar backends. This should only be disabled if presenting configuration options or similar.

Returns

An avatar service, or None if one could not be found.

Return type

djblets.avatars.services.base.AvatarService