[Author Prev][Author Next][Thread Prev][Thread Next][Author Index][Thread Index]

[tor-commits] [stem/master] Moving bulk of help output to config



commit 523d5075496a5787e8bb814ed593c6699a50e929
Author: Damian Johnson <atagar@xxxxxxxxxxxxxx>
Date:   Sun Apr 13 12:37:07 2014 -0700

    Moving bulk of help output to config
    
    Moving most of the help descriptions to a configuration file rather than
    bundling it with the source. There's still some more bits I plan to move, but
    this gets the largest parts.
---
 stem/interpretor/commands.py  |  221 ++++++++++++-----------------------------
 stem/interpretor/settings.cfg |  148 +++++++++++++++++++++++++++
 2 files changed, 214 insertions(+), 155 deletions(-)

diff --git a/stem/interpretor/commands.py b/stem/interpretor/commands.py
index b326cc0..af1948c 100644
--- a/stem/interpretor/commands.py
+++ b/stem/interpretor/commands.py
@@ -2,9 +2,12 @@
 Handles making requests and formatting the responses.
 """
 
+import os
 import re
 
 import stem
+import stem.util.conf
+import stem.util.log
 
 from stem.util.term import Attr, Color, format
 
@@ -32,76 +35,6 @@ TOR_CONTROLLER_COMMANDS = [
   'DROPGUARDS',
 ]
 
-MULTILINE_UNIMPLEMENTED_NOTICE = "Multi-line control options like this are not yet implemented."
-
-GENERAL_HELP = """Interpretor commands include:
-  /help   - provides information for interpretor and tor commands/config options
-  /quit   - shuts down the interpretor
-
-Tor commands include:
-  GETINFO - queries information from tor
-  GETCONF, SETCONF, RESETCONF - show or edit a configuration option
-  SIGNAL - issues control signal to the process (for resetting, stopping, etc)
-  SETEVENTS - configures the events tor will notify us of
-
-  USEFEATURE - enables custom behavior for the controller
-  SAVECONF - writes tor's current configuration to our torrc
-  LOADCONF - loads the given input like it was part of our torrc
-  MAPADDRESS - replaces requests for one address with another
-  POSTDESCRIPTOR - adds a relay descriptor to our cache
-  EXTENDCIRCUIT - create or extend a tor circuit
-  SETCIRCUITPURPOSE - configures the purpose associated with a circuit
-  CLOSECIRCUIT - closes the given circuit
-  ATTACHSTREAM - associates an application's stream with a tor circuit
-  REDIRECTSTREAM - sets a stream's destination
-  CLOSESTREAM - closes the given stream
-  RESOLVE - issues an asynchronous dns or rdns request over tor
-  TAKEOWNERSHIP - instructs tor to quit when this control connection is closed
-  PROTOCOLINFO - queries version and controller authentication information
-  QUIT - disconnect the control connection
-
-For more information use '/help [OPTION]'."""
-
-HELP_HELP = """Provides usage information for the given interpretor, tor command, or tor
-configuration option.
-
-Example:
-  /help GETINFO     # usage information for tor's GETINFO controller option
-"""
-
-HELP_QUIT = """Terminates the interpretor."""
-
-HELP_GETINFO = """Queries the tor process for information. Options are...
-"""
-
-HELP_GETCONF = """Provides the current value for a given configuration value. Options include...
-"""
-
-HELP_SETCONF = """Sets the given configuration parameters. Values can be quoted or non-quoted
-strings, and reverts the option to 0 or NULL if not provided.
-
-Examples:
-  * Sets a contact address and resets our family to NULL
-    SETCONF MyFamily ContactInfo=foo@xxxxxxx
-
-  * Sets an exit policy that only includes port 80/443
-    SETCONF ExitPolicy=\"accept *:80, accept *:443, reject *:*\"\
-"""
-
-HELP_RESETCONF = """Reverts the given configuration options to their default values. If a value
-is provided then this behaves in the same way as SETCONF.
-
-Examples:
-  * Returns both of our accounting parameters to their defaults
-    RESETCONF AccountingMax AccountingStart
-
-  * Uses the default exit policy and sets our nickname to be 'Goomba'
-    RESETCONF ExitPolicy Nickname=Goomba"""
-
-HELP_SIGNAL = """Issues a signal that tells the tor process to reload its torrc, dump its
-stats, halt, etc.
-"""
-
 SIGNAL_DESCRIPTIONS = (
   ("RELOAD / HUP", "reload our torrc"),
   ("SHUTDOWN / INT", "gracefully shut down, waiting 30 seconds if we're a relay"),
@@ -112,92 +45,49 @@ SIGNAL_DESCRIPTIONS = (
   ("NEWNYM", "clears the DNS cache and uses new circuits for future connections")
 )
 
-HELP_SETEVENTS = """Sets the events that we will receive. This turns off any events that aren't
-listed so sending 'SETEVENTS' without any values will turn off all event reporting.
-
-For Tor versions between 0.1.1.9 and 0.2.2.1 adding 'EXTENDED' causes some
-events to give us additional information. After version 0.2.2.1 this is
-always on.
-
-Events include...
-
-"""
-
-HELP_USEFEATURE = """Customizes the behavior of the control port. Options include...
-"""
-
-HELP_SAVECONF = """Writes Tor's current configuration to its torrc."""
-
-HELP_LOADCONF = """Reads the given text like it belonged to our torrc.
-
-Example:
-  +LOADCONF
-  # sets our exit policy to just accept ports 80 and 443
-  ExitPolicy accept *:80
-  ExitPolicy accept *:443
-  ExitPolicy reject *:*
-  ."""
-
-HELP_MAPADDRESS = """Replaces future requests for one address with another.
-
-Example:
-  MAPADDRESS 0.0.0.0=torproject.org 1.2.3.4=tor.freehaven.net"""
-
-HELP_POSTDESCRIPTOR = """Simulates getting a new relay descriptor."""
-
-HELP_EXTENDCIRCUIT = """Extends the given circuit or create a new one if the CircuitID is zero. The
-PATH is a comma separated list of fingerprints. If it isn't set then this
-uses Tor's normal path selection."""
-
-HELP_SETCIRCUITPURPOSE = """Sets the purpose attribute for a circuit."""
-
-HELP_CLOSECIRCUIT = """Closes the given circuit. If "IfUnused" is included then this only closes
-the circuit if it isn't currently being used."""
-
-HELP_ATTACHSTREAM = """Attaches a stream with the given built circuit (tor picks one on its own if
-CircuitID is zero). If HopNum is given then this hop is used to exit the
-circuit, otherwise the last relay is used."""
+HELP_OPTIONS = {
+  'HELP': ("/help [OPTION]", 'help.help'),
+  'QUIT': ("/quit", 'help.quit'),
+  'GETINFO': ("GETINFO OPTION", 'help.getinfo'),
+  'GETCONF': ("GETCONF OPTION", 'help.getconf'),
+  'SETCONF': ("SETCONF PARAM[=VALUE]", 'help.setconf'),
+  'RESETCONF': ("RESETCONF PARAM[=VALUE]", 'help.resetconf'),
+  'SIGNAL': ("SIGNAL SIG", 'help.signal'),
+  'SETEVENTS': ("SETEVENTS [EXTENDED] [EVENTS]", 'help.setevents'),
+  'USEFEATURE': ("USEFEATURE OPTION", 'help.usefeature'),
+  'SAVECONF': ("SAVECONF", 'help.saveconf'),
+  'LOADCONF': ("LOADCONF...", 'help.loadconf'),
+  'MAPADDRESS': ("MAPADDRESS SOURCE_ADDR=DESTINATION_ADDR", 'help.mapaddress'),
+  'POSTDESCRIPTOR': ("POSTDESCRIPTOR [purpose=general/controller/bridge] [cache=yes/no]...", 'help.postdescriptor'),
+  'EXTENDCIRCUIT': ("EXTENDCIRCUIT CircuitID [PATH] [purpose=general/controller]", 'help.extendcircuit'),
+  'SETCIRCUITPURPOSE': ("SETCIRCUITPURPOSE CircuitID purpose=general/controller", 'help.setcircuitpurpose'),
+  'CLOSECIRCUIT': ("CLOSECIRCUIT CircuitID [IfUnused]", 'help.closecircuit'),
+  'ATTACHSTREAM': ("ATTACHSTREAM StreamID CircuitID [HOP=HopNum]", 'help.attachstream'),
+  'REDIRECTSTREAM': ("REDIRECTSTREAM StreamID Address [Port]", 'help.redirectstream'),
+  'CLOSESTREAM': ("CLOSESTREAM StreamID Reason [Flag]", 'help.closestream'),
+  'RESOLVE': ("RESOLVE [mode=reverse] address", 'help.resolve'),
+  'TAKEOWNERSHIP': ("TAKEOWNERSHIP", 'help.takeownership'),
+  'PROTOCOLINFO': ("PROTOCOLINFO [ProtocolVersion]", 'help.protocolinfo'),
+}
 
-HELP_REDIRECTSTREAM = """Sets the destination for a given stream. This can only be done after a
-stream is created but before it's attached to a circuit."""
 
-HELP_CLOSESTREAM = """Closes the given stream, the reason being an integer matching a reason as
-per section 6.3 of the tor-spec."""
+def uses_settings(func):
+  """
+  Loads our interpretor's internal settings. This should be treated as a fatal
+  failure if unsuccessful.
 
-HELP_RESOLVE = """Performs IPv4 DNS resolution over tor, doing a reverse lookup instead if
-"mode=reverse" is included. This request is processed in the background and
-results in a ADDRMAP event with the response."""
+  :raises: **IOError** if we're unable to read or parse our internal
+    configurations
+  """
 
-HELP_TAKEOWNERSHIP = """Instructs Tor to gracefully shut down when this control connection is closed."""
+  config = stem.util.conf.get_config('stem_interpretor')
 
-HELP_PROTOCOLINFO = """Provides bootstrapping information that a controller might need when first
-starting, like Tor's version and controller authentication. This can be done
-before authenticating to the control port."""
+  if not config.get('settings_loaded', False):
+    settings_path = os.path.join(os.path.dirname(__file__), 'settings.cfg')
+    config.load(settings_path)
+    config.set('settings_loaded', 'true')
 
-HELP_OPTIONS = {
-  "HELP": ("/help [OPTION]", HELP_HELP),
-  "QUIT": ("/quit", HELP_QUIT),
-  "GETINFO": ("GETINFO OPTION", HELP_GETINFO),
-  "GETCONF": ("GETCONF OPTION", HELP_GETCONF),
-  "SETCONF": ("SETCONF PARAM[=VALUE]", HELP_SETCONF),
-  "RESETCONF": ("RESETCONF PARAM[=VALUE]", HELP_RESETCONF),
-  "SIGNAL": ("SIGNAL SIG", HELP_SIGNAL),
-  "SETEVENTS": ("SETEVENTS [EXTENDED] [EVENTS]", HELP_SETEVENTS),
-  "USEFEATURE": ("USEFEATURE OPTION", HELP_USEFEATURE),
-  "SAVECONF": ("SAVECONF", HELP_SAVECONF),
-  "LOADCONF": ("LOADCONF...", HELP_LOADCONF),
-  "MAPADDRESS": ("MAPADDRESS SOURCE_ADDR=DESTINATION_ADDR", HELP_MAPADDRESS),
-  "POSTDESCRIPTOR": ("POSTDESCRIPTOR [purpose=general/controller/bridge] [cache=yes/no]...", HELP_POSTDESCRIPTOR),
-  "EXTENDCIRCUIT": ("EXTENDCIRCUIT CircuitID [PATH] [purpose=general/controller]", HELP_EXTENDCIRCUIT),
-  "SETCIRCUITPURPOSE": ("SETCIRCUITPURPOSE CircuitID purpose=general/controller", HELP_SETCIRCUITPURPOSE),
-  "CLOSECIRCUIT": ("CLOSECIRCUIT CircuitID [IfUnused]", HELP_CLOSECIRCUIT),
-  "ATTACHSTREAM": ("ATTACHSTREAM StreamID CircuitID [HOP=HopNum]", HELP_ATTACHSTREAM),
-  "REDIRECTSTREAM": ("REDIRECTSTREAM StreamID Address [Port]", HELP_REDIRECTSTREAM),
-  "CLOSESTREAM": ("CLOSESTREAM StreamID Reason [Flag]", HELP_CLOSESTREAM),
-  "RESOLVE": ("RESOLVE [mode=reverse] address", HELP_RESOLVE),
-  "TAKEOWNERSHIP": ("TAKEOWNERSHIP", HELP_TAKEOWNERSHIP),
-  "PROTOCOLINFO": ("PROTOCOLINFO [ProtocolVersion]", HELP_PROTOCOLINFO),
-}
+  return func
 
 
 def _get_commands(controller):
@@ -329,9 +219,9 @@ class ControlInterpretor(object):
     output = ''
 
     if not arg:
-      # provides the GENERAL_HELP with everything bolded except descriptions
+      # provides the general help with everything bolded except descriptions
 
-      for line in GENERAL_HELP.splitlines():
+      for line in msg('help.general').splitlines():
         cmd_start = line.find(' - ')
 
         if cmd_start != -1:
@@ -343,7 +233,8 @@ class ControlInterpretor(object):
       # Provides information for the tor or interpretor argument. This bolds
       # the usage information and indents the description after it.
 
-      usage, description = HELP_OPTIONS[arg]
+      usage, attr = HELP_OPTIONS[arg]
+      description = msg(attr)
 
       output = format(usage + '\n', *BOLD_OUTPUT_FORMAT)
 
@@ -420,7 +311,7 @@ class ControlInterpretor(object):
           output += format(feature_options + '\n', *OUTPUT_FORMAT)
       elif arg in ('LOADCONF', 'POSTDESCRIPTOR'):
         # gives a warning that this option isn't yet implemented
-        output += format('\n' + MULTILINE_UNIMPLEMENTED_NOTICE + '\n', *ERROR_FORMAT)
+        output += format('\n' + msg('msg.multiline_unimplemented_notice') + '\n', *ERROR_FORMAT)
     else:
       output += format("No help information available for '%s'..." % arg, *ERROR_FORMAT)
 
@@ -523,7 +414,7 @@ class ControlInterpretor(object):
         pass  # TODO: implement
       elif cmd.replace('+', '') in ('LOADCONF', 'POSTDESCRIPTOR'):
         # provides a notice that multi-line controller input isn't yet implemented
-        output = format(MULTILINE_UNIMPLEMENTED_NOTICE, *ERROR_FORMAT)
+        output = format(msg('msg.multiline_unimplemented_notice'), *ERROR_FORMAT)
       else:
         try:
           response = self.controller.msg(command)
@@ -539,3 +430,23 @@ class ControlInterpretor(object):
             output = format(str(exc), *ERROR_FORMAT)
 
     return output
+
+
+@uses_settings
+def msg(message, **attr):
+  """
+  Provides the given message.
+
+  :param str message: message handle
+  :param dict attr: attributes to format the message with
+
+  :returns: **str** that was requested
+  """
+
+  config = stem.util.conf.get_config('stem_interpretor')
+
+  try:
+    return config.get(message).format(**attr)
+  except:
+    stem.util.log.notice('BUG: We attempted to use an undefined string resource (%s)' % message)
+    return ''
diff --git a/stem/interpretor/settings.cfg b/stem/interpretor/settings.cfg
new file mode 100644
index 0000000..9cd2201
--- /dev/null
+++ b/stem/interpretor/settings.cfg
@@ -0,0 +1,148 @@
+################################################################################
+#
+# Configuration data used by Stem's interpretor prompt.
+#
+################################################################################
+
+msg.multiline_unimplemented_notice Multi-line control options like this are not yet implemented.
+
+help.quit Terminates the interpretor.
+help.saveconf Writes Tor's current configuration to its torrc.
+help.postdescriptor Simulates getting a new relay descriptor.
+help.setcircuitpurpose Sets the purpose attribute for a circuit.
+help.takeownership Instructs Tor to gracefully shut down when this control connection is closed.
+
+help.general
+|Interpretor commands include:
+|  /help   - provides information for interpretor and tor commands/config options
+|  /quit   - shuts down the interpretor
+|
+|Tor commands include:
+|  GETINFO - queries information from tor
+|  GETCONF, SETCONF, RESETCONF - show or edit a configuration option
+|  SIGNAL - issues control signal to the process (for resetting, stopping, etc)
+|  SETEVENTS - configures the events tor will notify us of
+|
+|  USEFEATURE - enables custom behavior for the controller
+|  SAVECONF - writes tor's current configuration to our torrc
+|  LOADCONF - loads the given input like it was part of our torrc
+|  MAPADDRESS - replaces requests for one address with another
+|  POSTDESCRIPTOR - adds a relay descriptor to our cache
+|  EXTENDCIRCUIT - create or extend a tor circuit
+|  SETCIRCUITPURPOSE - configures the purpose associated with a circuit
+|  CLOSECIRCUIT - closes the given circuit
+|  ATTACHSTREAM - associates an application's stream with a tor circuit
+|  REDIRECTSTREAM - sets a stream's destination
+|  CLOSESTREAM - closes the given stream
+|  RESOLVE - issues an asynchronous dns or rdns request over tor
+|  TAKEOWNERSHIP - instructs tor to quit when this control connection is closed
+|  PROTOCOLINFO - queries version and controller authentication information
+|  QUIT - disconnect the control connection
+|
+|For more information use '/help [OPTION]'.
+
+help.help
+|Provides usage information for the given interpretor, tor command, or tor
+|configuration option.
+|
+|Example:
+|  /help GETINFO     # usage information for tor's GETINFO controller option
+
+help.getinfo
+|Queries the tor process for information. Options are...
+|
+
+help.getconf
+|Provides the current value for a given configuration value. Options include...
+|
+
+help.setconf
+|Sets the given configuration parameters. Values can be quoted or non-quoted
+|strings, and reverts the option to 0 or NULL if not provided.
+|
+|Examples:
+|  * Sets a contact address and resets our family to NULL
+|    SETCONF MyFamily ContactInfo=foo@xxxxxxx
+|
+|  * Sets an exit policy that only includes port 80/443
+|    SETCONF ExitPolicy=\"accept *:80, accept *:443, reject *:*\"\
+
+help.resetconf
+|Reverts the given configuration options to their default values. If a value
+|is provided then this behaves in the same way as SETCONF.
+|
+|Examples:
+|  * Returns both of our accounting parameters to their defaults
+|    RESETCONF AccountingMax AccountingStart
+|
+|  * Uses the default exit policy and sets our nickname to be 'Goomba'
+|    RESETCONF ExitPolicy Nickname=Goomba
+
+help.signal
+|Issues a signal that tells the tor process to reload its torrc, dump its
+|stats, halt, etc.
+
+help.setevents
+|Sets the events that we will receive. This turns off any events that aren't
+|listed so sending 'SETEVENTS' without any values will turn off all event reporting.
+|
+|For Tor versions between 0.1.1.9 and 0.2.2.1 adding 'EXTENDED' causes some
+|events to give us additional information. After version 0.2.2.1 this is
+|always on.
+|
+|Events include...
+|
+
+help.usefeature
+|Customizes the behavior of the control port. Options include...
+|
+
+help.loadconf
+|Reads the given text like it belonged to our torrc.
+|
+|Example:
+|  +LOADCONF
+|  # sets our exit policy to just accept ports 80 and 443
+|  ExitPolicy accept *:80
+|  ExitPolicy accept *:443
+|  ExitPolicy reject *:*
+|  .
+
+help.mapaddress
+|Replaces future requests for one address with another.
+|
+|Example:
+|  MAPADDRESS 0.0.0.0=torproject.org 1.2.3.4=tor.freehaven.net
+
+help.extendcircuit
+|Extends the given circuit or create a new one if the CircuitID is zero. The
+|PATH is a comma separated list of fingerprints. If it isn't set then this
+|uses Tor's normal path selection.
+
+help.closecircuit
+|Closes the given circuit. If "IfUnused" is included then this only closes
+|the circuit if it isn't currently being used.
+
+help.attachstream
+|Attaches a stream with the given built circuit (tor picks one on its own if
+|CircuitID is zero). If HopNum is given then this hop is used to exit the
+|circuit, otherwise the last relay is used.
+
+help.redirectstream
+|Sets the destination for a given stream. This can only be done after a
+|stream is created but before it's attached to a circuit.
+
+help.closestream
+|Closes the given stream, the reason being an integer matching a reason as
+|per section 6.3 of the tor-spec.
+
+help.resolve
+|Performs IPv4 DNS resolution over tor, doing a reverse lookup instead if
+|"mode=reverse" is included. This request is processed in the background and
+|results in a ADDRMAP event with the response.
+
+help.protocolinfo
+|Provides bootstrapping information that a controller might need when first
+|starting, like Tor's version and controller authentication. This can be done
+|before authenticating to the control port.
+



_______________________________________________
tor-commits mailing list
tor-commits@xxxxxxxxxxxxxxxxxxxx
https://lists.torproject.org/cgi-bin/mailman/listinfo/tor-commits