djblets.extensions.hooks¶
Base support and implementations for extension hooks.
Extension hooks allow applications to define formal ways to inject logic, behavior, or more into part of the application.
This module provides the base support for defining an extension hook, through
ExtensionHook
and ExtensionHookPoint
, along with
a utility mixin, AppliesToURLMixin
.
It also provides some built-in hooks for applications and extensions to use:
- class ExtensionHook(extension, *args, **kwargs)[source]¶
The base class for a hook into some part of an application.
ExtensionHooks are classes that can hook into an
ExtensionHookPoint
to provide some level of functionality in an application. A consuming application should provide a subclass of ExtensionHook that will provide functions for getting data or anything else that’s needed. Extensions may then subclass or initialize that specific ExtensionHook.A base ExtensionHook subclass must use
ExtensionHookPoint
as a metaclass. All hooks deriving from that subclass will be registered along with that hook point.Example
from django.utils import six from myproject.nav import register_thing, unregister_thing_id @six.add_metaclass(ExtensionHookPoint) class ThingHook(ExtensionHook): def initialize(self, thing_id): self.thing_id = thing_id register_thing(self.thing_id) def shutdown(self): unregister_thing(self.thing_id)
Changed in version 1.0: Starting with Djblets 1.0, extension hooks should implement the
initialize()
method to handle any initialization. It no longer needs to call the parentshutdown()
method, either. However, to retain compatibility with older versions, they may still override__init__()
and may call the parentshutdown()
. See those methods for more details.- extension¶
The parent extension, or another object that can act as a hook owner.
- hook_state¶
The state of the hook. This will be one of
HOOK_STATE_DISABLED
,HOOK_STATE_ENABLED
,HOOK_STATE_DISABLING
, orHOOK_STATE_ENABLING
.- Type
- initialize(*args, **kwargs)[source]¶
Initialize the extension hook’s state.
Extension subclasses can perform any custom initialization they need here.
Any additional arguments passed to the hook during construction will be passed to this as well.
While in this function,
hook_state
will be set toHOOK_STATE_ENABLING
.By default, this does nothing.
New in version 1.0.
- Parameters
Example
@six.add_metaclass(ExtensionHookPoint) class ThingHook(ExtensionHook): def initialize(self, thing_id): self.thing_id = thing_id register_thing(self.thing_id)
- shutdown()[source]¶
Shut down the extension.
Extension subclasses can perform any custom cleanup they need here.
While in this function,
hook_state
will be set toHOOK_STATE_DISABLING
.Changed in version 1.0: This method used to be responsible both for internal cleanup and the cleanup of the subclass. Starting in Djblets 1.0, internal cleanup has moved to
disable_hook()
. Subclasses no longer need to call the parent method unless inheriting from a mixin or anotherExtensionHook
subclass, but should continue to do so if they need to retain compatibility with older versions.Example
@six.add_metaclass(ExtensionHookPoint) class ThingHook(ExtensionHook): def shutdown(self): unregister_thing(self.thing_id)
- enable_hook(*args, **kwargs)[source]¶
Enable the ExtensionHook, beginning the initialization process.
This will register the instance of the hook and begin its initialization. It takes the same parameters that would be given during construction of the hook, allowing disabled hooks to be created again with fresh state.
Subclasses should not override this process. They should instead implement
initialize()
to handle initialization of the state of the hook.New in version 1.0.
- disable_hook(call_shutdown=True)[source]¶
Disable the hook, unregistering it from the extension.
This will unregister the hook and uninitialize it, putting it into a disabled state.
Consumers can call this if they want to turn off hooks temporarily without reconstructing the instances later. It’s also called internally when shutting down an extension.
New in version 1.0.
- Parameters
call_shutdown (bool, optional) – Whether to call
shutdown()
. This should always beTrue
unless called internally.
- class ExtensionHookPoint(name, bases, attrs)[source]¶
A metaclass used for base Extension Hooks.
Base
ExtensionHook
classes useExtensionHookPoint
as a metaclass. This metaclass stores the list of registered hooks that anExtensionHook
will automatically register with.- add_hook(hook)[source]¶
Adds an ExtensionHook to the list of active hooks.
This is called automatically by
ExtensionHook
.
- remove_hook(hook)[source]¶
Removes an ExtensionHook from the list of active hooks.
This is called automatically by
ExtensionHook
.
- class AppliesToURLMixin[source]¶
A mixin for hooks to allow restricting to certain URLs.
This provides an
applies_to()
function for the hook that can be used by consumers to determine if the hook should apply to the current page.
- class DataGridColumnsHook(extension, *args, **kwargs)[source]¶
Adds columns to a datagrid.
This hook allows an extension to register new columns to any datagrid. These columns can be added by the user, rearranged, and sorted, like any other column.
Each column must have an id already set, and it must be unique.
- shutdown()[source]¶
Shut down the extension.
Extension subclasses can perform any custom cleanup they need here.
While in this function,
hook_state
will be set toHOOK_STATE_DISABLING
.Changed in version 1.0: This method used to be responsible both for internal cleanup and the cleanup of the subclass. Starting in Djblets 1.0, internal cleanup has moved to
disable_hook()
. Subclasses no longer need to call the parent method unless inheriting from a mixin or anotherExtensionHook
subclass, but should continue to do so if they need to retain compatibility with older versions.Example
@six.add_metaclass(ExtensionHookPoint) class ThingHook(ExtensionHook): def shutdown(self): unregister_thing(self.thing_id)
- class URLHook(extension, *args, **kwargs)[source]¶
Custom URL hook.
A hook that installs custom URLs. These URLs reside in a project-specified parent URL.
- shutdown()[source]¶
Shut down the extension.
Extension subclasses can perform any custom cleanup they need here.
While in this function,
hook_state
will be set toHOOK_STATE_DISABLING
.Changed in version 1.0: This method used to be responsible both for internal cleanup and the cleanup of the subclass. Starting in Djblets 1.0, internal cleanup has moved to
disable_hook()
. Subclasses no longer need to call the parent method unless inheriting from a mixin or anotherExtensionHook
subclass, but should continue to do so if they need to retain compatibility with older versions.Example
@six.add_metaclass(ExtensionHookPoint) class ThingHook(ExtensionHook): def shutdown(self): unregister_thing(self.thing_id)
- class SignalHook(extension, *args, **kwargs)[source]¶
Connects to a Django signal.
This will handle connecting to a signal, calling the specified callback when fired. It will disconnect from the signal when the extension is disabled.
The callback will also be passed an extension= keyword argument pointing to the extension instance.
- initialize(signal, callback, sender=None, sandbox_errors=True)[source]¶
Initialize the hook.
- Parameters
signal (django.dispatch.Signal) – The signal to connect to.
callback (callable) – The function to call when the signal is fired.
sender (object or class, optional) – The sender argument to pass to the signal connection. See
send()
for more information.sandbox_errors (bool, optional) – If
True
, errors coming fromcallback
will be sandboxed, preventing them from reaching the code that fired the signal. The error will instead be logged and then ignored.
- shutdown()[source]¶
Shut down the extension.
Extension subclasses can perform any custom cleanup they need here.
While in this function,
hook_state
will be set toHOOK_STATE_DISABLING
.Changed in version 1.0: This method used to be responsible both for internal cleanup and the cleanup of the subclass. Starting in Djblets 1.0, internal cleanup has moved to
disable_hook()
. Subclasses no longer need to call the parent method unless inheriting from a mixin or anotherExtensionHook
subclass, but should continue to do so if they need to retain compatibility with older versions.Example
@six.add_metaclass(ExtensionHookPoint) class ThingHook(ExtensionHook): def shutdown(self): unregister_thing(self.thing_id)
- class TemplateHook(extension, *args, **kwargs)[source]¶
Custom templates hook.
A hook that renders a template at hook points defined in another template.
- initialize(name, template_name=None, apply_to=[], extra_context={})[source]¶
Initialize the hook.
- Parameters
name (unicode) – The name of the template hook point that should render this template. This is application-specific.
template_name (unicode, optional) – The name of the template to render.
apply_to (list, optional) – The list of URL names where this template should render. By default, all templates containing the template hook point will render this template.
extra_context (dict) – Extra context to include when rendering the template.
- shutdown()[source]¶
Shut down the extension.
Extension subclasses can perform any custom cleanup they need here.
While in this function,
hook_state
will be set toHOOK_STATE_DISABLING
.Changed in version 1.0: This method used to be responsible both for internal cleanup and the cleanup of the subclass. Starting in Djblets 1.0, internal cleanup has moved to
disable_hook()
. Subclasses no longer need to call the parent method unless inheriting from a mixin or anotherExtensionHook
subclass, but should continue to do so if they need to retain compatibility with older versions.Example
@six.add_metaclass(ExtensionHookPoint) class ThingHook(ExtensionHook): def shutdown(self): unregister_thing(self.thing_id)
- class BaseRegistryHook(extension, *args, **kwargs)[source]¶
A hook for registering an item with a registry.
This hook should not be used directly. Instead, it should be subclassed with the
registry
attribute set.Subclasses must use the
ExtensionHookPoint
metaclass.
- class BaseRegistryMultiItemHook(extension, *args, **kwargs)[source]¶
A hook for registering multiple items with a registry.
This hook should not be used directly. Instead, it should be subclassed with the
registry
attribute set.Subclasses must use the
ExtensionHookPoint
metaclass.