Minor change to get_extra_values function

3 files changed, 59 insertions, 10 deletions

diff --git a/configobj.py b/configobj.py
index 3be82d7..8823b0b 100644
--- a/configobj.py
+++ b/configobj.py
@@ -2430,15 +2430,18 @@ def get_extra_values(conf, _prepend=()):
     ``get_extra_values`` returns a list of tuples where each tuple represents
     either an extra section, or an extra value.
     
-    The tuple contains the parent sections of the missing entry, plus the name
-    of the missing entry, similar to the tuples returned by ``flatten_errors``.
+    The tuples contain two values, a tuple representing the section the value 
+    is in and the name of the extra values. For extra values in the top level
+    section the first member will be an empty tuple. For values in the 'foo'
+    section the first member will be ``('foo',)``. For members in the 'bar'
+    subsection of the 'foo' section the first member will be ``('foo', 'bar')``.
     
     NOTE: If you call ``get_extra_values`` on a ConfigObj instance that hasn't
     been validated it will return an empty list.
     """
     out = []
     
-    out.extend(_prepend + (name,) for name in conf.extra_values)
+    out.extend((_prepend, name) for name in conf.extra_values)
     for name in conf.sections:
         if name not in conf.extra_values:
             out.extend(get_extra_values(conf[name], _prepend + (name,)))
diff --git a/docs/configobj.txt b/docs/configobj.txt
index 30ddb6c..f5d04ec 100644
--- a/docs/configobj.txt
+++ b/docs/configobj.txt
@@ -2161,12 +2161,58 @@ Here is an example of how you could present this information to the user.
         print section_string, ' = ', error
 
 
-extra_values
-============
+get_extra_values
+================
+
+
+.. code-block:: python
+
+    get_extra_values(conf)
+
+New in ConfigObj 4.7.0.
+
+Find all the values and sections not in the configspec from a validated
+ConfigObj.
+
+``get_extra_values`` returns a list of tuples where each tuple represents
+either an extra section, or an extra value.
+
+The tuples contain two values, a tuple representing the section the value 
+is in and the name of the extra values. For extra values in the top level
+section the first member will be an empty tuple. For values in the 'foo'
+section the first member will be ``('foo',)``. For members in the 'bar'
+subsection of the 'foo' section the first member will be ``('foo', 'bar')``.
+
+NOTE: If you call ``get_extra_values`` on a ConfigObj instance that hasn't
+been validated it will return an empty list.
+
+
+Example Usage
+-------------
+
+The output from ``get_extra_values`` is a list of tuples.
 
-::
+Here is an example of how you could present this information to the user.
 
+.. code-block:: python
+
+    vtor = validate.Validator()
+    # ini is your config file - cs is the configspec
+    cfg = ConfigObj(ini, configspec=cs)
+    cfg.validate(vtor, preserve_errors=True)
+    
+    for sections, name in get_extra_values(cfg):
     
+        # this code gets the extra values themselves
+        the_section = cfg
+        for section in sections:
+            the_section = cfg[section]
+        # the_value may be a section or a value
+        the_value = the_section[name]
+        
+        
+        
+
 
 CREDITS
 =======
diff --git a/functionaltests/test_validate_errors.py b/functionaltests/test_validate_errors.py
index 307ff53..ed85ec3 100644
--- a/functionaltests/test_validate_errors.py
+++ b/functionaltests/test_validate_errors.py
@@ -51,10 +51,10 @@ class TestValidateErrors(unittest.TestCase):
         extra_values = get_extra_values(conf)
         
         expected = sorted([
-            ('extra',),
-            ('extra-section',),
-            ('section', 'sub-section', 'extra'),
-            ('section', 'extra-sub-section'),
+            ((), 'extra'),
+            ((), 'extra-section'),
+            (('section', 'sub-section'), 'extra'),
+            (('section',), 'extra-sub-section'),
         ])
         self.assertEqual(sorted(extra_values), expected)