[tor-commits] [stem/master] Better cache_manual.py output

[atagar at torproject.org]

commit fd91b749b28dc6cbbf2c72e98579f29e198a0ec3
Author: Damian Johnson <atagar at torproject.org>
Date:   Sun Jan 10 17:05:23 2016 -0800

    Better cache_manual.py output
    
    Changing our ConfigOption to a class inadvertantly made the output pretty
    sucky...
    
      removing HTTPSProxy => <stem.manual.ConfigOption object at 0xa5b290c>
    
    That aside though it was always pretty poor in that it simply reports a bunch
    of options were added and removed - not how they were modififed. We now show
    just the attributes that were modified...
    
      ./cache_manual.py
      Latest tor commit editing man page: 4f0e28977d6376ccba599e7089aeb9e3b4f25e5f
      Current stem commit: 3c7ea19c05dfb5c373cafd367e08741a79c8d9d3
    
      Differences detected...
    
      * Manual's config_options attribute changed
    
        modified HeartbeatPeriod (description) => Log a heartbeat message every HeartbeatPeriod seconds. This is a log level notice message, designed to let you know your Tor server is still alive and doing useful things. Settings this to 0 will disable the heartbeat. Otherwise, it must be at least 30 minutes. (Default: 6 hours)
        modified AccountingRule (usage) => sum|max|in|out
        modified AccountingRule (description) => How we determine when our AccountingMax has been reached (when we should hibernate) during a time interval. Set to "max" to calculate using the higher of either the sent or received bytes (this is the default functionality). Set to "sum" to calculate using the sent plus received bytes. Set to "in" to calculate using only the received bytes. Set to "out" to calculate using only the sent bytes. (Default: max)
---
 stem/cached_tor_manual.cfg |   10 +++++-----
 stem/manual.py             |   13 +++++++++++++
 2 files changed, 18 insertions(+), 5 deletions(-)

diff --git a/stem/cached_tor_manual.cfg b/stem/cached_tor_manual.cfg
index a05c4e9..2e35cad 100644
--- a/stem/cached_tor_manual.cfg
+++ b/stem/cached_tor_manual.cfg
@@ -6,8 +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 997f779a7f05540e5f564b4d121706c4a7069fb2
-stem_commit 4b49f5d1a616acfd7b1e5b9c7c82b3f8bed836d7
+man_commit 4f0e28977d6376ccba599e7089aeb9e3b4f25e5f
+stem_commit 3c7ea19c05dfb5c373cafd367e08741a79c8d9d3
 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.
@@ -1268,7 +1268,7 @@ config_options.HeartbeatPeriod.category Relay
 config_options.HeartbeatPeriod.name HeartbeatPeriod
 config_options.HeartbeatPeriod.usage N minutes|hours|days|weeks
 config_options.HeartbeatPeriod.summary Rate at which an INFO level heartbeat message is sent
-config_options.HeartbeatPeriod.description Log a heartbeat message every HeartbeatPeriod seconds. This is a log level notice message, designed to let you know your Tor server is still alive and doing useful things. Settings this to 0 will disable the heartbeat. (Default: 6 hours)
+config_options.HeartbeatPeriod.description Log a heartbeat message every HeartbeatPeriod seconds. This is a log level notice message, designed to let you know your Tor server is still alive and doing useful things. Settings this to 0 will disable the heartbeat. Otherwise, it must be at least 30 minutes. (Default: 6 hours)
 config_options.AccountingMax.category Relay
 config_options.AccountingMax.name AccountingMax
 config_options.AccountingMax.usage N bytes|KBytes|MBytes|GBytes|KBits|MBits|GBits|TBytes
@@ -1276,9 +1276,9 @@ config_options.AccountingMax.summary Amount of traffic before hibernating
 config_options.AccountingMax.description Limits the max number of bytes sent and received within a set time period using a given calculation rule (see: AccountingStart, AccountingRule). Useful if you need to stay under a specific bandwidth. By default, the number used for calculation is the max of either the bytes sent or received. For example, with AccountingMax set to 1 GByte, a server could send 900 MBytes and receive 800 MBytes and continue running. It will only hibernate once one of the two reaches 1 GByte. This can be changed to use the sum of the both bytes received and sent by setting the AccountingRule option to "sum" (total bandwidth in/out). When the number of bytes remaining gets low, Tor will stop accepting new connections and circuits. When the number of bytes is exhausted, Tor will hibernate until some time in the next accounting period. To prevent all servers from waking at the same time, Tor will also wait until a random point in each period before waking up. If you
  have bandwidth cost issues, enabling hibernation is preferable to setting a low bandwidth, since it provides users with a collection of fast servers that are up some of the time, which is more useful than a set of slow servers that are always "available".
 config_options.AccountingRule.category Relay
 config_options.AccountingRule.name AccountingRule
-config_options.AccountingRule.usage sum|max
+config_options.AccountingRule.usage sum|max|in|out
 config_options.AccountingRule.summary Method to determine when the accounting limit is reached
-config_options.AccountingRule.description How we determine when our AccountingMax has been reached (when we should hibernate) during a time interval. Set to "max" to calculate using the higher of either the sent or received bytes (this is the default functionality). Set to "sum" to calculate using the sent plus received bytes. (Default: max)
+config_options.AccountingRule.description How we determine when our AccountingMax has been reached (when we should hibernate) during a time interval. Set to "max" to calculate using the higher of either the sent or received bytes (this is the default functionality). Set to "sum" to calculate using the sent plus received bytes. Set to "in" to calculate using only the received bytes. Set to "out" to calculate using only the sent bytes. (Default: max)
 config_options.AccountingStart.category Relay
 config_options.AccountingStart.name AccountingStart
 config_options.AccountingStart.usage day|week|month [day] HH:MM
diff --git a/stem/manual.py b/stem/manual.py
index fe69dc1..55c94a2 100644
--- a/stem/manual.py
+++ b/stem/manual.py
@@ -166,6 +166,19 @@ def _manual_differences(previous_manual, new_manual):
       if attr in ('name', 'synopsis', 'description'):
         lines.append('  Previously...\n\n%s\n' % previous_attr)
         lines.append('  Updating to...\n\n%s' % new_attr)
+      elif attr == 'config_options':
+        for config_name, config_attr in new_attr.items():
+          previous = previous_attr.get(config_name)
+
+          if previous is None:
+            lines.append('  adding new config option => %s' % config_name)
+          elif config_attr != previous:
+            for attr in ('name', 'category', 'usage', 'summary', 'description'):
+              if getattr(config_attr, attr) != getattr(previous, attr):
+                lines.append('  modified %s (%s) => %s' % (config_name, attr, getattr(config_attr, attr)))
+
+        for config_name in set(previous_attr.keys()).difference(new_attr.keys()):
+          lines.append('  removing config option => %s' % config_name)
       else:
         added_items = set(new_attr.items()).difference(previous_attr.items())
         removed_items = set(previous_attr.items()).difference(new_attr.items())