Merge "Rename notifier 'listeners' to 'topics'"

taskflow/types/notifier.py

@@ -104,7 +104,7 @@ class _Listener(object):
 
 
 class Notifier(object):
-    """A notification helper class.
+    """A notification (`pub/sub`_ *like*) helper class.
 
     It is intended to be used to subscribe to notifications of events
     occurring as well as allow a entity to post said notifications to any
@@ -117,6 +117,8 @@ class Notifier(object):
     potentially end badly. It is thread-safe when
     only :py:meth:`.notify` calls or other read-only actions (like calling
     into :py:meth:`.is_registered`) are occuring at the same time.
+
+    .. _pub/sub: http://en.wikipedia.org/wiki/Publish%E2%80%93subscribe_pattern
     """
 
     #: Keys that can *not* be used in callbacks arguments
@@ -129,7 +131,7 @@ class Notifier(object):
     _DISALLOWED_NOTIFICATION_EVENTS = set([ANY])
 
     def __init__(self):
-        self._listeners = collections.defaultdict(list)
+        self._topics = collections.defaultdict(list)
 
     def __len__(self):
         """Returns how many callbacks are registered.
@@ -138,7 +140,7 @@ class Notifier(object):
         :rtype: number
         """
         count = 0
-        for (_event_type, listeners) in six.iteritems(self._listeners):
+        for (_event_type, listeners) in six.iteritems(self._topics):
             count += len(listeners)
         return count
 
@@ -148,14 +150,14 @@ class Notifier(object):
         :returns: checks if the callback is registered
         :rtype: boolean
         """
-        for listener in self._listeners.get(event_type, []):
+        for listener in self._topics.get(event_type, []):
             if listener.is_equivalent(callback, details_filter=details_filter):
                 return True
         return False
 
     def reset(self):
         """Forget all previously registered callbacks."""
-        self._listeners.clear()
+        self._topics.clear()
 
     def notify(self, event_type, details):
         """Notify about event occurrence.
@@ -176,8 +178,8 @@ class Notifier(object):
             LOG.debug("Event type '%s' is not allowed to trigger"
                       " notifications", event_type)
             return
-        listeners = list(self._listeners.get(self.ANY, []))
-        listeners.extend(self._listeners.get(event_type, []))
+        listeners = list(self._topics.get(self.ANY, []))
+        listeners.extend(self._topics.get(event_type, []))
         if not listeners:
             return
         if not details:
@@ -226,7 +228,7 @@ class Notifier(object):
                 if k in kwargs:
                     raise KeyError("Reserved key '%s' not allowed in "
                                    "kwargs" % k)
-        self._listeners[event_type].append(
+        self._topics[event_type].append(
             _Listener(callback,
                       args=args, kwargs=kwargs,
                       details_filter=details_filter))
@@ -236,11 +238,11 @@ class Notifier(object):
 
         :param event_type: deregister listener bound to event_type
         """
-        if event_type not in self._listeners:
+        if event_type not in self._topics:
             return False
-        for i, listener in enumerate(self._listeners.get(event_type, [])):
+        for i, listener in enumerate(self._topics.get(event_type, [])):
             if listener.is_equivalent(callback, details_filter=details_filter):
-                self._listeners[event_type].pop(i)
+                self._topics[event_type].pop(i)
                 return True
         return False
 
@@ -249,18 +251,18 @@ class Notifier(object):
 
         :param event_type: deregister listeners bound to event_type
         """
-        return len(self._listeners.pop(event_type, []))
+        return len(self._topics.pop(event_type, []))
 
     def copy(self):
         c = copy.copy(self)
-        c._listeners = collections.defaultdict(list)
-        for event_type, listeners in six.iteritems(self._listeners):
-            c._listeners[event_type] = listeners[:]
+        c._topics = collections.defaultdict(list)
+        for (event_type, listeners) in six.iteritems(self._topics):
+            c._topics[event_type] = listeners[:]
         return c
 
     def listeners_iter(self):
         """Return an iterator over the mapping of event => listeners bound."""
-        for event_type, listeners in six.iteritems(self._listeners):
+        for event_type, listeners in six.iteritems(self._topics):
             if listeners:
                 yield (event_type, listeners)