djblets.extensions.manager¶

Extension manager class for supporting extensions to an application.

class SettingListWrapper(setting_name, display_name, parent_dict=None)[source]¶

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.

add(item)[source]¶

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

Add a list of items to the setting.

Parameters

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

remove(item)[source]¶

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

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

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

Whether to explicitly install static media files from packages.

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

VERSION_SETTINGS_KEY = '_extension_installed_version'[source]¶

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.

get_url_patterns()[source]¶

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

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

Clear the extension synchronization state.

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

get_absolute_url()[source]¶

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

unicode

get_can_disable_extension(registered_extension)[source]¶

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

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

Return an enabled extension for the given exetnsion ID.

Parameters

extension_id (unicode) – 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()[source]¶

Return a list of all enabled extensions.

Returns

All extension instances currently enabled.

Return type

list of djblets.extensions.extension.Extension

get_installed_extensions()[source]¶

Return a list of all installed extension classes.

Returns

All extension classes currently registered.

Return type

list of type

get_installed_extension(extension_id)[source]¶

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

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

Parameters

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

Returns

The list of extension IDs required by this extension.

Return type

list of unicode

Raises

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

enable_extension(extension_id)[source]¶

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 (unicode) – The ID of the extension to enable.

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

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 (unicode) – The ID of the extension to disable.

Raises

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

install_extension(install_url, package_name)[source]¶

Install an extension from a remote source.

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

Notes

This currently does not support Wheel packages, and is considered a highly-experimental and unsupported feature. The functionality and function signature of this package is expected to change. Basically, expect breakages.

Parameters

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

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

Raises

djblets.extensions.errors.InstallExtensionError – There was an error installing the extension.

load(full_reload=False)[source]¶

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

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, force=False, max_lock_attempts=10)[source]¶

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.

get_extension_managers()[source]¶

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

Shut down all extension managers.

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