Change the coverage.config item-access syntax to a real method call.

The square brackets were too cute, and I couldn't figure out how to document
them anyway!

7 files changed, 100 insertions, 42 deletions

diff --git a/coverage/cmdline.py b/coverage/cmdline.py
index f148200..0a84aa1 100644
--- a/coverage/cmdline.py
+++ b/coverage/cmdline.py
@@ -469,9 +469,9 @@ class CoverageScript(object):
             # Apply the command line fail-under options, and then use the config
             # value, so we can get fail_under from the config file.
             if options.fail_under is not None:
-                self.coverage.config["report:fail_under"] = options.fail_under
+                self.coverage.set_option("report:fail_under", options.fail_under)
 
-            if self.coverage.config["report:fail_under"]:
+            if self.coverage.get_option("report:fail_under"):
 
                 # Total needs to be rounded, but be careful of 0 and 100.
                 if 0 < total < 1:
@@ -481,7 +481,7 @@ class CoverageScript(object):
                 else:
                     total = round(total)
 
-                if total >= self.coverage.config["report:fail_under"]:
+                if total >= self.coverage.get_option("report:fail_under"):
                     return OK
                 else:
                     return FAIL_UNDER
@@ -555,7 +555,7 @@ class CoverageScript(object):
     def do_run(self, options, args):
         """Implementation of 'coverage run'."""
 
-        if not self.coverage.config["run:parallel"]:
+        if not self.coverage.get_option("run:parallel"):
             if not options.append:
                 self.coverage.erase()
 
@@ -575,7 +575,8 @@ class CoverageScript(object):
             self.coverage.stop()
             if code_ran:
                 if options.append:
-                    self.coverage.combine(data_paths=[self.coverage.config["run:data_file"]])
+                    data_paths = [self.coverage.get_option("run:data_file")]
+                    self.coverage.combine(data_paths=data_paths)
                 self.coverage.save()
 
         return OK
diff --git a/coverage/config.py b/coverage/config.py
index 9939d6c..83eea51 100644
--- a/coverage/config.py
+++ b/coverage/config.py
@@ -310,8 +310,17 @@ class CoverageConfig(object):
         """Get a dictionary of options for the plugin named `plugin`."""
         return self.plugin_options.get(plugin, {})
 
-    # TODO: docs for this.
-    def __setitem__(self, option_name, value):
+    def set_option(self, option_name, value):
+        """Set an option in the configuration.
+
+        `option_name` is a colon-separated string indicating the section and
+        option name.  For example, the ``branch`` option in the ``[run]``
+        section of the config file would be indicated with `"run:branch"`.
+
+        `value` is the new value for the option.
+
+        """
+
         # Check all the hard-coded options.
         for option_spec in self.CONFIG_FILE_OPTIONS:
             attr, where = option_spec[:2]
@@ -328,8 +337,17 @@ class CoverageConfig(object):
         # If we get here, we didn't find the option.
         raise CoverageException("No such option: %r" % option_name)
 
-    # TODO: docs for this.
-    def __getitem__(self, option_name):
+    def get_option(self, option_name):
+        """Get an option from the configuration.
+
+        `option_name` is a colon-separated string indicating the section and
+        option name.  For example, the ``branch`` option in the ``[run]``
+        section of the config file would be indicated with `"run:branch"`.
+
+        Returns the value of the option.
+
+        """
+
         # Check all the hard-coded options.
         for option_spec in self.CONFIG_FILE_OPTIONS:
             attr, where = option_spec[:2]
diff --git a/coverage/control.py b/coverage/control.py
index ad3c1bd..02fe66b 100644
--- a/coverage/control.py
+++ b/coverage/control.py
@@ -596,6 +596,41 @@ class Coverage(object):
             msg = "[%d] %s" % (os.getpid(), msg)
         sys.stderr.write("Coverage.py warning: %s\n" % msg)
 
