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.
- 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_DEFAULTto 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
DEBUGisTrue. 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
- 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
- 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
Trueif the extension can be disabled.Falseif it cannot.- Return type
- 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
Trueif the extension can be enabled.Falseif it cannot.- Return type
- 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,
Nonewill be returned.- Return type
- 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
- 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_enabledsignal 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_disabledsignal 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
- Raises
djblets.extensions.errors.InstallExtensionMediaError – There was an error installing extension media. Details are in the error message.