gh-101503: Add public names for argparse's group and subparsers-action types

add_subparsers(), add_argument_group(), and add_mutually_exclusive_group()
return instances of _SubParsersAction, _ArgumentGroup, and
_MutuallyExclusiveGroup respectively -- underscore-prefixed, undocumented
classes with no supported way to reference them for type hints or
isinstance checks, even though the documentation itself was already
forced to describe _SubParsersAction.add_parser() under its private
name.

Rename these to SubParsersAction, ArgumentGroup, and
MutuallyExclusiveGroup, add them to __all__, and document them. The
old private names are kept as aliases for backwards compatibility with
existing code that imported them directly.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Author: NAVEENKUMARKR777

Doc/library/argparse.rst

@@ -211,7 +211,7 @@ your usage messages.
 When a custom usage message is specified for the main parser, you may also want to
 consider passing  the ``prog`` argument to :meth:`~ArgumentParser.add_subparsers`
 or the ``prog`` and the ``usage`` arguments to
-:meth:`~_SubParsersAction.add_parser`, to ensure consistent command prefixes and
+:meth:`~SubParsersAction.add_parser`, to ensure consistent command prefixes and
 usage information across subparsers.
 
 
@@ -1733,10 +1733,11 @@ Subcommands
    different functions which require different kinds of command-line arguments.
    :class:`ArgumentParser` supports the creation of such subcommands with the
    :meth:`!add_subparsers` method.  The :meth:`!add_subparsers` method is normally
-   called with no arguments and returns a special action object.  This object
-   has a single method, :meth:`~_SubParsersAction.add_parser`, which takes a
-   command name and any :class:`!ArgumentParser` constructor arguments, and
-   returns an :class:`!ArgumentParser` object that can be modified as usual.
+   called with no arguments and returns a :class:`SubParsersAction` object.
+   This object has a single method, :meth:`~SubParsersAction.add_parser`, which
+   takes a command name and any :class:`!ArgumentParser` constructor arguments,
+   and returns an :class:`!ArgumentParser` object that can be modified as
+   usual.
 
    Description of parameters:
 
@@ -1805,7 +1806,7 @@ Subcommands
    for that particular parser will be printed.  The help message will not
    include parent parser or sibling parser messages.  (A help message for each
    subparser command, however, can be given by supplying the ``help=`` argument
-   to :meth:`~_SubParsersAction.add_parser` as above.)
+   to :meth:`~SubParsersAction.add_parser` as above.)
 
    ::
 
@@ -1919,7 +1920,15 @@ Subcommands
       the main parser.
 
 
