djblets.extensions.manager¶

Extension manager class for supporting extensions to an application.

class SettingListWrapper(setting_name: str, display_name: str, parent_dict: Union[Dict[str, Any], None, LazySettings] = None)¶

Bases: object

Wraps list-based settings to provide management and ref counting.

This can be used instead of direct access to a list in Django settings to ensure items are never added more than once, and only removed when nothing needs it anymore.

Each item in the list is ref-counted. The initial items from the setting are populated and start with a ref count of 1. Adding items will increment a ref count for the item, adding it to the list if it doesn’t already exist. Removing items reduces the ref count, removing when it hits 0.

__init__(setting_name: str, display_name: str, parent_dict: Union[Dict[str, Any], None, LazySettings] = None) → None¶

Initialize the settings wrapper.

Parameters:

• setting_name (str) – The name of the setting. This is the key in either parent_dict or settings.

• display_name (str) – The display name of the setting, for use in error output.

• parent_dict (dict, optional) – The dictionary containing the setting. If not set, this will fall back to settings.

add(item: Any) → None¶

Add an item to the setting.

If the item is already in the list, it won’t be added again. The ref count will just be incremented.

If it’s a new item, it will be added to the list with a ref count of 1.

Parameters:

item (object) – The item to add.

add_list(items: List[Any]) → None¶

Add a list of items to the setting.

Parameters:

item (list of object) – The list of items to add.

remove(item: Any) → bool¶

Remove an item from the setting.

The item’s ref count will be decremented. If it hits 0, it will be removed from the list.

Parameters:

item (object) – The item to remove.

Returns:

True if the item was removed from the list. False if it was left in due to still having a reference.

Return type:

bool

remove_list(items: List[Any]) → List[Any]¶

Remove a list of items from the setting.

Parameters:

items (list of object) – The list of items to remove.

Returns:

The list of items that were removed (or that did not exist in the list).

Return type:

list of object

class ExtensionManager(key: str)¶

Bases: object

A manager for all extensions.

ExtensionManager manages the extensions available to a project. It can scan for new extensions, enable or disable them, determine dependencies, install into the database, and uninstall.

An installed extension is one that has been installed by a Python package on the system.

A registered extension is one that has been installed and information then placed in the database. This happens automatically after scanning for an installed extension. The registration data stores whether or not it’s enabled, and stores various pieces of information on the extension.

An enabled extension is one that is actively enabled and hooked into the project.

Each project should have one ExtensionManager.

Projects can set settings.EXTENSIONS_ENABLED_BY_DEFAULT to a list of extension IDs (class names) that should be automatically enabled when their registrations are first created. This will ensure that those extensions will default to being enabled. If an administrator later disables the extension, it won’t automatically re-renable unless the registration is removed.

should_install_static_media = True¶

Whether to explicitly install static media files from packages.

By default, we install static media files if PRODUCTION is True. Subclasses can override this to factor in other settings, if needed.

VERSION_SETTINGS_KEY = '_extension_installed_version'¶

The key in the settings indicating the last known configured version.

This setting is used to differentiate the version of an extension installed locally on a system and the last version that completed database-related installation/upgrade steps.

This should not be changed by subclasses, and generally is not needed outside of this class.

__init__(key: str) → None¶

Initialize the extension manager.

Parameters:

key (str) – A key that’s unique to this extension manager instance. It must also be the same key used to look up Python entry points.

middleware_classes: List[str]¶

Extension middleware class names, ordered by dependencies.

Type:

list of str

get_url_patterns() → List[DynamicURLResolver]¶

Return the URL patterns for the Extension Manager.

This should be included in the root urlpatterns for the site.

Returns:

The list of URL patterns for the Extension Manager.

Return type:

list

is_expired() → bool¶

Returns whether or not the extension state is possibly expired.

Extension state covers the lists of extensions and each extension’s configuration. It can expire if the state synchronization value falls out of cache or is changed.

Each ExtensionManager has its own state synchronization cache key.

Returns:

Whether the state has expired.

Return type:

bool

clear_sync_cache() → None¶

Clear the extension synchronization state.

This will force every process to reload the extension list and settings.

get_absolute_url() → str¶

Return an absolute URL to the view for listing extensions.

By default, this simply looks up the “extension-list” URL.

Subclasses can override this to provide a more specific URL, but should take care to cache the result in order to avoid unwanted lookups caused by URL resolver cache flushes.

Returns:

The URL to the extension list view.

Return type:

str

get_can_disable_extension(registered_extension: RegisteredExtension) → bool¶

Return whether an extension can be disabled.

Extensions can only be disabled if already enabled or there’s a load error.

Parameters:

registered_extension (djblets.extensions.models.RegisteredExtension) – The registered extension entry representing the extension.

Returns:

True if the extension can be disabled. False if it cannot.

Return type:

bool

get_can_enable_extension(registered_extension: RegisteredExtension) → bool¶

Return whether an extension can be enabled.

Extensions can only be enabled if already disabled.

Parameters:

registered_extension (djblets.extensions.models.RegisteredExtension) – The registered extension entry representing the extension.

Returns:

