[tor-commits] [stem/master] Note commits the cached manual is from

[atagar at torproject.org]

commit 9631a2623a0ffdbf900fd7df8318b7ded3c8abcd
Author: Damian Johnson <atagar at torproject.org>
Date:   Sat Dec 5 14:35:51 2015 -0800

    Note commits the cached manual is from
    
    Adding a 'man_commit' and 'stem_commit' attribute to record the tor and stem
    commits when our manual was cached. This will be very useful to troubleshoot
    any questions regarding its contents.
---
 cache_manual.py        |   29 +++++++++++++++++++++++++++++
 stem/cached_tor_manual |    2 ++
 stem/manual.py         |   19 ++++++++++++++++++-
 test/unit/manual.py    |    2 +-
 4 files changed, 50 insertions(+), 2 deletions(-)

diff --git a/cache_manual.py b/cache_manual.py
index 06aaac2..24d8bb7 100755
--- a/cache_manual.py
+++ b/cache_manual.py
@@ -7,13 +7,40 @@ Caches tor's latest manual content. Run this to pick new man page changes.
 """
 
 import os
+import re
 import sys
 
 import stem.manual
+import stem.util.system
+
+try:
+  # account for urllib's change between python 2.x and 3.x
+  import urllib.request as urllib
+except ImportError:
+  import urllib2 as urllib
 
 CACHE_PATH = os.path.join(os.path.dirname(__file__), 'stem', 'cached_tor_manual')
+GITWEB_MAN_LOG = 'https://gitweb.torproject.org/tor.git/log/doc/tor.1.txt'
+MAN_LOG_LINK = "href='/tor.git/commit/doc/tor.1.txt\?id=([^']*)'"
 
 if __name__ == '__main__':
+  try:
+    man_log_page = urllib.urlopen(GITWEB_MAN_LOG).read()
+    man_commit = re.search(MAN_LOG_LINK, man_log_page).group(1)
+  except:
+    print "Unable to determine the latest commit to edit tor's man page: %s" % sys.exc_info()[1]
+    sys.exit(1)
+
+  try:
+    stem_commit = stem.util.system.call('git rev-parse HEAD')[0]
+  except IOError as exc:
+    print "Unable to determine stem's current commit: %s" % exc
+    sys.exit(1)
+
+  print('Latest tor commit editing man page: %s' % man_commit)
+  print('Current stem commit: %s' % stem_commit)
+  print('')
+
   cached_manual = stem.manual.Manual.from_cache()
   latest_manual = stem.manual.Manual.from_remote()
 
@@ -45,4 +72,6 @@ if __name__ == '__main__':
 
       print('\n')
 
+  latest_manual.man_commit = man_commit
+  latest_manual.stem_commit = stem_commit
   latest_manual.save(CACHE_PATH)
diff --git a/stem/cached_tor_manual b/stem/cached_tor_manual
index a549e3a..fb7b637 100644
--- a/stem/cached_tor_manual
+++ b/stem/cached_tor_manual
@@ -6,6 +6,8 @@ description
 |Basically, Tor provides a distributed network of servers or relays ("onion routers"). Users bounce their TCP streams -- web traffic, ftp, ssh, etc. -- around the network, and recipients, observers, and even the relays themselves have difficulty tracking the source of the stream.
 |
 |By default, tor will only act as a client only. To help the network by providing bandwidth as a relay, change the ORPort configuration option -- see below. Please also consult the documentation on the Tor Project's website.
+man_commit 8661b4b5a2664f2bcda36d51371c0e141be497bd
+stem_commit 6d328e8d16c7b34c87d50d4259a6936451225e89
 commandline_options -f FILE => Specify a new configuration file to contain further Tor configuration options OR pass - to make Tor read its configuration from standard input. (Default: @CONFDIR@/torrc, or $HOME/.torrc if that file is not found)
 commandline_options --ignore-missing-torrc => Specifies that Tor should treat a missing torrc file as though it were empty. Ordinarily, Tor does this for missing default torrc files, but not for those specified on the command line.
 commandline_options --list-fingerprint => Generate your keys and output your nickname and fingerprint.
diff --git a/stem/manual.py b/stem/manual.py
index 5e34020..a1ce395 100644
--- a/stem/manual.py
+++ b/stem/manual.py
@@ -224,6 +224,10 @@ class Manual(object):
   :var dict files: mapping of file paths to their description
 
   :var dict config_options: :class:`~stem.manual.ConfigOption` tuples for tor configuration options
+
+  :var str man_commit: latest tor commit editing the man page when this
+    information was cached
+  :var str stem_commit: stem commit to cache this manual information
   """
 
   def __init__(self, name, synopsis, description, commandline_options, signals, files, config_options):
@@ -234,6 +238,8 @@ class Manual(object):
     self.signals = signals
     self.files = files
     self.config_options = config_options
+    self.man_commit = None
+    self.stem_commit = None
 
   @staticmethod
   def from_cache(path = None):
@@ -270,7 +276,7 @@ class Manual(object):
             conf.get('config_options.%s.description' % key, '')
           )
 
-    return Manual(
+    manual = Manual(
       conf.get('name', ''),
       conf.get('synopsis', ''),
       conf.get('description', ''),
@@ -280,6 +286,11 @@ class Manual(object):
       config_options,
     )
 
+    manual.man_commit = conf.get('man_commit', None)
+    manual.stem_commit = conf.get('stem_commit', None)
+
+    return manual
+
   @staticmethod
   def from_man(man_path = 'tor'):
     """
@@ -365,6 +376,12 @@ class Manual(object):
     conf.set('synopsis', self.synopsis)
     conf.set('description', self.description)
 
+    if self.man_commit:
+      conf.set('man_commit', self.man_commit)
+
+    if self.stem_commit:
+      conf.set('stem_commit', self.stem_commit)
+
     for k, v in self.commandline_options.items():
       conf.set('commandline_options', '%s => %s' % (k, v), overwrite = False)
 
diff --git a/test/unit/manual.py b/test/unit/manual.py
index 031dae2..21f578d 100644
--- a/test/unit/manual.py
+++ b/test/unit/manual.py
@@ -145,7 +145,7 @@ class TestManual(unittest.TestCase):
     self.assertTrue(manual.description.startswith(EXPECTED_DESCRIPTION))
     self.assertEqual(14, len(manual.commandline_options))
     self.assertEqual(8, len(manual.signals))
-    self.assertEqual(17, len(manual.files))
+    self.assertEqual(31, len(manual.files))
     self.assertEqual(288, len(manual.config_options))
 
   def test_download_man_page_without_arguments(self):