Add `-i/--issue option to blurb add

Author: AA-Turner

CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 2.1.0
+
+- Add the `-i` / `--issue` option to the 'blurb add' command.
+  This lets you pre-fill the `gh-issue` field in the template.
+
 ## 2.0.0
 
 * Move 'blurb test' subcommand into test suite by @hugovk in https://github.com/python/blurb/pull/37

README.md

@@ -108,6 +108,13 @@ Here's how you interact with the file:
 
 * Add the GitHub issue number for this commit to the
   end of the `.. gh-issue:` line.
+  The issue can also be specified via the ``-i`` / ``--issue`` option:
+
+  ```shell
+  $ blurb add -i 109198
+  # or equivalently
+  $ blurb add -i https://github.com/python/cpython/issues/109198
+  ```
 
 * Uncomment the line with the relevant `Misc/NEWS` section for this entry.
   For example, if this should go in the `Library` section, uncomment

src/blurb/blurb.py

@@ -824,25 +824,63 @@ def find_editor():
     error('Could not find an editor! Set the EDITOR environment variable.')
 
 
-def _template_text_for_temp_file():
+def _extract_issue_number(issue, /):
+    if issue is None:
+        return None
+    issue = issue.strip()
+
+    if issue.startswith(('GH-', 'gh-')):
+        stripped = issue[3:]
+    else:
+        stripped = issue.removeprefix('#')
+    try:
+        return int(stripped)
+    except ValueError:
+        pass
+
+    # Allow GitHub URL with or without the scheme
+    stripped = issue.removeprefix('https://')
+    stripped = stripped.removeprefix('github.com/python/cpython/issues/')
+    try:
+        return int(stripped)
+    except ValueError:
+        pass
+
+    sys.exit(f"Invalid GitHub issue number: {issue}")
+
+
+def _blurb_template_text(*, issue):
+    issue_number = _extract_issue_number(issue)
+
     text = template
 
     # Ensure that there is a trailing space after '.. gh-issue:' to make
-    # filling in the template easier.
+    # filling in the template easier, unless an issue number was given
+    # through the --issue command-line flag.
     issue_line = ".. gh-issue:"
     without_space = "\n" + issue_line + "\n"
-    with_space = "\n" + issue_line + " \n"
     if without_space not in text:
-        sys.exit("Can't find gh-issue line to ensure there's a space on the end!")
-    text = text.replace(without_space, with_space)
+        sys.exit("Can't find gh-issue line in the template!")
+    if issue_number is None:
+        with_space = "\n" + issue_line + " \n"
+        text = text.replace(without_space, with_space)
+    else:
+        with_issue_number = f"\n{issue_line} {issue_number}\n"
+        text = text.replace(without_space, with_issue_number)
 
     return text
 
 
 @subcommand
-def add():
+def add(*, issue=None):
     """
 Add a blurb (a Misc/NEWS.d/next entry) to the current CPython repo.
+
+Use -i/--issue to specify a GitHub issue number or link, e.g.:
+
+    blurb add -i 12345
+    # or
+    blurb add -i https://github.com/python/cpython/issues/12345
     """
 
     editor = find_editor()
@@ -851,7 +889,7 @@ def add():
     os.close(handle)
     atexit.register(lambda : os.unlink(tmp_path))
 
-    text = _template_text_for_temp_file()
+    text = _blurb_template_text(issue=issue)
     with open(tmp_path, "w", encoding="utf-8") as file:
         file.write(text)
 

tests/test_blurb_add.py

@@ -0,0 +1,87 @@
+import re
+
+import pytest
+
+from blurb import blurb
+
+
+def test_valid_no_issue_number():
+    assert blurb._extract_issue_number(None) is None
+    res = blurb._blurb_template_text(issue=None)
+    lines = frozenset(res.splitlines())
+    assert '.. gh-issue:' not in lines
+    assert '.. gh-issue: ' in lines
+
+
+@pytest.mark.parametrize('issue', (
+    # issue given by their number
+    '12345',
+    ' 12345  ',
+    # issue given by their number and a 'GH-' prefix
+    'GH-12345',
+    ' GH-12345  ',
+    # issue given by their number and a 'gh-' prefix
+    'gh-12345',
+    ' gh-12345  ',
+    # issue given by their number and a '#' prefix
+    '#12345',
+    ' #12345  ',
+    # issue given by their URL (no scheme)
+    'github.com/python/cpython/issues/12345',
+    ' github.com/python/cpython/issues/12345  ',
+    # issue given by their URL (with scheme)
+    'https://github.com/python/cpython/issues/12345',
+    ' https://github.com/python/cpython/issues/12345  ',
+))
+def test_valid_issue_number_12345(issue):
+    actual = blurb._extract_issue_number(issue)
+    assert actual == 12345
+
+    res = blurb._blurb_template_text(issue=issue)
+    lines = frozenset(res.splitlines())
+    assert '.. gh-issue:' not in lines
+    assert '.. gh-issue: ' not in lines
+    assert '.. gh-issue: 12345' in lines
+
+
+@pytest.mark.parametrize('issue', (
+    '',
+    'abc',
+    'Gh-123',
+    'gh-abc',
+    'gh- 123',
+    'gh -123',
+    'gh-',
+    'bpo-',
+    'bpo-12345',
+    'github.com/python/cpython/issues',
+    'github.com/python/cpython/issues/',
+    'github.com/python/cpython/issues/abc',
+    'github.com/python/cpython/issues/gh-abc',
+    'github.com/python/cpython/issues/gh-123',
+    'github.com/python/cpython/issues/1234?param=1',
+    'https://github.com/python/cpython/issues',
+    'https://github.com/python/cpython/issues/',
+    'https://github.com/python/cpython/issues/abc',
+    'https://github.com/python/cpython/issues/gh-abc',
+    'https://github.com/python/cpython/issues/gh-123',
+    'https://github.com/python/cpython/issues/1234?param=1',
+))
+def test_invalid_issue_number(issue):
+    error_message = re.escape(f'Invalid GitHub issue: {issue}')
+    with pytest.raises(SystemExit, match=error_message):
+        blurb._blurb_template_text(issue=issue)
+
+
+@pytest.mark.parametrize('invalid', (
+    'gh-issue: ',
+    'gh-issue: 1',
+    'gh-issue',
+))
+def test_malformed_gh_issue_line(invalid, monkeypatch):
+    template = blurb.template.replace('.. gh-issue:', invalid)
+    error_message = re.escape("Can't find gh-issue line in the template!")
+    with monkeypatch.context() as cm:
+        cm.setattr(blurb, 'template', template)
+        with pytest.raises(SystemExit, match=error_message):
+            blurb._blurb_template_text(issue='1234')