+    def get_option(self, option_name):
+        """Get an option from the configuration.
+
+        `option_name` is a colon-separated string indicating the section and
+        option name.  For example, the ``branch`` option in the ``[run]``
+        section of the config file would be indicated with `"run:branch"`.
+
+        Returns the value of the option.
+
+        """
+        return self.config.get_option(option_name)
+
+    def set_option(self, option_name, value):
+        """Set an option in the configuration.
+
+        `option_name` is a colon-separated string indicating the section and
+        option name.  For example, the ``branch`` option in the ``[run]``
+        section of the config file would be indicated with `"run:branch"`.
+
+        `value` is the new value for the option.  This should be a Python
+        value where appropriate.  For example, use True for booleans, not the
+        string ``"True"``.
+
+        As an example, calling::
+
+            cov.set_option("run:branch", True)
+
+        has the same effect as this configuration file:
+
+            [run]
+            branch = True
+
+        """
+        self.config.set_option(option_name, value)
+
     def use_cache(self, usecache):
         """Obsolete method."""
         self._init()
diff --git a/tests/test_cmdline.py b/tests/test_cmdline.py
index a379d40..3baa262 100644
--- a/tests/test_cmdline.py
+++ b/tests/test_cmdline.py
@@ -56,7 +56,11 @@ class BaseCmdLineTest(CoverageTest):
         # We'll invoke .coverage as the constructor, and then keep using the
         # same object as the resulting coverage object.
         mk.coverage.return_value = mk
-        mk.config = CoverageConfig()
+
+        # The mock needs to get options, but shouldn't need to set them.
+        config = CoverageConfig()
+        mk.get_option = config.get_option
+
         return mk
 
     def mock_command_line(self, args):
diff --git a/tests/test_config.py b/tests/test_config.py
index 9d3c95d..93a7bbf 100644
--- a/tests/test_config.py
+++ b/tests/test_config.py
@@ -146,41 +146,41 @@ class ConfigTest(CoverageTest):
     def test_tweaks_after_constructor(self):
         # Arguments to the constructor are applied to the configuration.
         cov = coverage.Coverage(timid=True, data_file="fooey.dat")
-        cov.config["run:timid"] = False
+        cov.set_option("run:timid", False)
 
         self.assertFalse(cov.config.timid)
         self.assertFalse(cov.config.branch)
         self.assertEqual(cov.config.data_file, "fooey.dat")
 
-        self.assertFalse(cov.config["run:timid"])
-        self.assertFalse(cov.config["run:branch"])
-        self.assertEqual(cov.config["run:data_file"], "fooey.dat")
+        self.assertFalse(cov.get_option("run:timid"))
+        self.assertFalse(cov.get_option("run:branch"))
+        self.assertEqual(cov.get_option("run:data_file"), "fooey.dat")
 
     def test_tweak_error_checking(self):
         # Trying to set an unknown config value raises an error.
         cov = coverage.Coverage()
         with self.assertRaises(CoverageException):
-            cov.config["run:xyzzy"] = 12
+            cov.set_option("run:xyzzy", 12)
         with self.assertRaises(CoverageException):
-            cov.config["xyzzy:foo"] = 12
+            cov.set_option("xyzzy:foo", 12)
         with self.assertRaises(CoverageException):
-            _ = cov.config["run:xyzzy"]
+            _ = cov.get_option("run:xyzzy")
         with self.assertRaises(CoverageException):
-            _ = cov.config["xyzzy:foo"]
+            _ = cov.get_option("xyzzy:foo")
 
     def test_tweak_plugin_options(self):
         # Plugin options have a more flexible syntax.
         cov = coverage.Coverage()
-        cov.config["run:plugins"] = ["fooey.plugin", "xyzzy.coverage.plugin"]
-        cov.config["fooey.plugin:xyzzy"] = 17
-        cov.config["xyzzy.coverage.plugin:plugh"] = ["a", "b"]
+        cov.set_option("run:plugins", ["fooey.plugin", "xyzzy.coverage.plugin"])
+        cov.set_option("fooey.plugin:xyzzy", 17)
+        cov.set_option("xyzzy.coverage.plugin:plugh", ["a", "b"])
         with self.assertRaises(CoverageException):
