gh-125542: Deprecate prefix_chars in ArgumentParser.add_argument_group

Doc/library/argparse.rst

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

Doc/whatsnew/3.14.rst

@@ -420,6 +420,11 @@
 Deprecated
 ==========
 
+* :mod:`argparse`:
+  Passing *prefix_chars* to :meth:`argparse.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 @@ def _check_help(self, action):
 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

@@ -2816,6 +2816,36 @@ def test_interleaved_groups(self):
         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.assertWarnsRegex(DeprecationWarning, msg):
+            parser.add_argument_group(prefix_chars='-+')
+
+    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.assertWarnsRegex(DeprecationWarning, msg):
+            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'))
+
 # ===================
 # Parent parser tests
 # ===================

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

@@ -0,0 +1 @@
+Deprecate passing prefix_chars_ parameter to :meth:`ArgumentParser.add_argument_group`.