djblets.avatars.registry¶

A registry for managing avatar services.

class AvatarServiceRegistry¶

Bases: Registry

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'¶

The key name for the list of enabled services.

ENABLE_CONSENT_CHECKS = 'avatars_enable_consent_checks'¶

The key name for specifying whether consent must be checked.

DEFAULT_SERVICE_KEY = 'avatars_default_service'¶

The key name for the default service.

lookup_attrs: Sequence[str] = ('avatar_service_id',)¶

A list of attributes that items can be looked up by.

Type:

list of str

default_errors: RegistryErrorsDict = {'already_registered': 'Could not register avatar service %(item)s: This service is already registered.', 'attribute_registered': 'Could not register avatar service %(attr_value)s: This service is already registered.', 'disabled_service': 'Could not fetch instance of %(service_id)s service: This service is disabled.', 'disabled_service_default': 'Could not set the default service to %(service_id)s: This service is disabled.', 'invalid_attribute': '"%(attr_name)s" is not a registered lookup attribute.', 'load_entry_point': 'Could not load entry point %(entry_point)s: %(error)s.', 'missing_attribute': 'Could not register %(item)s: it does not have a "%(attr_name)s" attribute.', 'not_registered': 'Unknown avatar service %(attr_value)s: This service is not registered.', 'unknown_service_default': 'Could not set the default avatar service to %(service_id)s: This service is not registered.', 'unknown_service_disabled': 'Could not disable unknown avatar service %(service_id)s: This service is not registered.', 'unknown_service_enabled': 'Could not enable unknown avatar service %(service_id)s: This service is not registered.', 'unregister': 'Could not unregister unknown avatar service %(item)s: This service is not registered.'}¶

The default error formatting strings.

If subclasses need to provide additional errors that can be overridden, they should copy DEFAULT_ERRORS and set their copy on the subclass as this attribute.

Type:

dict

lookup_error_class¶

alias of AvatarServiceNotFoundError

default_avatar_service_classes = [<class 'djblets.avatars.services.gravatar.GravatarService'>, <class 'djblets.avatars.services.url.URLAvatarService'>]¶

The default avatar service classes.

fallback_service_class¶

A fallback service to use if others are not available.

New in version 1.0.11.

alias of FallbackService

settings_manager_class¶

The settings manager for avatar services.

This should be changed in a subclass as the default cannot get or set avatar service configurations.

alias of AvatarSettingsManager

__init__()¶

Initialize the avatar service registry.

get_avatar_service(avatar_service_id)¶

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¶

Yield the enabled service instances that have configuration forms.

Yields:

tuple – The enabled service instances that have configuration forms.

property enabled_services¶

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)¶

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¶

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¶

The fallback service used if no other services are available.

set_default_service(service, save=True)¶

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)¶

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)¶

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)¶

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)¶

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)¶

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)¶

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)¶

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()¶

Yield the default avatar services.

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

save()¶

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)¶

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

__annotations__ = {'_items': 'set[RegistryItemType]', '_lock': 'RLock', '_registry': 'dict[str, dict[object, RegistryItemType]]', 'already_registered_error_class': 'Type[AlreadyRegisteredError]', 'default_errors': 'RegistryErrorsDict', 'errors': 'RegistryErrorsDict', 'item_name': 'Optional[str]', 'lookup_attrs': 'Sequence[str]', 'lookup_error_class': 'Type[ItemLookupError]', 'state': 'RegistryState'}¶

__parameters__ = ()¶