diff options
| author | Jenkins <jenkins@review.openstack.org> | 2012-12-10 18:42:15 +0000 |
|---|---|---|
| committer | Gerrit Code Review <review@openstack.org> | 2012-12-10 18:42:15 +0000 |
| commit | 734d9fb22b56c2fea9831c6ceba37a671d76b707 (patch) | |
| tree | a5f25dbde8b81d110557b209b4157dfa82489597 /doc | |
| parent | 5bfe4a7438a0bd500f109d1efd4dbf9ec63f3883 (diff) | |
| parent | e937a53065377ecb7c30372ce880bd3d358f4572 (diff) | |
Merge "Add generic customization hooks via decorator."
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/source/devref/hooks.rst | 57 | ||||
| -rw-r--r-- | doc/source/devref/index.rst | 1 |
2 files changed, 58 insertions, 0 deletions
diff --git a/doc/source/devref/hooks.rst b/doc/source/devref/hooks.rst new file mode 100644 index 000000000..a53e37352 --- /dev/null +++ b/doc/source/devref/hooks.rst @@ -0,0 +1,57 @@ +Hooks +===== + +Hooks provide a mechanism to extend Nova with custom code through a plugin +mechanism. + +Named hooks are added to nova code via a decorator that will lazily load +plugin code matching the name. The loading works via setuptools +`entry points`_. + +.. _`entry points`: http://packages.python.org/distribute/pkg_resources.html#entry-points + +What are hooks good for? +------------------------ + +Hooks are good for anchoring your custom code to Nova internal APIs. + +What are hooks NOT good for? +---------------------------- + +Hooks should not be used when API stability is a key factor. Internal APIs may +change. Consider using a notification driver if this is important to you. + +Declaring hooks in the Nova codebase +------------------------------------ + +The following example declares a *resize_hook* around the *resize_instance* method:: + + from nova import hooks + + @hooks.add_hook("resize_hook") + def resize_instance(self, context, instance, a=1, b=2): + ... + +Hook objects can now be attached via entry points to the *resize_hook*. + +Adding hook object code +----------------------- + +1. Setup a Python package with a setup.py file. +2. Add the following to the setup.py setup call:: + + entry_points = [ + 'nova.hooks': [ + 'resize_hook': your_package.hooks.YourHookClass, + ] + ] + +3. *YourHookClass* should be an object with *pre* and/or *post* methods:: + + class YourHookClass(object): + + def pre(self, *args, **kwargs): + .... + + def post(self, rv, *args, **kwargs): + .... diff --git a/doc/source/devref/index.rst b/doc/source/devref/index.rst index 239848c62..0b7883f7b 100644 --- a/doc/source/devref/index.rst +++ b/doc/source/devref/index.rst @@ -43,6 +43,7 @@ Background Concepts for Nova filter_scheduler multinic rpc + hooks Other Resources --------------- |