-            cov.config["no_such.plugin:foo"] = 23
+            cov.set_option("no_such.plugin:foo", 23)
 
-        self.assertEqual(cov.config["fooey.plugin:xyzzy"], 17)
-        self.assertEqual(cov.config["xyzzy.coverage.plugin:plugh"], ["a", "b"])
+        self.assertEqual(cov.get_option("fooey.plugin:xyzzy"), 17)
+        self.assertEqual(cov.get_option("xyzzy.coverage.plugin:plugh"), ["a", "b"])
         with self.assertRaises(CoverageException):
-            _ = cov.config["no_such.plugin:foo"]
+            _ = cov.get_option("no_such.plugin:foo")
 
     def test_unknown_option(self):
         self.make_file(".coveragerc", """\
diff --git a/tests/test_plugins.py b/tests/test_plugins.py
index 558c043..5218f6c 100644
--- a/tests/test_plugins.py
+++ b/tests/test_plugins.py
@@ -148,7 +148,7 @@ class PluginTest(CoverageTest):
 
         self.assert_doesnt_exist("evidence.out")
         cov = coverage.Coverage()
-        cov.config["run:plugins"] = ["my_plugin"]
+        cov.set_option("run:plugins", ["my_plugin"])
         cov.start()
         cov.stop()
 
@@ -159,7 +159,7 @@ class PluginTest(CoverageTest):
         # Prove that a missing plugin will raise an ImportError.
         with self.assertRaises(ImportError):
             cov = coverage.Coverage()
-            cov.config["run:plugins"] = ["does_not_exist_woijwoicweo"]
+            cov.set_option("run:plugins", ["does_not_exist_woijwoicweo"])
             cov.start()
         cov.stop()
 
@@ -170,7 +170,7 @@ class PluginTest(CoverageTest):
             """)
         with self.assertRaises(ZeroDivisionError):
             cov = coverage.Coverage()
-            cov.config["run:plugins"] = ["plugin_over_zero"]
+            cov.set_option("run:plugins", ["plugin_over_zero"])
             cov.start()
         cov.stop()
 
@@ -188,7 +188,7 @@ class PluginTest(CoverageTest):
         debug_out = StringIO()
         cov = coverage.Coverage(debug=["sys"])
         cov._debug_file = debug_out
-        cov.config["run:plugins"] = ["plugin_sys_info"]
+        cov.set_option("run:plugins", ["plugin_sys_info"])
         cov.load()
 
         out_lines = debug_out.getvalue().splitlines()
@@ -212,7 +212,7 @@ class PluginTest(CoverageTest):
         debug_out = StringIO()
         cov = coverage.Coverage(debug=["sys"])
         cov._debug_file = debug_out
-        cov.config["run:plugins"] = ["plugin_no_sys_info"]
+        cov.set_option("run:plugins", ["plugin_no_sys_info"])
         cov.load()
 
         out_lines = debug_out.getvalue().splitlines()
@@ -253,7 +253,7 @@ class PluginWarningOnPyTracer(CoverageTest):
         self.make_file("simple.py", """a = 1""")
 
         cov = coverage.Coverage()
-        cov.config["run:plugins"] = ["tests.plugin1"]
+        cov.set_option("run:plugins", ["tests.plugin1"])
 
         warnings = []
         def capture_warning(msg):
@@ -294,7 +294,7 @@ class GoodPluginTest(FileTracerTest):
         cov = coverage.Coverage()
         CheckUniqueFilenames.hook(cov, '_should_trace')
         CheckUniqueFilenames.hook(cov, '_check_include_omit_etc')
-        cov.config["run:plugins"] = ["tests.plugin1"]
+        cov.set_option("run:plugins", ["tests.plugin1"])
 
         # Import the Python file, executing it.
         self.start_import_stop(cov, "simple")
@@ -359,7 +359,7 @@ class GoodPluginTest(FileTracerTest):
         cov = coverage.Coverage(omit=["*quux*"])
         CheckUniqueFilenames.hook(cov, '_should_trace')
         CheckUniqueFilenames.hook(cov, '_check_include_omit_etc')
