[tor-commits] [stem/master] Support for NETWORK_LIVENESS events

[atagar at torproject.org]

commit a990a42a01a2e66739066138f029df0314ad8a8b
Author: Damian Johnson <atagar at torproject.org>
Date:   Tue May 19 08:41:42 2015 -0700

    Support for NETWORK_LIVENESS events
    
    Adding support for tor's new event type...
    
      https://gitweb.torproject.org/torspec.git/commit/?id=44aac630f69fc1bc1ab8cd33645f9f461de116a4
      https://trac.torproject.org/projects/tor/ticket/15358
---
 docs/change_log.rst          |    4 ++++
 stem/control.py              |    2 ++
 stem/response/events.py      |   17 +++++++++++++++++
 stem/version.py              |    2 ++
 test/unit/response/events.py |   12 ++++++++++++
 5 files changed, 37 insertions(+)

diff --git a/docs/change_log.rst b/docs/change_log.rst
index bbde6f5..1486391 100644
--- a/docs/change_log.rst
+++ b/docs/change_log.rst
@@ -42,6 +42,10 @@ Unreleased
 The following are only available within Stem's `git repository
 <download.html>`_.
 
+ * **Controller**
+
+  * Added `support for NETWORK_LIVENESS events <api/response.html#stem.response.events.NetworkLivenessEvent>`_ (:spec:`44aac63`)
+
 .. _version_1.4:
 
 Version 1.4 (May 13th, 2015)
diff --git a/stem/control.py b/stem/control.py
index 657f559..a903e4d 100644
--- a/stem/control.py
+++ b/stem/control.py
@@ -197,6 +197,7 @@ If you're fine with allowing your script to raise exceptions then this can be mo
   **HS_DESC**             :class:`stem.response.events.HSDescEvent`
   **HS_DESC_CONTENT**     :class:`stem.response.events.HSDescContentEvent`
   **INFO**                :class:`stem.response.events.LogEvent`
+  **NETWORK_LIVENESS**    :class:`stem.response.events.NetworkLivenessEvent`
   **NEWCONSENSUS**        :class:`stem.response.events.NewConsensusEvent`
   **NEWDESC**             :class:`stem.response.events.NewDescEvent`
   **NOTICE**              :class:`stem.response.events.LogEvent`
@@ -293,6 +294,7 @@ EventType = stem.util.enum.UppercaseEnum(
   'HS_DESC',
   'HS_DESC_CONTENT',
   'INFO',
+  'NETWORK_LIVENESS',
   'NEWCONSENSUS',
   'NEWDESC',
   'NOTICE',
diff --git a/stem/response/events.py b/stem/response/events.py
index 9c38649..2ae01be 100644
--- a/stem/response/events.py
+++ b/stem/response/events.py
@@ -749,6 +749,22 @@ class NetworkStatusEvent(Event):
     ))
 
 
+class NetworkLivenessEvent(Event):
+  """
+  Event for when the network becomes reachable or unreachable.
+
+  The NETWORK_LIVENESS event was introduced in tor version 0.2.7.2-alpha.
+
+  .. versionadded:: 1.5.0
+
+  :var str status: status of the network ('UP', 'DOWN', or possibly other
+    statuses in the future)
+  """
+
+  _VERSION_ADDED = stem.version.Requirement.EVENT_NETWORK_LIVENESS
+  _POSITIONAL_ARGS = ('status',)
+
+
 class NewConsensusEvent(Event):
   """
   Event for when we have a new consensus. This is similar to
@@ -1311,6 +1327,7 @@ EVENT_TYPE_TO_CLASS = {
   'HS_DESC': HSDescEvent,
   'HS_DESC_CONTENT': HSDescContentEvent,
   'INFO': LogEvent,
+  'NETWORK_LIVENESS': NetworkLivenessEvent,
   'NEWCONSENSUS': NewConsensusEvent,
   'NEWDESC': NewDescEvent,
   'NOTICE': LogEvent,
diff --git a/stem/version.py b/stem/version.py
index 1182bfc..a4e184a 100644
--- a/stem/version.py
+++ b/stem/version.py
@@ -39,6 +39,7 @@ easily parsed and compared, for instance...
   **EVENT_DESCCHANGED**                 DESCCHANGED events
   **EVENT_GUARD**                       GUARD events
   **EVENT_HS_DESC_CONTENT**             HS_DESC_CONTENT events
+  **EVENT_NETWORK_LIVENESS**            NETWORK_LIVENESS events
   **EVENT_NEWCONSENSUS**                NEWCONSENSUS events
   **EVENT_NS**                          NS events
   **EVENT_SIGNAL**                      SIGNAL events
@@ -349,6 +350,7 @@ Requirement = stem.util.enum.Enum(
   ('EVENT_GUARD', Version('0.1.2.5-alpha')),
   ('EVENT_HS_DESC_CONTENT', Version('0.2.7.1-alpha')),
   ('EVENT_NS', Version('0.1.2.3-alpha')),
+  ('EVENT_NETWORK_LIVENESS', Version('0.2.7.2-alpha')),
   ('EVENT_NEWCONSENSUS', Version('0.2.1.13-alpha')),
   ('EVENT_SIGNAL', Version('0.2.3.1-alpha')),
   ('EVENT_STATUS', Version('0.1.2.3-alpha')),
diff --git a/test/unit/response/events.py b/test/unit/response/events.py
index e5ddc1a..80cc9f1 100644
--- a/test/unit/response/events.py
+++ b/test/unit/response/events.py
@@ -919,6 +919,18 @@ class TestEvents(unittest.TestCase):
     self.assertEqual(NEWDESC_MULTIPLE.lstrip('650 '), str(event))
     self.assertEqual(expected_relays, event.relays)
 
+  def test_network_liveness_event(self):
+    event = _get_event('650 NETWORK_LIVENESS UP')
+    self.assertTrue(isinstance(event, stem.response.events.NetworkLivenessEvent))
+    self.assertEqual('NETWORK_LIVENESS UP', str(event))
+    self.assertEqual('UP', event.status)
+
+    event = _get_event('650 NETWORK_LIVENESS DOWN')
+    self.assertEqual('DOWN', event.status)
+
+    event = _get_event('650 NETWORK_LIVENESS OTHER_STATUS key=value')
+    self.assertEqual('OTHER_STATUS', event.status)
+
   def test_new_consensus_event(self):
     expected_desc = []