versioned object plugin registry

This patch implements the plumbing to support dynamically loadable
plugins for neutron versioned objects as per the spec [1]. Specifically
a utility class is introduced as a generic plugin manager for stevedore
based plugins in a given namespace. A global singleton instance of this
plugin manager is then wrapped to provide access to neutron versioned
objects.

Using this implementation:
- Neutron version object classes are registered as entry points. For
example [2].
- Consumers can then use the object registry in neutron_lib to access
them, for example [3].

As-is this change doesn't introduce any breakage risk; it's new
functionality that no one is using.

[1] I079d06502e6e7b1e20aea882979b0ecd9106eaeb
[2] https://review.openstack.org/#/c/553836/
[3] https://review.openstack.org/#/c/553835/

Change-Id: I39d9bab1e24fbcbd5f9b3abf80560da920f1cf26

lower-constraints.txt

@@ -51,6 +51,7 @@ oslo.policy==1.30.0
 oslo.serialization==2.18.0
 oslo.service==1.24.0
 oslo.utils==3.33.0
+oslo.versionedobjects===1.31.2
 oslotest==3.2.0
 Paste==2.0.2
 PasteDeploy==1.5.0

neutron_lib/objects/registry.py

@@ -0,0 +1,52 @@
+# Licensed under the Apache License, Version 2.0 (the "License"); you may
+# not use this file except in compliance with the License. You may obtain
+# a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations
+# under the License.
+
+from neutron_lib.utils import runtime
+
+
+NEUTRON_OBJECT_NAMESPACE = 'neutron.objects'
+_REGISTRY = runtime.NamespacedPlugins(NEUTRON_OBJECT_NAMESPACE)
+
+
+def load_class(object_class_name):
+    """Return the versioned object for the given class name.
+
+    :param object_class_name: The class name of the versioned object to
+        get.
+    :returns: A reference to the class for the said object_class_name.
+    """
+    return _REGISTRY.get_plugin_class(object_class_name)
+
+
+def new_instance(object_class_name, *inst_args, **inst_kwargs):
+    """Create a new instance of a versioned object.
+
+    :param object_class_name: The name of the versioned object's class to
+        instantiate.
+    :param inst_args: Any args pass onto the constructor of the versioned
+        object when creating it.
+    :param inst_kwargs: Any kwargs to pass onto the constructor of the object
+        when creating it.
+    :returns: A new instance of the versioned object.
+    """
+    return _REGISTRY.new_plugin_instance(
+        object_class_name, *inst_args, **inst_kwargs)
+
+
+def contains(object_class_name):
+    """Determine if a given versioned object is loaded.
+
+    :param object_class_name: The class name of the versioned object to check
+        for.
+    :returns: True if the versioned object is loaded, and False otherwise.
+    """
+    return object_class_name in _REGISTRY.loaded_plugin_names

neutron_lib/tests/unit/utils/test_runtime.py

@@ -12,6 +12,7 @@
 # limitations under the License.
 
 import mock
+from stevedore import enabled
 
 from neutron_lib.tests import _base as base
 from neutron_lib.utils import runtime
@@ -51,3 +52,61 @@ class TestRunTime(base.BaseTestCase):
         self.assertEqual(
             mock.sentinel.dummy_class,
             runtime.load_class_by_alias_or_classname('ns', 'n'))
+
+
+class TestNamespacedPlugins(base.BaseTestCase):
+
+    @mock.patch.object(enabled, 'EnabledExtensionManager')
+    def test_init_reload(self, mock_mgr):
+        plugins = runtime.NamespacedPlugins('_test_ns_')
+        mock_mgr.assert_called_with(
+            '_test_ns_', mock.ANY, invoke_on_load=False)
+        mock_mgr().map.assert_called_with(plugins._add_extension)
+
+    @mock.patch.object(runtime, 'LOG')
+    @mock.patch.object(enabled, 'EnabledExtensionManager')
+    def test_init_reload_no_plugins(self, mock_mgr, mock_log):
+        mock_mgr().names.return_value = []
+        plugins = runtime.NamespacedPlugins('_test_ns_')
+        mock_log.debug.assert_called_once()
+        mock_mgr().map.assert_not_called()
+        self.assertDictEqual({}, plugins._extensions)
+
+    @mock.patch.object(enabled, 'EnabledExtensionManager')
+    def test_add_duplicate_names(self, mock_mgr):
+        mock_ep = mock.Mock()
+        mock_ep.name = 'a'
+        mock_mgr().names.return_value = ['a', 'a']
+        # return 2 EPs with the same name
+        mock_mgr().map = lambda f: [f(ep) for ep in [mock_ep, mock_ep]]
+        self.assertRaises(KeyError, runtime.NamespacedPlugins, '_test_ns_')
+
+    @mock.patch.object(enabled, 'EnabledExtensionManager')
+    def test_get_plugin_class(self, mock_mgr):
+        mock_epa = mock.Mock()
+        mock_epa.name = 'a'
+        mock_epa.plugin = 'A'
+        mock_epb = mock.Mock()
+        mock_epb.name = 'b'
+        mock_epb.plugin = 'B'
+        mock_mgr().names.return_value = ['a', 'b']
+        mock_mgr().map = lambda f: [f(ep) for ep in [mock_epa, mock_epb]]
+
+        plugins = runtime.NamespacedPlugins('_test_ns_')
+        self.assertEqual('A', plugins.get_plugin_class('a'))
+        self.assertEqual('B', plugins.get_plugin_class('b'))
+
+    @mock.patch.object(enabled, 'EnabledExtensionManager')
+    def test_new_plugin_instance(self, mock_mgr):
+        mock_epa = mock.Mock()
+        mock_epa.name = 'a'
+        mock_epb = mock.Mock()
+        mock_epb.name = 'b'
+        mock_mgr().names.return_value = ['a', 'b']
+        mock_mgr().map = lambda f: [f(ep) for ep in [mock_epa, mock_epb]]
+
+        plugins = runtime.NamespacedPlugins('_test_ns_')
+        plugins.new_plugin_instance('a', 'c', 'd', karg='kval')
+        plugins.new_plugin_instance('b')
+        mock_epa.plugin.assert_called_once_with('c', 'd', karg='kval')
+        mock_epb.plugin.assert_called_once_with()

