Provide human-readable event descriptions

Adding a new stem.control.event_description(event) function that can be used to get a human-friendly description of an event type. This is primarily for Nyx, but could be useful to others (similar to how we provide more human-readable manual information)... https://trac.torproject.org/projects/tor/ticket/19061

Provide human-readable event descriptions
7773234c · Damian Johnson · b6b65684 · c0af2527 · 7773234c · 7773234c
Commit 7773234c authored May 22, 2016 by Damian Johnson
--- a/docs/change_log.rst
+++ b/docs/change_log.rst
@@ -49,6 +49,7 @@ The following are only available within Stem's `git repository
  * :func:`~stem.connection.connect` and :func:`~stem.control.Controller.from_port` now connect to both port 9051 (relay's default) and 9151 (Tor Browser's default) (:trac:`16075`)
  * :class:`~stem.exit_policy.ExitPolicy` support for *accept6/reject6* and *\*4/6* wildcards (:trac:`16053`)
  * Added `support for NETWORK_LIVENESS events <api/response.html#stem.response.events.NetworkLivenessEvent>`_ (:spec:`44aac63`)
+  * Added :func:`~stem.control.event_description` for getting human-friendly descriptions of tor events (:trac:`19061`)
  * Added :func:`~stem.control.Controller.reconnect` to the :class:`~stem.control.Controller`
  * Added :func:`~stem.control.Controller.is_set` to the :class:`~stem.control.Controller`
  * Added :func:`~stem.control.Controller.is_user_traffic_allowed` to the :class:`~stem.control.Controller`

--- a/stem/control.py
+++ b/stem/control.py
@@ -66,6 +66,8 @@ If you're fine with allowing your script to raise exceptions then this can be mo

 ::

+  event_description - brief description of a tor event type
+
  Controller - General controller class intended for direct use
    | |- from_port - Provides a Controller based on a port connection.
    | +- from_socket_file - Provides a Controller based on a socket file connection.
@@ -264,6 +266,7 @@ import stem.exit_policy
 import stem.response
 import stem.response.events
 import stem.socket
+import stem.util.conf
 import stem.util.connection
 import stem.util.enum
 import stem.util.str_tools
