From b5e43afc37e1683e222a48bd8c5c1700c417c336 Mon Sep 17 00:00:00 2001 From: Mark McLoughlin Date: Sun, 23 Jun 2013 13:21:42 +0100 Subject: [PATCH] Docstrings for notifier API --- oslo/messaging/notify/_impl_log.py | 2 + oslo/messaging/notify/_impl_messaging.py | 11 +++ oslo/messaging/notify/_impl_test.py | 2 + oslo/messaging/notify/notifier.py | 91 ++++++++++++++++++++++++ 4 files changed, 106 insertions(+) diff --git a/oslo/messaging/notify/_impl_log.py b/oslo/messaging/notify/_impl_log.py index d5673e699..480c60339 100644 --- a/oslo/messaging/notify/_impl_log.py +++ b/oslo/messaging/notify/_impl_log.py @@ -23,6 +23,8 @@ from oslo.messaging.openstack.common import jsonutils class LogDriver(notifier._Driver): + "Publish notifications via Python logging infrastructure." + LOGGER_BASE = 'oslo.messaging.notification' def notify(self, context, message, priority): diff --git a/oslo/messaging/notify/_impl_messaging.py b/oslo/messaging/notify/_impl_messaging.py index 7754e3121..349dcf5de 100644 --- a/oslo/messaging/notify/_impl_messaging.py +++ b/oslo/messaging/notify/_impl_messaging.py @@ -25,6 +25,15 @@ LOG = logging.getLogger(__name__) class MessagingDriver(notifier._Driver): + """Send notifications using the 1.0 message format. + + This driver sends notifications over the configured messaging transport, + but without any message envelope (also known as message format 1.0). + + This driver should only be used in cases where there are existing consumers + deployed which do not support the 2.0 message format. + """ + def __init__(self, conf, topics, transport, envelope=False): super(MessagingDriver, self).__init__(conf, topics, transport) self.envelope = envelope @@ -43,5 +52,7 @@ class MessagingDriver(notifier._Driver): class MessagingV2Driver(MessagingDriver): + "Send notifications using the 2.0 message format." + def __init__(self, conf, **kwargs): super(MessagingDriver, self).__init__(conf, envelope=True, **kwargs) diff --git a/oslo/messaging/notify/_impl_test.py b/oslo/messaging/notify/_impl_test.py index a3dda6498..67bde6833 100644 --- a/oslo/messaging/notify/_impl_test.py +++ b/oslo/messaging/notify/_impl_test.py @@ -20,6 +20,8 @@ from oslo.messaging.notify import notifier class TestDriver(notifier._Driver): + "Store notifications in memory for test verification." + def __init__(self, conf, **kwargs): super(TestDriver, self).__init__(conf, **kwargs) self.notifications = [] diff --git a/oslo/messaging/notify/notifier.py b/oslo/messaging/notify/notifier.py index b1ff6c81c..6949c2a74 100644 --- a/oslo/messaging/notify/notifier.py +++ b/oslo/messaging/notify/notifier.py @@ -55,8 +55,54 @@ class _Driver(object): class Notifier(object): + """Send notification messages. + + The Notifier class is used for sending notification messages over a + messaging transport or other means. + + Notification messages follow the following format: + + {'message_id': str(uuid.uuid4()), + 'publisher_id': 'compute.host1', + 'timestamp': timeutils.utcnow(), + 'priority': 'WARN', + 'event_type': 'compute.create_instance', + 'payload': {'instance_id': 12, ... }} + + A Notifier object can be instantiated with a configuration object and a + publisher ID: + + notifier = notifier.Notifier(cfg.CONF, 'compute.host1') + + and notifications are sent via drivers chosen with the notification_driver + config option, on the topics consen with the notification_topics config + option, on a transport contstructed using the supplied configuration. + + Alternatively, a Notifier object can be instantiated with a specific + driver, topic or transport: + + notifier = notifier.Notifier(cfg.CONF, + 'compute.host', + driver='messaging', + topic='notifications', + transport=RPC_TRANSPORT) + """ + def __init__(self, conf, publisher_id, driver=None, topic=None, transport=None): + """Construct a Notifier object. + + :param conf: user configuration, used for e.g. notification_driver + :type conf: a cfg.ConfigOpts instance + :param publisher_id: field in notifications sent, e.g. 'compute.host1' + :type publisher_id: str + :param driver: a driver to lookup from oslo.messaging.notify.drivers + :type driver: str + :param topic: the topic which to send messages on + :type topic: str + :param transport: the transport to use for sending messages + :type transport: oslo.messaging.Transport + """ self.conf = conf self.conf.register_opts(_notifier_opts) @@ -98,16 +144,61 @@ class Notifier(object): self._driver_mgr.map(do_notify) def debug(self, context, event_type, payload): + """Send a notification at debug level. + + :param context: a request context dict + :type context: dict + :param event_type: describes the event, e.g. 'compute.create_instance' + :type event_type: str + :param payload: the notification payload + :type payload: dict + """ self._notify(context, event_type, payload, 'DEBUG') def info(self, context, event_type, payload): + """Send a notification at info level. + + :param context: a request context dict + :type context: dict + :param event_type: describes the event, e.g. 'compute.create_instance' + :type event_type: str + :param payload: the notification payload + :type payload: dict + """ self._notify(context, event_type, payload, 'INFO') def warn(self, context, event_type, payload): + """Send a notification at warning level. + + :param context: a request context dict + :type context: dict + :param event_type: describes the event, e.g. 'compute.create_instance' + :type event_type: str + :param payload: the notification payload + :type payload: dict + """ self._notify(context, event_type, payload, 'WARN') def error(self, context, event_type, payload): + """Send a notification at error level. + + :param context: a request context dict + :type context: dict + :param event_type: describes the event, e.g. 'compute.create_instance' + :type event_type: str + :param payload: the notification payload + :type payload: dict + """ self._notify(context, event_type, payload, 'ERROR') def critical(self, context, event_type, payload): + """Send a notification at critical level. + + :param context: a request context dict + :type context: dict + :param event_type: describes the event, e.g. 'compute.create_instance' + :type event_type: str + :param payload: the notification payload + :type payload: dict + """ self._notify(context, event_type, payload, 'CRITICAL')