[tor-commits] [stem/master] Splitting set_conf/reset_conf back up

[atagar at torproject.org]

commit 3d1538746adad85bb7235d8bc7f4b3d93b1f3d50
Author: Damian Johnson <atagar at torproject.org>
Date:   Sun Jul 8 12:39:29 2012 -0700

    Splitting set_conf/reset_conf back up
    
    Ravi made a good point that the set_option() syntax for resetting config
    options is now worse, so trying a compromise of our approaches.
    
    This reintroduces set_conf() and reset_conf() methods, but also keeping my
    set_options() method to handle the more complicated use cases (batch setconf
    requests, resetconf with values, and context sensitive options).
    
    Personally I found the old set_conf() method confusingly overloaded (python
    does not handle overloading use cases very well). This solution lets us keep
    the set_conf() and reset_conf() methods simple, while also providing something
    that's reasonably intuitive (imho) for the complicated use cases.
---
 stem/control.py                  |   49 ++++++++++++++++++++++++--------------
 test/integ/control/controller.py |   16 ++++++++----
 2 files changed, 42 insertions(+), 23 deletions(-)

diff --git a/stem/control.py b/stem/control.py
index ccfeb94..2c12d43 100644
--- a/stem/control.py
+++ b/stem/control.py
@@ -13,11 +13,12 @@ interacting at a higher level.
   from_socket_file - Provides a Controller based on a socket file connection.
   
   Controller - General controller class intended for direct use.
-    |- get_info - issues a GETINFO query
-    |- get_conf - issues a GETCONF query for a single parameter
-    |- get_conf_mapping - issues a GETCONF query for multiple parameters
-    |- set_conf - issues a SETCONF query
-    |- reset_conf - issues a RESETCONF query
+    |- get_info - issues a GETINFO query for a parameter
+    |- get_conf - gets the value of a configuration option
+    |- get_conf_mapping - gets the values of multiple configuration options
+    |- set_conf - sets the value of a configuration option
+    |- reset_conf - reverts configuration options to their default values
+    |- set_options - sets or resets the values of multiple configuration options
     |- get_version - convenience method to get tor version
     |- authenticate - convenience method to authenticate the controller
     +- protocolinfo - convenience method to get the protocol info
@@ -664,22 +665,17 @@ class Controller(BaseController):
       if default != UNDEFINED: return default
       else: raise exc
   
-  def set_option(self, param, value, reset = False):
+  def set_conf(self, param, value):
     """
-    Changes the value of a tor configuration option via either a SETCONF or
-    RESETCONF query. Both behave identically unless our value is None, in which
-    case SETCONF sets the value to 0 or NULL, and RESETCONF returns it to its
-    default value.
-    
-    Our value can be any of the following...
+    Changes the value of a tor configuration option. Our value can be any of
+    the following...
     
     * a string to set a single value
     * a list of strings to set a series of values (for instance the ExitPolicy)
-    * None to either set the value to 0/NULL or reset it to its default
+    * None to either set the value to 0/NULL
     
     :param str param: configuration option to be set
     :param str,list value: value to set the parameter to
-    :param bool reset: issues a SETCONF if False, and RESETCONF if True
     
     :raises:
       :class:`stem.socket.ControllerError` if the call fails
@@ -687,12 +683,29 @@ class Controller(BaseController):
       :class:`stem.socket.InvalidRequest` if the configuration setting is impossible or if there's a syntax error in the configuration values
     """
     
-    self.set_options({param: value}, reset)
+    self.set_options({param: value}, False)
+  
+  def reset_conf(self, *params):
+    """
+    Reverts one or more parameters to their default values.
+    
+    :param str params: configuration option to be reset
+    
+    :raises:
+      :class:`stem.socket.ControllerError` if the call fails
+      :class:`stem.socket.InvalidArguments` if configuration options requested was invalid
+      :class:`stem.socket.InvalidRequest` if the configuration setting is impossible or if there's a syntax error in the configuration values
+    """
+    
+    self.set_options(dict([(entry, None) for entry in params]), True)
   
   def set_options(self, params, reset = False):
     """
-    Changes multiple tor configurations, in a similar fashion to
-    :func:`stem.control.Controller.set_option`. For example...
+    Changes multiple tor configuration options via either a SETCONF or
+    RESETCONF query. Both behave identically unless our value is None, in which
+    case SETCONF sets the value to 0 or NULL, and RESETCONF returns it to its
+    default value. This accepts str, list, or None values in a similar fashion
+    to :func:`stem.control.Controller.set_conf`. For example...
     
     ::
     
@@ -708,7 +721,7 @@ class Controller(BaseController):
     configuration (those options are order dependent).
     
     :param dict,list params: mapping of configuration options to the values we're setting it to
-    :param bool reset: issues a SETCONF if False, and RESETCONF if True
+    :param bool reset: issues a RESETCONF, returning None values to their defaults if True
     
     :raises:
       :class:`stem.socket.ControllerError` if the call fails
diff --git a/test/integ/control/controller.py b/test/integ/control/controller.py
index 3a15634..65dfe18 100644
--- a/test/integ/control/controller.py
+++ b/test/integ/control/controller.py
@@ -194,9 +194,10 @@ class TestController(unittest.TestCase):
       self.assertEqual({}, controller.get_conf_map("", "la-di-dah"))
       self.assertEqual({}, controller.get_conf_map([], "la-di-dah"))
   
-  def test_set_options(self):
+  def test_set_conf(self):
     """
-    Exercises set_option() and set_options() with valid and invalid requests.
+    Exercises set_conf(), reset_conf(), and set_options() methods with valid
+    and invalid requests.
     """
     
     if test.runner.require_control(self): return
@@ -208,21 +209,26 @@ class TestController(unittest.TestCase):
       try:
         # successfully set a single option
         connlimit = int(controller.get_conf("ConnLimit"))
-        controller.set_option("connlimit", str(connlimit - 1))
+        controller.set_conf("connlimit", str(connlimit - 1))
         self.assertEqual(connlimit - 1, int(controller.get_conf("ConnLimit")))
         
         # successfully set a single list option
         exit_policy = ["accept *:7777", "reject *:*"]
-        controller.set_option("ExitPolicy", exit_policy)
+        controller.set_conf("ExitPolicy", exit_policy)
         self.assertEqual(exit_policy, controller.get_conf("ExitPolicy", multiple = True))
         
         # fail to set a single option
         try:
-          controller.set_option("invalidkeyboo", "abcde")
+          controller.set_conf("invalidkeyboo", "abcde")
           self.fail()
         except stem.socket.InvalidArguments, exc:
           self.assertEqual(["invalidkeyboo"], exc.arguments)
         
+        # resets configuration parameters
+        controller.reset_conf("ConnLimit", "ExitPolicy")
+        self.assertEqual(connlimit, int(controller.get_conf("ConnLimit")))
+        self.assertEqual(None, controller.get_conf("ExitPolicy"))
+        
         # successfully sets multiple config options
         controller.set_options({
           "connlimit": str(connlimit - 2),