gh-125542: Deprecate prefix_chars in ArgumentParser.add_argument_group() (GH-125563)

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
+* :mod:`argparse`:
-  groups are deprecated.
+
+  * 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

@@ -1894,6 +1894,10 @@ Argument groups
     The function exists on the API by accident through inheritance and
     will be removed in the future.
 
+   .. deprecated:: 3.14
+    Passing prefix_chars_ to :meth:`add_argument_group`
+    is now deprecated.
+
 
 Mutual exclusion
 ^^^^^^^^^^^^^^^^

Doc/whatsnew/3.14.rst

@@ -428,6 +428,12 @@ asyncio
 Deprecated
 ==========
 
+* :mod:`argparse`:
+  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`:
   :func:`!asyncio.iscoroutinefunction` is deprecated
   and will be removed in Python 3.16,

Lib/argparse.py

@@ -1662,6 +1662,14 @@ class _ActionsContainer(object):
 class _ArgumentGroup(_ActionsContainer):
 
     def __init__(self, container, title=None, description=None, **kwargs):
+        if 'prefix_chars' in kwargs:
+            import warnings
+            depr_msg = (
+                "The use of the undocumented 'prefix_chars' parameter in "
+                "ArgumentParser.add_argument_group() is deprecated."
+            )
+            warnings.warn(depr_msg, DeprecationWarning, stacklevel=3)
+
         # add any missing keyword arguments by checking the container
         update = kwargs.setdefault
         update('conflict_handler', container.conflict_handler)

Lib/test/test_argparse.py

@@ -2893,6 +2893,31 @@ class TestPositionalsGroups(TestCase):
         result = parser.parse_args('1 2 3 4'.split())
         self.assertEqual(expected, result)
 
+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."
+        )
+        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."
+        )
+        with self.assertWarns(DeprecationWarning) as cm:
+            parser.add_argument_group(prefix_chars='-')
+        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

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