[tor-commits] [stem/master] Changing prompt's events builtin to be a function

[atagar at torproject.org]

commit 00903e75ff4f3e16ae81240506237ef9e50da113
Author: Damian Johnson <atagar at torproject.org>
Date:   Sun May 25 12:10:51 2014 -0700

    Changing prompt's events builtin to be a function
    
    Changing 'events' from being a variable to a function. Presently this provides
    a single optional argument to filter the event types it returns (a very, very
    common thing to want). This also makes it easier for us to expand in the future
    as more use cases crop up.
---
 docs/_static/prompt/events_variable.png |  Bin 17084 -> 17511 bytes
 docs/tutorials/down_the_rabbit_hole.rst |    8 ++++++--
 stem/interpreter/commands.py            |   17 +++++++++++------
 3 files changed, 17 insertions(+), 8 deletions(-)

diff --git a/docs/_static/prompt/events_variable.png b/docs/_static/prompt/events_variable.png
index f104767..d5188fc 100644
Binary files a/docs/_static/prompt/events_variable.png and b/docs/_static/prompt/events_variable.png differ
diff --git a/docs/tutorials/down_the_rabbit_hole.rst b/docs/tutorials/down_the_rabbit_hole.rst
index 2cfbabb..a2193e3 100644
--- a/docs/tutorials/down_the_rabbit_hole.rst
+++ b/docs/tutorials/down_the_rabbit_hole.rst
@@ -101,11 +101,15 @@ provides a quick dump of the events we've received thus far...
 .. image:: /_static/prompt/events_command.png
 
 You can list events of just a certain type by saying which (for instance
-**/events BW**). More useful though is your **events** variable, which is a
-list of :class:`~stem.response.events.Event` instances we've received...
+**/events BW**). More useful though is your **events()** function, which
+provides a list of :class:`~stem.response.events.Event` instances we've
+received...
 
 .. image:: /_static/prompt/events_variable.png
 
+You can specify event types to either **/events** or **events()** to just
+receive events of those types (for instance, **events('BW', 'DEBUG')**).
+
 To stop receiving events run **SETEVENTS** without any event types, and to
 clear the backlog of events we've received run **/events clear**.
 
diff --git a/stem/interpreter/commands.py b/stem/interpreter/commands.py
index 0342ba9..6731949 100644
--- a/stem/interpreter/commands.py
+++ b/stem/interpreter/commands.py
@@ -91,7 +91,7 @@ class ControlInterpretor(code.InteractiveConsole):
       'stem': stem,
       'stem.control': stem.control,
       'controller': controller,
-      'events': self._received_events
+      'events': self.get_events,
     })
 
     self._controller = controller
@@ -113,6 +113,15 @@ class ControlInterpretor(code.InteractiveConsole):
 
     self._controller._handle_event = handle_event_wrapper
 
+  def get_events(self, *event_types):
+    events = list(self._received_events)
+    event_types = map(str.upper, event_types)  # make filtering case insensitive
+
+    if event_types:
+      events = filter(lambda e: e.type in event_types, events)
+
+    return events
+
   def do_help(self, arg):
     """
     Performs the '/help' operation, giving usage information for the given
@@ -131,17 +140,13 @@ class ControlInterpretor(code.InteractiveConsole):
     received.
     """
 
-    events = self._received_events
     event_types = arg.upper().split()
 
     if 'CLEAR' in event_types:
       del self._received_events[:]
       return format('cleared event backlog', *STANDARD_OUTPUT)
 
-    if event_types:
-      events = filter(lambda event: event.type in event_types, events)
-
-    return '\n'.join([format(str(event), *STANDARD_OUTPUT) for event in events])
+    return '\n'.join([format(str(e), *STANDARD_OUTPUT) for e in self.get_events(*event_types)])
 
   def do_info(self, arg):
     """