True if the extension can be enabled. False if it cannot.

Return type:

bool

get_enabled_extension(extension_id: str) → Optional[Extension]¶

Return an enabled extension for the given exetnsion ID.

Parameters:

extension_id (str) – The ID of the extension.

Returns:

The extension matching the given ID, if enabled. If disabled or not found, None will be returned.

Return type:

djblets.extensions.extension.Extension

get_enabled_extensions() → List[Extension]¶

Return a list of all enabled extensions.

Returns:

All extension instances currently enabled.

Return type:

list of djblets.extensions.extension.Extension

get_installed_extensions() → List[Type[Extension]]¶

Return a list of all installed extension classes.

Returns:

All extension classes currently registered.

Return type:

list of type

get_installed_extension(extension_id: str) → Type[Extension]¶

Return the installed extension class with the given extension ID.

The extension class must be available on the system and must be importable.

Parameters:

extension_id (str) – The ID of the extension.

Returns:

The extension class matching the ID.

Return type:

type

Raises:

djblets.extensions.errors.InvalidExtensionError – The extension could not be found.

get_dependent_extensions(dependency_extension_id: str) → List[str]¶

Return a list of all extension IDs required by an extension.

Parameters:

dependency_extension_id (str) – The ID of the extension to retrieve dependencies for.

Returns:

The list of extension IDs required by this extension.

Return type:

list of str

Raises:

djblets.extensions.errors.InvalidExtensionError – The extension could not be found.

enable_extension(extension_id: str) → Optional[Extension]¶

Enable an extension.

Enabling an extension will install any data files the extension may need, any tables in the database, perform any necessary database migrations, and then will start up the extension.

If the extension is already enabled, this will do nothing.

After enabling the extension, the djblets.extensions.signals.extension_enabled signal will be emitted.

Parameters:

extension_id (str) – The ID of the extension to enable.

Returns:

The extension instance.

Return type:

djblets.extensions.extension.Extension

Raises:

• djblets.extensions.errors.EnablingExtensionError – There was an error enabling an extension. The error information will be provided.

• djblets.extensions.errors.InvalidExtensionError – The extension could not be found.

disable_extension(extension_id: str) → None¶

Disable an extension.

Disabling an extension will remove any data files the extension installed and then shut down the extension and all of its hooks.

It will not delete any data from the database.

After disabling the extension, the djblets.extensions.signals.extension_disabled signal will be emitted.

Parameters:

extension_id (str) – The ID of the extension to disable.

Raises:

djblets.extensions.errors.InvalidExtensionError – The extension could not be found.

install_extension(install_url: str, package_name: str) → None¶

Install an extension from a remote source.

This will attempt to install or upgrade an extension package using easy_install.

Deprecated since version 3.3: This support has been removed. It’s never worked quite right, didn’t keep up with modern Python Wheel packages, and was previously documented as not being fully-supported.

Parameters:

• install_url (str) – The URL of the package to install.

• package_name (str) – The name of the package being installed.

Raises:

djblets.extensions.errors.InstallExtensionError – Always raised to indicate support is unavailable.

load(full_reload: bool = False) → None¶

Load information on all extensions on the system.

This will begin looking up all extensions on the system, adding registration entries and enabling any that were previously enabled.

Calling this a second time will refresh the list of extensions, adding any new ones and deleting old ones.

This method is designed to be thread-safe. Only one load across threads can occur at once.

Parameters:

full_reload (bool, optional) – If True, a full reload will be performed, disabling all enabled extensions, clearing all state, and re-loading all extension data.

shutdown() → None¶

Shut down the extension manager and all of its extensions.

This method is designed to be thread-safe. Only one shutdown across threads can occur at once.

install_extension_media(ext_class: Type[Extension], force: bool = False, max_lock_attempts: int = 10) → None¶

Install extension static media.

This will check whether we actually need to install extension media, based on the presence and version of the locally-stored extension media. If media needs to be installed, this will pull it out of the extension package and place it in the appropriate static media location.

This is thread-safe. If multiple threads are attempting to install extension media at the same time, only one will actually perform the install and the rest will make use of that new media.

Parameters:

• ext_class (type) – The extension class owning the static media to install.

• force (bool, optional) – Whether to force installation of static media, regardless of the media version.

• max_lock_attempts (int, optional) – Maximum number of attempts to try to claim a lock in order to install media files.

Raises:

djblets.extensions.errors.InstallExtensionMediaError – There was an error installing extension media. Details are in the error message.

__annotations__ = {'_extension_classes': 'Dict[str, Type[Extension]]', '_extension_instances': 'Dict[str, Extension]', '_extension_list_url': 'Optional[str]', '_load_errors': 'Dict[str, str]', 'middleware_classes': 'List[str]'}¶

get_extension_managers() → List[ExtensionManager]¶

Return all extension manager instances.

This will return all the extension managers that have been constructed. The order is not guaranteed.

Returns:

The list of all extension manager instances currently registered.

Return type:

list of ExtensionManager

shutdown_extension_managers() → None¶

Shut down all extension managers.

This is called automatically when the process exits, but can be run manually.