Merge "Deprecate nova.hooks"

doc/source/hooks.rst

@@ -1,57 +0,0 @@
-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://pythonhosted.org/setuptools/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):
-            ....

doc/source/index.rst

@@ -153,7 +153,6 @@ Open Development.
    i18n
    filter_scheduler
    rpc
-   hooks
    block_device_mapping
    addmethod.openstackapi
    conductor

nova/hooks.py

@@ -16,6 +16,9 @@
 """Decorator and config option definitions for adding custom code (hooks)
 around callables.
 
+NOTE: as of Nova 13.0 hooks are DEPRECATED and will be removed in the
+near future. You should not build any new code using this facility.
+
 Any method may have the 'add_hook' decorator applied, which yields the
 ability to invoke Hook objects before or after the method. (i.e. pre and
 post)
@@ -47,7 +50,7 @@ import functools
 from oslo_log import log as logging
 import stevedore
 
-from nova.i18n import _, _LE
+from nova.i18n import _, _LE, _LW
 
 LOG = logging.getLogger(__name__)
 NS = 'nova.hooks'
@@ -82,6 +85,8 @@ class HookManager(stevedore.hook.HookManager):
             obj = e.obj
             hook_method = getattr(obj, method_type, None)
             if hook_method:
+                LOG.warning(_LW("Hooks are deprecated as of Nova 13.0 and "
+                                "will be removed in a future release"))
                 LOG.debug("Running %(name)s %(type)s-hook: %(obj)s",
                           {'name': name, 'type': method_type, 'obj': obj})
                 try:

releasenotes/notes/deprecate_hooks-6f6d60ac206a6da6.yaml

@@ -0,0 +1,7 @@
+---
+deprecations:
+  - Deprecate the use of nova.hooks. This facility used to let
+    arbitrary out of tree code be executed around certain internal
+    actions, but is unsuitable for having a well maintained
+    API. Anyone using this facility should bring forward their use
+    cases in the Newton cycle as nova-specs.