-        cov.config["run:plugins"] = ["tests.plugin2"]
+        cov.set_option("run:plugins", ["tests.plugin2"])
 
         self.start_import_stop(cov, "caller")
 
@@ -390,7 +390,7 @@ class GoodPluginTest(FileTracerTest):
         cov = coverage.Coverage(branch=True, omit=["*quux*"])
         CheckUniqueFilenames.hook(cov, '_should_trace')
         CheckUniqueFilenames.hook(cov, '_check_include_omit_etc')
-        cov.config["run:plugins"] = ["tests.plugin2"]
+        cov.set_option("run:plugins", ["tests.plugin2"])
 
         self.start_import_stop(cov, "caller")
 
@@ -409,7 +409,7 @@ class GoodPluginTest(FileTracerTest):
         self.make_render_and_caller()
 
         cov = coverage.Coverage(branch=True, omit=["*quux*"])
-        cov.config["run:plugins"] = ["tests.plugin2"]
+        cov.set_option("run:plugins", ["tests.plugin2"])
 
         self.start_import_stop(cov, "caller")
 
@@ -431,7 +431,7 @@ class GoodPluginTest(FileTracerTest):
         self.make_render_and_caller()
 
         cov = coverage.Coverage(branch=True, omit=["*quux*"])
-        cov.config["run:plugins"] = ["tests.plugin2"]
+        cov.set_option("run:plugins", ["tests.plugin2"])
 
         self.start_import_stop(cov, "caller")
 
@@ -446,7 +446,7 @@ class GoodPluginTest(FileTracerTest):
         self.make_render_and_caller()
 
         cov = coverage.Coverage(branch=True, omit=["*quux*"])
-        cov.config["run:plugins"] = ["tests.plugin2"]
+        cov.set_option("run:plugins", ["tests.plugin2"])
 
         self.start_import_stop(cov, "caller")
 
@@ -499,7 +499,7 @@ class GoodPluginTest(FileTracerTest):
             f = 6
             """)
         cov = coverage.Coverage(include=["unsuspecting.py"])
-        cov.config["run:plugins"] = ["fairly_odd_plugin"]
+        cov.set_option("run:plugins", ["fairly_odd_plugin"])
         self.start_import_stop(cov, "unsuspecting")
 
         repout = StringIO()
@@ -548,7 +548,7 @@ class BadPluginTest(FileTracerTest):
             """)
 
         cov = coverage.Coverage()
-        cov.config["run:plugins"] = [module_name]
+        cov.set_option("run:plugins", [module_name])
         self.start_import_stop(cov, "simple")
 
         stderr = self.stderr()
diff --git a/tests/test_xml.py b/tests/test_xml.py
index dbf0927..3806c58 100644
--- a/tests/test_xml.py
+++ b/tests/test_xml.py
@@ -184,7 +184,7 @@ class XmlPackageStructureTest(XmlTestHelpers, CoverageTest):
         cov = coverage.Coverage(source=".")
         self.start_import_stop(cov, "main")
 
-        cov.config["xml:package_depth"] = 1
+        cov.set_option("xml:package_depth", 1)
         self.assert_package_and_class_tags(cov, """\
             <package name=".">
                <class filename="main.py" name="main.py">
@@ -197,7 +197,7 @@ class XmlPackageStructureTest(XmlTestHelpers, CoverageTest):
                <class filename="d0/f0.py" name="f0.py">
             """)
 
-        cov.config["xml:package_depth"] = 2
+        cov.set_option("xml:package_depth", 2)
         self.assert_package_and_class_tags(cov, """\
             <package name=".">
                <class filename="main.py" name="main.py">
@@ -211,7 +211,7 @@ class XmlPackageStructureTest(XmlTestHelpers, CoverageTest):
                <class filename="d0/d0/f0.py" name="f0.py">
             """)
 
-        cov.config["xml:package_depth"] = 3
+        cov.set_option("xml:package_depth", 3)
         self.assert_package_and_class_tags(cov, """\
             <package name=".">
                <class filename="main.py" name="main.py">