-.. method:: _SubParsersAction.add_parser(name, *, help=None, aliases=None, \
+.. class:: SubParsersAction
+
+   The type of the object returned by :meth:`~ArgumentParser.add_subparsers`.
+
+   .. versionadded:: 3.16
+      Previously this class was only available under the private,
+      undocumented name ``argparse._SubParsersAction``.
+
+.. method:: SubParsersAction.add_parser(name, *, help=None, aliases=None, \
                                          deprecated=False, **kwargs)
 
    Create and return a new :class:`ArgumentParser` object for the
@@ -2019,8 +2028,8 @@ Argument groups
        bar    bar help
        --foo FOO  foo help
 
-   The :meth:`add_argument_group` method returns an argument group object which
-   has an :meth:`~ArgumentParser.add_argument` method just like a regular
+   The :meth:`add_argument_group` method returns an :class:`ArgumentGroup`
+   object which has an :meth:`~ArgumentParser.add_argument` method just like a regular
    :class:`ArgumentParser`.  When an argument is added to the group, the parser
    treats it just like a normal argument, but displays the argument in a
    separate group for help messages.  The :meth:`!add_argument_group` method
@@ -2066,6 +2075,16 @@ Argument groups
       is now deprecated.
 
 
+.. class:: ArgumentGroup
+
+   The type of the object returned by
+   :meth:`~ArgumentParser.add_argument_group`.
+
+   .. versionadded:: 3.16
+      Previously this class was only available under the private,
+      undocumented name ``argparse._ArgumentGroup``.
+
+
 Mutual exclusion
 ^^^^^^^^^^^^^^^^
 
@@ -2129,6 +2148,17 @@ Mutual exclusion
       exposed through inheritance.
 
 
+.. class:: MutuallyExclusiveGroup
+
+   The type of the object returned by
+   :meth:`~ArgumentParser.add_mutually_exclusive_group`. A subclass of
+   :class:`ArgumentGroup`.
+
+   .. versionadded:: 3.16
+      Previously this class was only available under the private,
+      undocumented name ``argparse._MutuallyExclusiveGroup``.
+
+
 Parser defaults
 ^^^^^^^^^^^^^^^
 

Lib/argparse.py

@@ -77,6 +77,9 @@
     'MetavarTypeHelpFormatter',
     'Namespace',
     'Action',
+    'ArgumentGroup',
+    'MutuallyExclusiveGroup',
+    'SubParsersAction',
     'ONE_OR_MORE',
     'OPTIONAL',
     'PARSER',
@@ -1337,15 +1340,15 @@ def __call__(self, parser, namespace, values, option_string=None):
         parser.exit()
 
 
-class _SubParsersAction(Action):
+class SubParsersAction(Action):
 
     class _ChoicesPseudoAction(Action):
 
         def __init__(self, name, aliases, help):
             metavar = dest = name
             if aliases:
                 metavar += ' (%s)' % ', '.join(aliases)
-            sup = super(_SubParsersAction._ChoicesPseudoAction, self)
+            sup = super(SubParsersAction._ChoicesPseudoAction, self)
             sup.__init__(option_strings=[], dest=dest, help=help,
                          metavar=metavar)
 
@@ -1365,7 +1368,7 @@ def __init__(self,
         self._deprecated = set()
         self._color = True
 
-        super(_SubParsersAction, self).__init__(
+        super(SubParsersAction, self).__init__(
             option_strings=option_strings,
             dest=dest,
             nargs=PARSER,
@@ -1455,6 +1458,10 @@ def __call__(self, parser, namespace, values, option_string=None):
                 setattr(namespace, _UNRECOGNIZED_ARGS_ATTR, [])
             getattr(namespace, _UNRECOGNIZED_ARGS_ATTR).extend(arg_strings)
 
+# Deprecated alias, kept for backwards compatibility with code that
+# imported this class under its old, undocumented private name.
+_SubParsersAction = SubParsersAction
+
 class _ExtendAction(_AppendAction):
     def __call__(self, parser, namespace, values, option_string=None):
         items = getattr(namespace, self.dest, None)
@@ -1580,7 +1587,7 @@ def __init__(self,
         self.register('action', 'count', _CountAction)
         self.register('action', 'help', _HelpAction)
         self.register('action', 'version', _VersionAction)
-        self.register('action', 'parsers', _SubParsersAction)
+        self.register('action', 'parsers', SubParsersAction)
         self.register('action', 'extend', _ExtendAction)
 
         # raise an exception if the conflict handler is invalid
@@ -1699,12 +1706,12 @@ def add_argument(self, *args, **kwargs):
         return self._add_action(action)
 
     def add_argument_group(self, *args, **kwargs):
-        group = _ArgumentGroup(self, *args, **kwargs)
+        group = ArgumentGroup(self, *args, **kwargs)
         self._action_groups.append(group)
         return group
 
     def add_mutually_exclusive_group(self, **kwargs):
-        group = _MutuallyExclusiveGroup(self, **kwargs)
+        group = MutuallyExclusiveGroup(self, **kwargs)
         self._mutually_exclusive_groups.append(group)
         return group
 
@@ -1892,7 +1899,7 @@ def _check_help(self, action):
                 raise ValueError('badly formed help string') from exc
 
 
-class _ArgumentGroup(_ActionsContainer):
+class ArgumentGroup(_ActionsContainer):
 
     def __init__(self, container, title=None, description=None, **kwargs):
         if 'prefix_chars' in kwargs:
@@ -1907,7 +1914,7 @@ def __init__(self, container, title=None, description=None, **kwargs):
         update('conflict_handler', container.conflict_handler)
         update('prefix_chars', container.prefix_chars)
         update('argument_default', container.argument_default)
-        super_init = super(_ArgumentGroup, self).__init__
+        super_init = super(ArgumentGroup, self).__init__
         super_init(description=description, **kwargs)
 
         # group attributes
@@ -1924,21 +1931,25 @@ def __init__(self, container, title=None, description=None, **kwargs):
         self._mutually_exclusive_groups = container._mutually_exclusive_groups
 
     def _add_action(self, action):
-        action = super(_ArgumentGroup, self)._add_action(action)
+        action = super(ArgumentGroup, self)._add_action(action)
         self._group_actions.append(action)
         return action
 
     def _remove_action(self, action):
-        super(_ArgumentGroup, self)._remove_action(action)
+        super(ArgumentGroup, self)._remove_action(action)
         self._group_actions.remove(action)
 
     def add_argument_group(self, *args, **kwargs):
         raise ValueError('argument groups cannot be nested')
 
-class _MutuallyExclusiveGroup(_ArgumentGroup):
+# Deprecated alias, kept for backwards compatibility with code that
+# imported this class under its old, undocumented private name.
+_ArgumentGroup = ArgumentGroup
+
+class MutuallyExclusiveGroup(ArgumentGroup):
 
     def __init__(self, container, required=False):
-        super(_MutuallyExclusiveGroup, self).__init__(container)
+        super(MutuallyExclusiveGroup, self).__init__(container)
         self.required = required
         self._container = container
 
@@ -1957,6 +1968,10 @@ def _remove_action(self, action):
     def add_mutually_exclusive_group(self, **kwargs):
         raise ValueError('mutually exclusive groups cannot be nested')
 
+# Deprecated alias, kept for backwards compatibility with code that
+# imported this class under its old, undocumented private name.
+_MutuallyExclusiveGroup = MutuallyExclusiveGroup
+
 def _prog_name(prog=None):
     if prog is not None:
         return prog

Lib/test/test_argparse.py

@@ -3175,6 +3175,44 @@ def test_alias_help(self):
                 3                   3 help
             """))
 
+class TestPublicClasses(TestCase):
+    """Test that public names are used for objects returned by parser
+    methods that used to return only private, undocumented types
+    (see gh-101503)."""
+
+    def test_add_subparsers_return_type(self):
+        parser = argparse.ArgumentParser()
+        subparsers = parser.add_subparsers()
+        self.assertIsInstance(subparsers, argparse.SubParsersAction)
+        subparser = subparsers.add_parser('cmd')
+        self.assertIsInstance(subparser, argparse.ArgumentParser)
+
+    def test_add_argument_group_return_type(self):
+        parser = argparse.ArgumentParser()
+        group = parser.add_argument_group('title')
+        self.assertIsInstance(group, argparse.ArgumentGroup)
+
+    def test_add_mutually_exclusive_group_return_type(self):
+        parser = argparse.ArgumentParser()
+        group = parser.add_mutually_exclusive_group()
+        self.assertIsInstance(group, argparse.MutuallyExclusiveGroup)
+        self.assertIsInstance(group, argparse.ArgumentGroup)
+
+    def test_old_private_names_are_aliases(self):
+        # The old, undocumented private names are kept as aliases for
+        # backwards compatibility with code that imported them directly.
+        self.assertIs(argparse._SubParsersAction, argparse.SubParsersAction)
+        self.assertIs(argparse._ArgumentGroup, argparse.ArgumentGroup)
+        self.assertIs(argparse._MutuallyExclusiveGroup,
+                      argparse.MutuallyExclusiveGroup)
+
+    def test_public_names_exported(self):
+        for name in ('SubParsersAction', 'ArgumentGroup',
+                     'MutuallyExclusiveGroup'):
+            with self.subTest(name=name):
+                self.assertIn(name, argparse.__all__)
+
+
 # ============
 # Groups tests
 # ============

Misc/NEWS.d/next/Library/2026-09-05-18-05-00.gh-issue-101503.Tz8Xk2.rst

@@ -0,0 +1,9 @@
+Add public names :class:`argparse.SubParsersAction`,
+:class:`argparse.ArgumentGroup`, and :class:`argparse.MutuallyExclusiveGroup`
+for the previously private, undocumented types returned by
+:meth:`~argparse.ArgumentParser.add_subparsers`,
+:meth:`~argparse.ArgumentParser.add_argument_group`, and
+:meth:`~argparse.ArgumentParser.add_mutually_exclusive_group` respectively,
+so that code (and type checkers) can reference them without relying on the
+old ``_SubParsersAction``, ``_ArgumentGroup``, and ``_MutuallyExclusiveGroup``
+names, which are kept as aliases for backwards compatibility.