[tor-commits] [stem/master] Chaning GuardEvent to match spec revisions

[atagar at torproject.org]

commit 2f90285dd88db3fdac5dc14441b7ffe19ce8da38
Author: Damian Johnson <atagar at torproject.org>
Date:   Sat Mar 16 09:05:22 2013 -0700

    Chaning GuardEvent to match spec revisions
    
    Nick has clarified GUARD events in...
    
    https://trac.torproject.org/7619
    
    Updating our enum docs to reflect the revisions and changing our 'name'
    attribute to reflect that it could contain either a fingerprint or
    fingerprint/nickname pair. This is a similar pattern to what we use for
    ORConnEvent.
---
 stem/__init__.py             |   20 +++++++-------------
 stem/response/events.py      |   29 ++++++++++++++++++++++-------
 test/unit/response/events.py |   14 ++++++++++----
 3 files changed, 39 insertions(+), 24 deletions(-)

diff --git a/stem/__init__.py b/stem/__init__.py
index 3fee276..935ba00 100644
--- a/stem/__init__.py
+++ b/stem/__init__.py
@@ -332,31 +332,25 @@ Library for working with the tor process.
 
   Use a guard relay can be for. Tor may provide types not in this enum.
 
-  Enum descriptions are pending...
-  https://trac.torproject.org/7619
-
   =========== ===========
   GuardType   Description
   =========== ===========
-  **ENTRY**   unknown
+  **ENTRY**   used to connect to the tor network
   =========== ===========
 
 .. data:: GuardStatus (enum)
 
   Status a guard relay can have. Tor may provide types not in this enum.
 
-  Enum descriptions are pending...
-  https://trac.torproject.org/7619
-
   ============= ===========
   GuardStatus   Description
   ============= ===========
-  **NEW**       unknown
-  **UP**        unknown
-  **DOWN**      unknown
-  **BAD**       unknown
-  **GOOD**      unknown
-  **DROPPED**   unknown
+  **NEW**       new guard that we weren't previously using
+  **DROPPED**   removed from use as one of our guards
+  **UP**        guard is now reachable
+  **DOWN**      guard is now unreachable
+  **BAD**       consensus or relay considers this relay to be unusable as a guard
+  **GOOD**      consensus or relay considers this relay to be usable as a guard
   ============= ===========
 
 .. data:: TimeoutSetType (enum)
diff --git a/stem/response/events.py b/stem/response/events.py
index a2c43ff..d99b291 100644
--- a/stem/response/events.py
+++ b/stem/response/events.py
@@ -522,23 +522,38 @@ class DescChangedEvent(Event):
 
 class GuardEvent(Event):
   """
-  Event that indicates that our guard relays have changed.
+  Event that indicates that our guard relays have changed. The 'endpoint' could
+  be either a...
+
+  * fingerprint
+  * 'fingerprint=nickname' pair
+
+  The derived 'endpoint_*' attributes are generally more useful.
 
   The GUARD event was introduced in tor version 0.1.2.5-alpha.
 
   :var stem.GuardType guard_type: purpose the guard relay is for
-  :var str name: nickname or fingerprint of the guard relay
+  :var str endpoint: relay that the event concerns
+  :var str endpoint_fingerprint: endpoint's finterprint
+  :var str endpoint_nickname: endpoint's nickname if it was provided
   :var stem.GuardStatus status: status of the guard relay
   """
 
   _VERSION_ADDED = stem.version.Requirement.EVENT_GUARD
+  _POSITIONAL_ARGS = ("guard_type", "endpoint", "status")
 
-  # TODO: We should replace the 'name' field with a fingerprint or nickname
-  # attribute once we know what it can be...
-  #
-  # https://trac.torproject.org/7619
+  def _parse(self):
+    self.endpoint_fingerprint = None
+    self.endpoint_nickname = None
+
+    try:
+      self.endpoint_fingerprint, self.endpoint_nickname = \
+        stem.control._parse_circ_entry(self.endpoint)
+    except stem.ProtocolError:
+      raise stem.ProtocolError("ORCONN's endpoint doesn't match a ServerSpec: %s" % self)
 
-  _POSITIONAL_ARGS = ("guard_type", "name", "status")
+    self._log_if_unrecognized('guard_type', stem.GuardType)
+    self._log_if_unrecognized('status', stem.GuardStatus)
 
 
 class LogEvent(Event):
diff --git a/test/unit/response/events.py b/test/unit/response/events.py
index 803de0f..98e7f95 100644
--- a/test/unit/response/events.py
+++ b/test/unit/response/events.py
@@ -173,7 +173,7 @@ CONF_CHANGED_EVENT = """650-CONF_CHANGED
 
 GUARD_NEW = "650 GUARD ENTRY $36B5DBA788246E8369DBAF58577C6BC044A9A374 NEW"
 GUARD_GOOD = "650 GUARD ENTRY $5D0034A368E0ABAF663D21847E1C9B6CFA09752A GOOD"
-GUARD_BAD = "650 GUARD ENTRY $5D0034A368E0ABAF663D21847E1C9B6CFA09752A BAD"
+GUARD_BAD = "650 GUARD ENTRY $5D0034A368E0ABAF663D21847E1C9B6CFA09752A=caerSidi BAD"
 
 # NEWCONSENSUS event from v0.2.1.30.
 
@@ -636,17 +636,23 @@ class TestEvents(unittest.TestCase):
     self.assertTrue(isinstance(event, stem.response.events.GuardEvent))
     self.assertEqual(GUARD_NEW.lstrip("650 "), str(event))
     self.assertEqual(GuardType.ENTRY, event.guard_type)
-    self.assertEqual("$36B5DBA788246E8369DBAF58577C6BC044A9A374", event.name)
+    self.assertEqual("$36B5DBA788246E8369DBAF58577C6BC044A9A374", event.endpoint)
+    self.assertEqual("36B5DBA788246E8369DBAF58577C6BC044A9A374", event.endpoint_fingerprint)
+    self.assertEqual(None, event.endpoint_nickname)
     self.assertEqual(GuardStatus.NEW, event.status)
 
     event = _get_event(GUARD_GOOD)
     self.assertEqual(GuardType.ENTRY, event.guard_type)
-    self.assertEqual("$5D0034A368E0ABAF663D21847E1C9B6CFA09752A", event.name)
+    self.assertEqual("$5D0034A368E0ABAF663D21847E1C9B6CFA09752A", event.endpoint)
+    self.assertEqual("5D0034A368E0ABAF663D21847E1C9B6CFA09752A", event.endpoint_fingerprint)
+    self.assertEqual(None, event.endpoint_nickname)
     self.assertEqual(GuardStatus.GOOD, event.status)
 
     event = _get_event(GUARD_BAD)
     self.assertEqual(GuardType.ENTRY, event.guard_type)
-    self.assertEqual("$5D0034A368E0ABAF663D21847E1C9B6CFA09752A", event.name)
+    self.assertEqual("$5D0034A368E0ABAF663D21847E1C9B6CFA09752A=caerSidi", event.endpoint)
+    self.assertEqual("5D0034A368E0ABAF663D21847E1C9B6CFA09752A", event.endpoint_fingerprint)
+    self.assertEqual("caerSidi", event.endpoint_nickname)
     self.assertEqual(GuardStatus.BAD, event.status)
 
   def test_newdesc_event(self):