bpo-22047: [argparse] deprecate nested argument groups and mutually exclusive groups (GH-30098)

4 files changed, 45 insertions, 2 deletions

diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst
index 2edf84e..80c382a 100644
--- a/Doc/library/argparse.rst
+++ b/Doc/library/argparse.rst
@@ -1898,6 +1898,12 @@ Argument groups
    Note that any arguments not in your user-defined groups will end up back
    in the usual "positional arguments" and "optional arguments" sections.
 
+   .. versionchanged:: 3.11
+    Calling :meth:`add_argument_group` on an argument group is deprecated.
+    This feature was never supported and does not always work correctly.
+    The function exists on the API by accident through inheritance and
+    will be removed in the future.
+
 
 Mutual exclusion
 ^^^^^^^^^^^^^^^^
@@ -1936,6 +1942,12 @@ Mutual exclusion
    *title* and *description* arguments of
    :meth:`~ArgumentParser.add_argument_group`.
 
+   .. versionchanged:: 3.11
+    Calling :meth:`add_argument_group` or :meth:`add_mutually_exclusive_group`
+    on a mutually exclusive group is deprecated. These features were never
+    supported and do not always work correctly. The functions exist on the
+    API by accident through inheritance and will be removed in the future.
+
 
 Parser defaults
 ^^^^^^^^^^^^^^^
diff --git a/Lib/argparse.py b/Lib/argparse.py
index 8a81801..de95eed 100644
--- a/Lib/argparse.py
+++ b/Lib/argparse.py
@@ -89,6 +89,8 @@ import os as _os
 import re as _re
 import sys as _sys
 
+import warnings
+
 from gettext import gettext as _, ngettext
 
 SUPPRESS = '==SUPPRESS=='
@@ -1648,6 +1650,14 @@ class _ArgumentGroup(_ActionsContainer):
         super(_ArgumentGroup, self)._remove_action(action)
         self._group_actions.remove(action)
 
+    def add_argument_group(self, *args, **kwargs):
+        warnings.warn(
+            "Nesting argument groups is deprecated.",
+            category=DeprecationWarning,
+            stacklevel=2
+        )
+        return super().add_argument_group(*args, **kwargs)
+
 
 class _MutuallyExclusiveGroup(_ArgumentGroup):
 
@@ -1668,6 +1678,14 @@ class _MutuallyExclusiveGroup(_ArgumentGroup):
         self._container._remove_action(action)
         self._group_actions.remove(action)
 
+    def add_mutually_exclusive_group(self, *args, **kwargs):
+        warnings.warn(
+            "Nesting mutually exclusive groups is deprecated.",
+            category=DeprecationWarning,
+            stacklevel=2
+        )
+        return super().add_mutually_exclusive_group(*args, **kwargs)
+
 
 class ArgumentParser(_AttributeHolder, _ActionsContainer):
     """Object for parsing command line strings into Python objects.
diff --git a/Lib/test/test_argparse.py b/Lib/test/test_argparse.py
index eb37d4d..4c23610 100644
--- a/Lib/test/test_argparse.py
+++ b/Lib/test/test_argparse.py
@@ -9,6 +9,7 @@ import textwrap
 import tempfile
 import unittest
 import argparse
+import warnings
 
 from io import StringIO
 
@@ -2973,15 +2974,24 @@ class TestMutuallyExclusiveOptionalsAndPositionalsMixed(MEMixin, TestCase):
 
 class TestMutuallyExclusiveNested(MEMixin, TestCase):
 
+    # Nesting mutually exclusive groups is an undocumented feature
+    # that came about by accident through inheritance and has been
+    # the source of many bugs. It is deprecated and this test should
+    # eventually be removed along with it.
+
     def get_parser(self, required):
         parser = ErrorRaisingArgumentParser(prog='PROG')
         group = parser.add_mutually_exclusive_group(required=required)
         group.add_argument('-a')
         group.add_argument('-b')
-        group2 = group.add_mutually_exclusive_group(required=required)
+        with warnings.catch_warnings():
+            warnings.simplefilter('ignore', DeprecationWarning)
+            group2 = group.add_mutually_exclusive_group(required=required)
         group2.add_argument('-c')
         group2.add_argument('-d')
-        group3 = group2.add_mutually_exclusive_group(required=required)
+        with warnings.catch_warnings():
+            warnings.simplefilter('ignore', DeprecationWarning)
+            group3 = group2.add_mutually_exclusive_group(required=required)
         group3.add_argument('-e')
         group3.add_argument('-f')
         return parser
diff --git a/Misc/NEWS.d/next/Library/2021-12-15-19-24-54.bpo-22047.gBV4vT.rst b/Misc/NEWS.d/next/Library/2021-12-15-19-24-54.bpo-22047.gBV4vT.rst
new file mode 100644
index 0000000..a381ad8
--- /dev/null
+++ b/Misc/NEWS.d/next/Library/2021-12-15-19-24-54.bpo-22047.gBV4vT.rst
@@ -0,0 +1,3 @@
+Calling :meth:`add_argument_group` on an argument group is deprecated. Calling :meth:`add_argument_group` or :meth:`add_mutually_exclusive_group` on a mutually exclusive group is deprecated.

+

+These features were never supported and do not always work correctly. The functions exist on the API by accident through inheritance and will be removed in the future.
\ No newline at end of file