Allow custom notification drivers

Our class hierarchy hides classes and modules that so its hard
for folks to write a custom Notification driver. We should
make these public and document them

Closes-Bug: #1426046
Change-Id: Ifb96c2ae9868426cac2700bf4917c27c02c90b15

doc/source/index.rst

@@ -16,6 +16,7 @@ Contents
    server
    rpcclient
    notifier
+   notification_driver
    notification_listener
    serializer
    exceptions

doc/source/notification_driver.rst

@@ -0,0 +1,15 @@
+-------------------
+Notification Driver
+-------------------
+
+.. automodule:: oslo_messaging.notify.messaging
+
+.. autoclass:: MessagingDriver
+
+.. autoclass:: MessagingV2Driver
+
+.. currentmodule:: oslo_messaging.notify.notifier
+
+.. autoclass:: Driver
+   :members:
+   :noindex:

oslo_messaging/notify/_impl_log.py

@@ -23,7 +23,7 @@ from oslo_utils import strutils
 from oslo_messaging.notify import notifier
 
 
-class LogDriver(notifier._Driver):
+class LogDriver(notifier.Driver):
 
     "Publish notifications via Python logging infrastructure."
 

oslo_messaging/notify/_impl_noop.py

@@ -18,7 +18,7 @@
 from oslo_messaging.notify import notifier
 
 
-class NoOpDriver(notifier._Driver):
+class NoOpDriver(notifier.Driver):
 
     def notify(self, ctxt, message, priority, retry):
         pass

oslo_messaging/notify/_impl_routing.py

@@ -34,7 +34,7 @@ CONF = cfg.CONF
 CONF.register_opt(router_config)
 
 
-class RoutingDriver(notifier._Driver):
+class RoutingDriver(notifier.Driver):
     NOTIFIER_PLUGIN_NAMESPACE = 'oslo.messaging.notify.drivers'
 
     plugin_manager = None

oslo_messaging/notify/_impl_test.py

@@ -26,7 +26,7 @@ def reset():
     NOTIFICATIONS = []
 
 
-class TestDriver(notifier._Driver):
+class TestDriver(notifier.Driver):
 
     "Store notifications in memory for test verification."
 

oslo_messaging/notify/messaging.py

@@ -23,7 +23,7 @@ from oslo_messaging.notify import notifier
 LOG = logging.getLogger(__name__)
 
 
-class MessagingDriver(notifier._Driver):
+class MessagingDriver(notifier.Driver):
 
     """Send notifications using the 1.0 message format.
 

oslo_messaging/notify/notifier.py

@@ -43,15 +43,35 @@ _LOG = logging.getLogger(__name__)
 
 
 @six.add_metaclass(abc.ABCMeta)
-class _Driver(object):
+class Driver(object):
+    """Base driver for Notifications"""
 
     def __init__(self, conf, topics, transport):
+        """base driver initialization
+
+        :param conf: configuration options
+        :param topics: list of topics
+        :param transport: transport driver to use
+        """
         self.conf = conf
         self.topics = topics
         self.transport = transport
 
     @abc.abstractmethod
     def notify(self, ctxt, msg, priority, retry):
+        """send a single notification with a specific priority
+
+        :param ctxt: current request context
+        :param msg: message to be sent
+        :type msg: str
+        :param priority: priority of the message
+        :type priority: str
+        :param retry: an connection retries configuration
+                      None or -1 means to retry forever
+                      0 means no retry
+                      N means N retries
+        :type retry: int
+        """
         pass
 
 

oslo_messaging/tests/notify/test_notifier.py

@@ -29,7 +29,7 @@ import yaml
 
 import oslo_messaging
 from oslo_messaging.notify import _impl_log
-from oslo_messaging.notify import _impl_messaging
+from oslo_messaging.notify import messaging
 from oslo_messaging.notify import _impl_test
 from oslo_messaging.notify import notifier as msg_notifier
 from oslo_messaging import serializer as msg_serializer
@@ -145,7 +145,7 @@ class TestMessagingNotifier(test_utils.BaseTestCase):
         super(TestMessagingNotifier, self).setUp()
 
         self.logger = self.useFixture(_ReRaiseLoggedExceptionsFixture()).logger
-        self.stubs.Set(_impl_messaging, 'LOG', self.logger)
+        self.stubs.Set(messaging, 'LOG', self.logger)
         self.stubs.Set(msg_notifier, '_LOG', self.logger)
 
     @mock.patch('oslo_utils.timeutils.utcnow')

setup.cfg

@@ -43,8 +43,8 @@ oslo.messaging.executors =
     threading = oslo_messaging._executors.impl_thread:ThreadExecutor
 
 oslo.messaging.notify.drivers =
-    messagingv2 = oslo_messaging.notify._impl_messaging:MessagingV2Driver
+    messagingv2 = oslo_messaging.notify.messaging:MessagingV2Driver
-    messaging = oslo_messaging.notify._impl_messaging:MessagingDriver
+    messaging = oslo_messaging.notify.messaging:MessagingDriver
     log = oslo_messaging.notify._impl_log:LogDriver
     test = oslo_messaging.notify._impl_test:TestDriver
     noop = oslo_messaging.notify._impl_noop:NoOpDriver