@@ -375,12 +378,15 @@ UNCACHEABLE_GETCONF_PARAMS = (

 # number of sequential attempts before we decide that the Tor geoip database
 # is unavailable
+
 GEOIP_FAILURE_THRESHOLD = 5

 SERVER_DESCRIPTORS_UNSUPPORTED = "Tor is currently not configured to retrieve \
 server descriptors. As of Tor version 0.2.3.25 it downloads microdescriptors \
 instead unless you set 'UseMicrodescriptors 0' in your torrc."

+EVENT_DESCRIPTIONS = None
+

 class AccountingStats(collections.namedtuple('AccountingStats', ['retrieved', 'status', 'interval_end', 'time_until_reset', 'read_bytes', 'read_bytes_left', 'read_limit', 'written_bytes', 'write_bytes_left', 'write_limit'])):
  """
@@ -475,6 +481,32 @@ def with_default(yields = False):
  return decorator


+def event_description(event):
+  """
+  Provides a description for Tor events.
+
+  :param str event: the event for which a description is needed
+
+  :returns: str The event description or **None** if this is an event name we
+    don't have a description for
+  """
+
+  global EVENT_DESCRIPTIONS
+
+  if EVENT_DESCRIPTIONS is None:
+    config = stem.util.conf.Config()
+    config_path = os.path.join(os.path.dirname(__file__), 'settings.cfg')
+
+    try:
+      config.load(config_path)
+      EVENT_DESCRIPTIONS = dict([(key.lower()[18:], config.get_value(key)) for key in config.keys() if key.startswith('event.description.')])
+    except Exception as exc:
+      log.warn("BUG: stem failed to load its internal manual information from '%s': %s" % (config_path, exc))
+      return None
+
+  return EVENT_DESCRIPTIONS.get(event.lower())
+
+
 class BaseController(object):
  """
  Controller for the tor process. This is a minimal base class for other

--- a/stem/manual.py
+++ b/stem/manual.py
@@ -141,7 +141,7 @@ def _config(lowercase = True):

  try:
    config.load(config_path)
-    config_dict = dict([(key.lower() if lowercase else key, config.get_value(key)) for key in config.keys()])
+    config_dict = dict([(key.lower() if lowercase else key, config.get_value(key)) for key in config.keys() if key.startswith('manual.summary.')])
    config_dict['manual.important'] = [name.lower() if lowercase else name for name in config.get_value('manual.important', [], multiple = True)]
    return config_dict
  except Exception as exc:

--- a/stem/settings.cfg
+++ b/stem/settings.cfg
 ################################################################################
 #
-# Information related to tor configuration options...
+# Information related to tor configuration options and events...
 #
 #   * manual.important   Most commonly used configuration options.
 #   * manual.summary     Short summary describing the option.
+#   * event.description  Descriptions for the events.
 #
 ################################################################################

@@ -362,3 +363,40 @@ manual.summary.TestingLinkKeySlop Time before expiration that we replace our ed2
 manual.summary.TestingAuthKeySlop Time before expiration that we replace our ed25519 authentication key
 manual.summary.TestingSigningKeySlop Time before expiration that we replace our ed25519 signing key

+# Brief description of tor events
+
+event.description.debug Logging at the debug runlevel. This is low level, high volume information about tor's internals that generally isn't useful to users.
+event.description.info Logging at the info runlevel. This is low level information of important internal processes.
+event.description.notice Logging at the notice runlevel. This runlevel and above are shown to users by default, and includes general information the user should be aware of.
+event.description.warn Logging at the warning runlevel. These are problems the user should be aware of.
+event.description.err Logging at the error runlevel. These are critical issues that may prevent tor from working properly.
+
+event.description.addrmap New address mapping for our DNS cache.
+event.description.authdir_newdescs Indicates we just received a new descriptor. This is only used by directory authorities.
+event.description.buildtimeout_set Indicates the timeout value for a circuit has changed.
+event.description.bw Event emitted every second with the bytes sent and received by tor.
+event.description.cell_stats Event emitted every second with the count of the number of cell types per circuit.
+event.description.circ Indicates that a circuit we've established through the tor network has been created, changed, or closed.
+event.description.circ_bw Event emitted every second with the bytes sent and received on a per-circuit basis.
+event.description.circ_minor Minor changes to our circuits, such as reuse of existing circuits for a different purpose.
+event.description.clients_seen Periodic summary of the countries we've seen users connect from. This is only used by bridge relays.
+event.description.conf_changed Indicates that our torrc configuration has changed. This could be in response to a SETCONF or RELOAD signal.
+event.description.conn_bw Event emitted every second with the byytes sent and received on a per-connection basis.
+event.description.descchanged Indicates that our descriptor has changed.
+event.description.guard Indicates that the set of relays we use for our initial connection into the tor network (guards) have changed.
+event.description.hs_desc Received a hidden service descriptor that wasn't yet cached.
+event.description.hs_desc_content Content of a hidden service descriptor we've fetched.
+event.description.network_liveness Emitted when the network becomes reachable or unreachable.
+event.description.newconsensus Received a new hourly consensus of relays in the tor network.
+event.description.newdesc Indicates that a new descriptor is available.
+event.description.ns Consensus information for an individual relay has changed. This could be due to receiving a new consensus or tor locally decides a relay is up or down.
+event.description.orconn Change in our connections as a relay.
+event.description.signal Indicates that tor has received and acted upon a signal being sent to its process.
+event.description.status_client Notification of a change in tor's state as a client (ie user).
+event.description.status_general Notification of a change in tor's state.
+event.description.status_server Notification of a change in tor's state as a relay.
+event.description.stream Communication over a circuit we've established. For instance, Firefox making a connection through tor.
+event.description.stream_bw Event emitted every second with the bytes sent and received for a specific stream.
+event.description.tb_empty Statistics for when token buckets are refilled. This is only used when TestingTorNetwork is set.
+event.description.transport_launched Emitted when a pluggable transport is launched.
+
--- a/test/unit/control/controller.py
+++ b/test/unit/control/controller.py
@@ -34,6 +34,17 @@ class TestControl(unittest.TestCase):
    with patch('stem.control.Controller.add_event_listener', Mock()):
      self.controller = Controller(socket)

+  def test_event_description(self):
+    self.assertEqual("Logging at the debug runlevel. This is low level, high volume information about tor's internals that generally isn't useful to users.", stem.control.event_description('DEBUG'))
+    self.assertEqual('Event emitted every second with the bytes sent and received by tor.', stem.control.event_description('BW'))
+    self.assertEqual('Event emitted every second with the bytes sent and received by tor.', stem.control.event_description('bw'))
+
+  def test_event_description_includes_all_events(self):
+    self.assertEqual(None, stem.control.event_description('NO_SUCH_EVENT'))
+
+    for event in stem.control.EventType:
+      self.assertTrue(stem.control.event_description(event) is not None)
+
  @patch('stem.control.Controller.get_info')
  def test_get_version(self, get_info_mock):
    """