[tor-commits] [stem/master] Adding a add_event_listener() example

[atagar at torproject.org]

commit cc530bb2005f0e156c62fe322d5b43ffe16c3e99
Author: Damian Johnson <atagar at torproject.org>
Date:   Mon Nov 5 07:20:49 2012 -0800

    Adding a add_event_listener() example
    
    On reflection the example that I included on ticket #7328 is pretty good at
    exemplifying the function's usage, so including it in our pydocs.
---
 stem/control.py |   16 +++++++++++++++-
 1 files changed, 15 insertions(+), 1 deletions(-)

diff --git a/stem/control.py b/stem/control.py
index bfb907c..e07658d 100644
--- a/stem/control.py
+++ b/stem/control.py
@@ -563,7 +563,21 @@ class Controller(BaseController):
     """
     Directs further tor controller events to a given function. The function is
     expected to take a single argument, which is a
-    :class:`~stem.response.events.Event` subclass.
+    :class:`~stem.response.events.Event` subclass. For instance the following
+    would would print the bytes sent and received by tor over five seconds...
+    
+    ::
+    
+      import time
+      from stem.control import Controller, EventType
+      
+      def print_bw(event):
+        print "sent: %i, received: %i" % (event.written, event.read)
+      
+      with Controller.from_port(control_port = 9051) as controller:
+        controller.authenticate()
+        controller.add_event_listener(print_bw, EventType.BW)
+        time.sleep(5)
     
     If a new control connection is initialized then this listener will be
     reattached.