[tor-commits] [stem/master] EventType to Event subclass table

[atagar at torproject.org]

commit 1d56eb59e256977d34f9d3d77e4e0b8c2df49f86
Author: Damian Johnson <atagar at torproject.org>
Date:   Mon Nov 5 08:21:30 2012 -0800

    EventType to Event subclass table
    
    Adding a table that'll list the EventType enumerations and map them to Event
    subclasses.
---
 docs/api/response.rst |    6 ++++++
 stem/control.py       |   18 ++++++++++++++++--
 2 files changed, 22 insertions(+), 2 deletions(-)

diff --git a/docs/api/response.rst b/docs/api/response.rst
index bf3b722..6e23c91 100644
--- a/docs/api/response.rst
+++ b/docs/api/response.rst
@@ -12,3 +12,9 @@ Responses
 .. autoclass:: stem.response.mapaddress.MapAddressResponse
 .. autoclass:: stem.response.protocolinfo.ProtocolInfoResponse
 
+Events
+------
+
+.. autoclass:: stem.response.events.Event
+.. autoclass:: stem.response.events.BandwidthEvent
+
diff --git a/stem/control.py b/stem/control.py
index c2a94aa..f9f7def 100644
--- a/stem/control.py
+++ b/stem/control.py
@@ -543,6 +543,15 @@ class Controller(BaseController):
     self._event_listeners = {}
     self._event_listeners_lock = threading.RLock()
     
+    # TODO: We want the capability of taking post-authentication actions, for
+    # instance to call SETEVENTS so our event listeners will work on new
+    # connections. The trouble is that the user could do this by a variety of
+    # methods (authenticate(), msg(), stem.connection.authenticete(), etc)...
+    #
+    # When we get it figured out we should add the pydoc comment:
+    # If a new control connection is initialized then this listener will be
+    # reattached.
+    
     # number of sequential 'GETINFO ip-to-country/*' lookups that have failed
     self._geoip_failure_count = 0
     self.enabled_features = []
@@ -579,8 +588,13 @@ class Controller(BaseController):
         controller.add_event_listener(print_bw, EventType.BW)
         time.sleep(5)
     
-    If a new control connection is initialized then this listener will be
-    reattached.
+    The EventType enumeration is mapped to event classes as follows...
+    
+    ========= ===========
+    EventType Event Class
+    ========= ===========
+    **BW**    :class:`stem.response.events.BandwidthEvent`
+    ========= ===========
     
     :param functor listener: function to be called when an event is received
     :param stem.control.EventType events: event types to be listened for