neutron_lib/utils/runtime.py

@@ -17,17 +17,84 @@ from oslo_concurrency import lockutils
 from oslo_log import log as logging
 from oslo_utils import importutils
 from stevedore import driver
+from stevedore import enabled
 
 from neutron_lib._i18n import _
 
 LOG = logging.getLogger(__name__)
 SYNCHRONIZED_PREFIX = 'neutron-'
 
-
 # common synchronization decorator
 synchronized = lockutils.synchronized_with_prefix(SYNCHRONIZED_PREFIX)
 
 
+class NamespacedPlugins(object):
+    """Wraps a stevedore plugin namespace to load/access its plugins."""
+
+    def __init__(self, namespace):
+        self.namespace = namespace
+        self._extension_manager = None
+        self._extensions = {}
+        self.reload()
+
+    def reload(self):
+        """Force a reload of the plugins for this instances namespace.
+
+        :returns: None.
+        """
+        self._extensions = {}
+        self._extension_manager = enabled.EnabledExtensionManager(
+            self.namespace, lambda x: True,
+            invoke_on_load=False)
+
+        if not self._extension_manager.names():
+            LOG.debug("No plugins found in namespace: ",  self.namespace)
+            return
+        self._extension_manager.map(self._add_extension)
+
+    def _add_extension(self, ext):
+        if ext.name in self._extensions:
+            msg = _("Plugin '%(p)s' already in namespace: %(ns)s") % {
+                'p': ext.name, 'ns': self.namespace}
+            raise KeyError(msg)
+
+        LOG.debug("Loaded plugin '%s' from namespace: %s",
+                  (ext.name, self.namespace))
+        self._extensions[ext.name] = ext
+
+    def _assert_plugin_loaded(self, plugin_name):
+        if plugin_name not in self._extensions:
+            msg = _("Plugin '%(p)s' not in namespace: %(ns)s") % {
+                'p': plugin_name, 'ns': self.namespace}
+            raise KeyError(msg)
+
+    def get_plugin_class(self, plugin_name):
+        """Gets a reference to a loaded plugin's class.
+
+        :param plugin_name: The name of the plugin to get the class for.
+        :returns: A reference to the loaded plugin's class.
+        :raises: KeyError if plugin_name is not loaded.
+        """
+        self._assert_plugin_loaded(plugin_name)
+        return self._extensions[plugin_name].plugin
+
+    def new_plugin_instance(self, plugin_name, *args, **kwargs):
+        """Create a new instance of a plugin.
+
+        :param plugin_name: The name of the plugin to instantiate.
+        :param args: Any args to pass onto the constructor.
+        :param kwargs: Any kwargs to pass onto the constructor.
+        :returns: A new instance of plugin_name.
+        :raises: KeyError if plugin_name is not loaded.
+        """
+        self._assert_plugin_loaded(plugin_name)
+        return self.get_plugin_class(plugin_name)(*args, **kwargs)
+
+    @property
+    def loaded_plugin_names(self):
+        return self._extensions.keys()
+
+
 def load_class_by_alias_or_classname(namespace, name):
     """Load a class using stevedore alias or the class name.
 
@@ -36,7 +103,6 @@ def load_class_by_alias_or_classname(namespace, name):
     :returns: Class if it can be loaded.
     :raises ImportError: if class cannot be loaded.
     """
-
     if not name:
         LOG.error("Alias or class name is not set")
         raise ImportError(_("Class not found."))

releasenotes/notes/add-ovo-registry-27cb7d4ac76d4dc8.yaml

@@ -0,0 +1,9 @@
+---
+features:
+  - The ``neutron_lib.utils.runtime.NamespacedPlugins`` class is now available
+    and wraps a stevedore namespace of plugins.
+  - The ``neutron_lib.objects.registry`` module is now available for loading
+    neutron versioned object classes registered as entry points with the
+    ``NEUTRON_OBJECT_NAMESPACE`` namespace therein. This global registry can
+    be used by consumers to access references to neutron versioned object
+    classes and instances so there's no need to import ``neutron.objects``.

requirements.txt

@@ -19,4 +19,5 @@ oslo.policy>=1.30.0 # Apache-2.0
 oslo.serialization!=2.19.1,>=2.18.0 # Apache-2.0
 oslo.service!=1.28.1,>=1.24.0 # Apache-2.0
 oslo.utils>=3.33.0 # Apache-2.0
+oslo.versionedobjects>=1.31.2 # Apache-2.0
 WebOb>=1.7.1 # MIT