Allow subparsers to take title= and description= parameters.

3 files changed, 60 insertions, 5 deletions

diff --git a/argparse.py b/argparse.py
index 9b99712..bf3f277 100644
--- a/argparse.py
+++ b/argparse.py
@@ -1498,11 +1498,10 @@ class ArgumentParser(_AttributeHolder, _ActionsContainer):
         self.fromfile_prefix_chars = fromfile_prefix_chars

         self.add_help = add_help

 

-        self._has_subparsers = False

-

         add_group = self.add_argument_group

         self._positionals = add_group(_('positional arguments'))

         self._optionals = add_group(_('optional arguments'))

+        self._subparsers = None

 

         # register types

         def identity(string):

@@ -1549,12 +1548,19 @@ class ArgumentParser(_AttributeHolder, _ActionsContainer):
     # Optional/Positional adding methods

     # ==================================

     def add_subparsers(self, **kwargs):

-        if self._has_subparsers:

+        if self._subparsers is not None:

             self.error(_('cannot have multiple subparser arguments'))

 

         # add the parser class to the arguments if it's not present

         kwargs.setdefault('parser_class', type(self))

 

+        if 'title' in kwargs or 'description' in kwargs:

+            title = _(kwargs.pop('title', 'subcommands'))

+            description = _(kwargs.pop('description', None))

+            self._subparsers = self.add_argument_group(title, description)

+        else:

+            self._subparsers = self._positionals

+

         # prog defaults to the usage message of this parser, skipping

         # optional arguments and with no "usage:" prefix

         if kwargs.get('prog') is None:

@@ -1567,8 +1573,7 @@ class ArgumentParser(_AttributeHolder, _ActionsContainer):
         # create the parsers action and add it to the positionals list

         parsers_class = self._pop_action_class(kwargs, 'parsers')

         action = parsers_class(option_strings=[], **kwargs)

-        self._positionals._add_action(action)

-        self._has_subparsers = True

+        self._subparsers._add_action(action)

 

         # return the created parsers action

         return action

diff --git a/doc/source/other-methods.rst b/doc/source/other-methods.rst
index 5934554..7d9f33e 100644
--- a/doc/source/other-methods.rst
+++ b/doc/source/other-methods.rst
@@ -129,7 +129,27 @@ Sub-commands
      optional arguments:

        -h, --help     show this help message and exit

        --baz {X,Y,Z}  baz help

+

+   The :meth:`add_subparsers` method also supports ``title`` and ``description`` keyword arguments.  When either is present, the subparser's commands will appear in their own group in the help output.  For example::

    

+     >>> parser = argparse.ArgumentParser()

+     >>> subparsers = parser.add_subparsers(title='subcommands',

+     ...                                    description='valid subcommands',

+     ...                                    help='additional help')

+     >>> subparsers.add_parser('foo')

+     >>> subparsers.add_parser('bar')

+     >>> parser.parse_args(['-h'])

+     usage:  [-h] {foo,bar} ...

+     

+     optional arguments:

+       -h, --help  show this help message and exit

+     

+     subcommands:

+       valid subcommands

+     

+       {foo,bar}   additional help

+     

+

    One particularly effective way of handling sub-commands is to combine the use of the :meth:`add_subparsers` method with calls to :meth:`set_defaults` so that each subparser knows which Python function it should execute.  For example::

    

      >>> # sub-command functions

diff --git a/test/test_argparse.py b/test/test_argparse.py
index bd5a854..011b9b6 100644
--- a/test/test_argparse.py
+++ b/test/test_argparse.py
@@ -1654,6 +1654,36 @@ class TestAddSubparsers(TestCase):
               --foo       foo help

             '''))

 

+    def test_subparser_title_help(self):

+        parser = ErrorRaisingArgumentParser(prog='PROG',

+                                            description='main description')

+        parser.add_argument('--foo', action='store_true', help='foo help')

+        parser.add_argument('bar', help='bar help')

+        subparsers = parser.add_subparsers(title='subcommands',

+                                           description='command help',

+                                           help='additional text')

+        parser1 = subparsers.add_parser('1')

+        parser2 = subparsers.add_parser('2')

+        self.assertEqual(parser.format_usage(),

+                         'usage: PROG [-h] [--foo] bar {1,2} ...\n')

+        self.assertEqual(parser.format_help(), textwrap.dedent('''\

+            usage: PROG [-h] [--foo] bar {1,2} ...

+

+            main description

+

+            positional arguments:

+              bar         bar help

+

+            optional arguments:

+              -h, --help  show this help message and exit

+              --foo       foo help

+

+            subcommands:

+              command help

+

+              {1,2}       additional text

+            '''))

+

     def _test_subparser_help(self, args_str, expected_help):

         try:

             self.parser.parse_args(args_str.split())