gh-125542: Deprecate prefix_chars in ArgumentParser.add_argument_group

Doc/deprecations/pending-removal-in-future.rst

@@ -4,8 +4,13 @@ Pending removal in future versions
 The following APIs will be removed in the future,
 although there is currently no date scheduled for their removal.
 
-* :mod:`argparse`: Nesting argument groups and nesting mutually exclusive
-  groups are deprecated.
+* :mod:`argparse`:
+
+  * Nesting argument groups and nesting mutually exclusive
+    groups are deprecated.
+  * Passing the undocumented keyword argument *prefix_chars* to
+    :meth:`~argparse.ArgumentParser.add_argument_group` is now
+    deprecated.
 
 * :mod:`array`'s ``'u'`` format code (:gh:`57281`)
 

Doc/library/argparse.rst

@@ -1868,7 +1868,7 @@ Argument groups
     The function exists on the API by accident through inheritance and
     will be removed in the future.
 
-   .. versionchanged:: 3.14
+   .. deprecated:: 3.14
     Passing prefix_chars_ to :meth:`add_argument_group`
     is now deprecated.
 

Doc/whatsnew/3.14.rst

@@ -421,8 +421,9 @@ Deprecated
 ==========
 
 * :mod:`argparse`:
-  Passing *prefix_chars* to :func:`argparse.add_argument_group`
-  is now deprecated.
+  Passing the undocumented keyword argument *prefix_chars* to
+  :meth:`~argparse.ArgumentParser.add_argument_group` is now
+  deprecated.
   (Contributed by Savannah Ostrowski in :gh:`125563`.)
 
 * :mod:`asyncio`:

Lib/argparse.py

@@ -1666,7 +1666,7 @@ def __init__(self, container, title=None, description=None, **kwargs):
             import warnings
             depr_msg = (
                 "The use of the undocumented 'prefix_chars' parameter in "
-                "ArgumentParser.add_argument_group is deprecated."
+                "ArgumentParser.add_argument_group() is deprecated."
             )
             warnings.warn(depr_msg, DeprecationWarning, stacklevel=3)
 

Lib/test/test_argparse.py

@@ -2819,32 +2819,27 @@ def test_interleaved_groups(self):
 class TestGroupConstructor(TestCase):
     def test_group_prefix_chars(self):
         parser = ErrorRaisingArgumentParser()
-
         msg = (
             "The use of the undocumented 'prefix_chars' parameter in "
-            "ArgumentParser.add_argument_group is deprecated."
+            "ArgumentParser.add_argument_group() is deprecated."
         )
-        with self.assertWarnsRegex(DeprecationWarning, msg):
+        with self.assertWarns(DeprecationWarning) as cm:
             parser.add_argument_group(prefix_chars='-+')
+        self.assertEqual(msg, str(cm.warning))
+        self.assertEqual(cm.filename, __file__)
 
     def test_group_prefix_chars_default(self):
         # "default" isn't quite the right word here, but it's the same as
         # the parser's default prefix so it's a good test
         parser = ErrorRaisingArgumentParser()
-
         msg = (
             "The use of the undocumented 'prefix_chars' parameter in "
-            "ArgumentParser.add_argument_group is deprecated."
+            "ArgumentParser.add_argument_group() is deprecated."
         )
-
-        with self.assertWarnsRegex(DeprecationWarning, msg):
+        with self.assertWarns(DeprecationWarning) as cm:
             parser.add_argument_group(prefix_chars='-')
-
-    def test_group_without_prefix_chars(self):
-        parser = ErrorRaisingArgumentParser()
-        group = parser.add_argument_group()
-        group.add_argument('--foo')
-        self.assertEqual(parser.parse_args(['--foo', 'bar']), NS(foo='bar'))
+        self.assertEqual(msg, str(cm.warning))
+        self.assertEqual(cm.filename, __file__)
 
 # ===================
 # Parent parser tests

Misc/NEWS.d/next/Library/2024-10-16-04-50-53.gh-issue-125542.vZJ-Ns.rst

@@ -1 +1,2 @@
-Deprecate passing prefix_chars_ parameter to :meth:`ArgumentParser.add_argument_group`.
+Deprecate passing keyword-only ``prefix_chars`` argument to
+:meth:`argparse.ArgumentParser.add_argument_group`.