Improved error checking when parsing a Blurb. (#507)

We now:
* Check the entries in metadata in order, so we complain about
  the *first* one that has an error, which is a more familiar
  user experience.
* Have checks for:
	* Invalid issue number
	* Invalid section
	* Empty section
	* Completely missing section

(There is no test for "missing issue number", because it's legal
to have a Blurb with no issue number.  "no changes" blurbs don't
have an issue number.  But we do now reliably test that, *if* the
issue number is specified, it *is* correctly formatted.)

Author: larryhastings

blurb/blurb.py

@@ -472,27 +472,34 @@ def finish_entry():
                     throw("Blurb 'body' can't start with " + repr(naughty_prefix) + "!")
 
             no_changes = metadata.get('no changes')
-            section = metadata.get('section')
-
-            if not no_changes:
-                if not section:
-                    throw("No 'section' specified.  You must provide one!")
-                elif section not in sections:
-                    throw("Invalid 'section'!  You must use one of the predefined sections.")
-
-            issue_number = None
-
-            if metadata.get("gh-issue") is not None:
-                try:
-                    issue_number = int(metadata.get('gh-issue'))
-                except (TypeError, ValueError):
-                    throw("Invalid GitHub issue number! (" + repr(issue_number) + ")")
-            elif metadata.get("bpo") is not None:
-                try:
-                    issue_number = int(metadata.get('bpo'))
-                except (TypeError, ValueError):
-                    throw("Invalid bpo issue number! (" + repr(issue_number) + ")")
 
+            issue_keys = {
+                'gh-issue': 'GitHub',
+                'bpo': 'bpo',
+                }
+            for key, value in metadata.items():
+                # Iterate over metadata items in order.
+                # We parsed the blurb file line by line,
+                # so we'll insert metadata keys in the
+                # order we see them.  So if we issue the
+                # errors in the order we see the keys,
+                # we'll complain about the *first* error
+                # we see in the blurb file, which is a
+                # better user experience.
+                if key in issue_keys:
+                    try:
+                        int(value)
+                    except (TypeError, ValueError):
+                        throw(f"Invalid {issue_keys[key]} issue number! ({value!r})")
+
+                if key == "section":
+                    if no_changes:
+                        continue
+                    if value not in sections:
+                        throw(f"Invalid section {value!r}!  You must use one of the predefined sections.")
+
+            if not 'section' in metadata:
+                throw("No 'section' specified.  You must provide one!")
 
             self.append((metadata, text))
             metadata = {}
@@ -854,6 +861,13 @@ def test(*args):
     # unittest.main doesn't work because this isn't a module
     # so we'll do it ourselves
 
+    while not (os.path.isdir(".git") and os.path.isdir("blurb")):
+        old_dir = os.getcwd()
+        os.chdir("..")
+        if old_dir == os.getcwd():
+            # we reached the root and never found it!
+            sys.exit("Error: Couldn't find the root of your blurb repo!")
+
     print("-" * 79)
 
     for clsname, cls in sorted(globals().items()):

blurb/tests/fail/invalid-gh-number.rst

@@ -0,0 +1,4 @@
+.. gh-issue: abcde
+.. section: Library
+
+Things, stuff.

blurb/tests/fail/invalid-section.rst

@@ -0,0 +1,4 @@
+.. gh-issue: 8675309
+.. section: Funky Kong
+
+This is an invalid blurb.  Shockingly, "Funky Kong" is not a valid section name.

blurb/tests/fail/no-gh-number.rst

@@ -0,0 +1,4 @@
+.. gh-issue:
+.. section: Library
+
+Things, stuff.

blurb/tests/fail/no-section.rst

@@ -0,0 +1,3 @@
+.. gh-issue: 8675309
+
+This is an invalid blurb.  It doesn't have a "section".