djblets.extensions.manager¶
Extension manager class for supporting extensions to an application.
- class SettingListWrapper(setting_name, display_name, parent_dict=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, display_name, parent_dict=None)¶
Initialize the settings wrapper.
- Parameters:
- add(item)¶
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)¶
Add a list of items to the setting.
- remove(item)¶
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.
- class ExtensionManager(key)¶
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
DEBUG
isTrue
. 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)¶
Initialize the extension manager.
- Parameters:
key (
unicode
) – A key that’s unique to this extension manager instance. It must also be the same key used to look up Python entry points.
- get_url_patterns()¶
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()¶
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()¶
Clear the extension synchronization state.
This will force every process to reload the extension list and settings.
- get_absolute_url()¶
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:
- get_can_disable_extension(registered_extension)¶
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:
- get_can_enable_extension(registered_extension)¶
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:
- get_enabled_extension(extension_id)¶
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:
- get_enabled_extensions()¶
Return a list of all enabled extensions.
- Returns:
All extension instances currently enabled.
- Return type:
- get_installed_extensions()¶
Return a list of all installed extension classes.
- get_installed_extension(extension_id)¶
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)¶
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:
- Raises:
djblets.extensions.errors.InvalidExtensionError – The extension could not be found.
- enable_extension(extension_id)¶
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)¶
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)¶
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:
- Raises:
djblets.extensions.errors.InstallExtensionError – There was an error installing the extension.
- load(full_reload=False)¶
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) – IfTrue
, a full reload will be performed, disabling all enabled extensions, clearing all state, and re-loading all extension data.
- shutdown()¶
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)¶
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.
- get_extension_managers()¶
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:
- shutdown_extension_managers()¶
Shut down all extension managers.
This is called automatically when the process exits, but can be run manually.