Rietveld Code Review Tool
Help | Bug tracker | Discussion group | Source code | Sign in
(32325)

Delta Between Two Patch Sets: Doc/library/argparse.rst

Issue 9253: argparse: optional subparsers
Left Patch Set: Created 7 years, 8 months ago
Right Patch Set: Created 6 years, 5 months ago
Left:
Right:
Use n/p to move between diff chunks; N/P to move between comments. Please Sign in to add in-line comments.
Jump to:
Right: Side by side diff | Download
« no previous file with change/comment | « no previous file | Lib/argparse.py » ('j') | no next file with change/comment »
Toggle Intra-line Diffs ('i') | Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
LEFTRIGHT
(no file at all)
1 :mod:`argparse` --- Parser for command-line options, arguments and sub-commands 1 :mod:`argparse` --- Parser for command-line options, arguments and sub-commands
2 =============================================================================== 2 ===============================================================================
3 3
4 .. module:: argparse 4 .. module:: argparse
5 :synopsis: Command-line option and argument parsing library. 5 :synopsis: Command-line option and argument parsing library.
6 .. moduleauthor:: Steven Bethard <steven.bethard@gmail.com> 6 .. moduleauthor:: Steven Bethard <steven.bethard@gmail.com>
7 .. sectionauthor:: Steven Bethard <steven.bethard@gmail.com> 7 .. sectionauthor:: Steven Bethard <steven.bethard@gmail.com>
8 8
9 .. versionadded:: 3.2 9 .. versionadded:: 3.2
10 10
(...skipping 1434 matching lines...) Expand 10 before | Expand all | Expand 10 after
1445 >>> c.foo 1445 >>> c.foo
1446 'BAR' 1446 'BAR'
1447 1447
1448 1448
1449 Other utilities 1449 Other utilities
1450 --------------- 1450 ---------------
1451 1451
1452 Sub-commands 1452 Sub-commands
1453 ^^^^^^^^^^^^ 1453 ^^^^^^^^^^^^
1454 1454
1455 .. method:: ArgumentParser.add_subparsers() 1455 .. method:: ArgumentParser.add_subparsers([title], [description], [prog], [dest] , \
1456 [required], [help], [metavar])
1457
1458 Create an action object which parses a command-line argument as a choice
1459 from a set of parser sub-commands. The keyword arguments include a subset of
1460 those accepted by :meth:`ArgumentParser.add_argument`.
1461
1462 * title_ - If defined, display the sub-command choices as an argument group.
1463
1464 * `description` - Description of the argument group.
1465
1466 * `prog` - Usage prefix in the subparser help output (default uses the parser prog_).
1467
1468 * dest_ - :class:`Namespace` attribute to hold the sub-command name (default ``argparse.SUPPRESS``).
1469
1470 * required_ - Whether or not the command-line option may be omitted (default ``True``).
1471
1472 * help_ - A brief description of subparser group.
1473
1474 * metavar_ - A name for the sub-command in the usage message.
1456 1475
1457 Many programs split up their functionality into a number of sub-commands, 1476 Many programs split up their functionality into a number of sub-commands,
1458 for example, the ``svn`` program can invoke sub-commands like ``svn 1477 for example, the ``svn`` program can invoke sub-commands like ``svn
1459 checkout``, ``svn update``, and ``svn commit``. Splitting up functionality 1478 checkout``, ``svn update``, and ``svn commit``. Splitting up functionality
1460 this way can be a particularly good idea when a program performs several 1479 this way can be a particularly good idea when a program performs several
1461 different functions which require different kinds of command-line arguments. 1480 different functions which require different kinds of command-line arguments.
1462 :class:`ArgumentParser` supports the creation of such sub-commands with the 1481 :class:`ArgumentParser` supports the creation of such sub-commands with the
1463 :meth:`add_subparsers` method. The :meth:`add_subparsers` method is normally 1482 :meth:`add_subparsers` method. The :meth:`add_subparsers` method is normally
1464 called with no arguments and returns a special action object. This object 1483 called with no arguments and returns a special action object. This object
1465 has a single method, :meth:`~ArgumentParser.add_parser`, which takes a 1484 has a single method, :meth:`~ArgumentParser.add_parser`, which takes a
(...skipping 19 matching lines...) Expand all
1485 >>> parser.parse_args(['a', '12']) 1504 >>> parser.parse_args(['a', '12'])
1486 Namespace(bar=12, foo=False) 1505 Namespace(bar=12, foo=False)
1487 >>> parser.parse_args(['--foo', 'b', '--baz', 'Z']) 1506 >>> parser.parse_args(['--foo', 'b', '--baz', 'Z'])
1488 Namespace(baz='Z', foo=True) 1507 Namespace(baz='Z', foo=True)
1489 1508
1490 Note that the object returned by :meth:`parse_args` will only contain 1509 Note that the object returned by :meth:`parse_args` will only contain
1491 attributes for the main parser and the subparser that was selected by the 1510 attributes for the main parser and the subparser that was selected by the
1492 command line (and not any other subparsers). So in the example above, when 1511 command line (and not any other subparsers). So in the example above, when
1493 the ``a`` command is specified, only the ``foo`` and ``bar`` attributes are 1512 the ``a`` command is specified, only the ``foo`` and ``bar`` attributes are
1494 present, and when the ``b`` command is specified, only the ``foo`` and 1513 present, and when the ``b`` command is specified, only the ``foo`` and
1495 ``baz`` attributes are present. 1514 ``baz`` attributes are present. In this example, all argument strings after
1515 subparser name ('a' or 'b') are parsed by that subparser.
1496 1516
1497 Similarly, when a help message is requested from a subparser, only the help 1517 Similarly, when a help message is requested from a subparser, only the help
1498 for that particular parser will be printed. The help message will not 1518 for that particular parser will be printed. The help message will not
1499 include parent parser or sibling parser messages. (A help message for each 1519 include parent parser or sibling parser messages. (A help message for each
1500 subparser command, however, can be given by supplying the ``help=`` argument 1520 subparser command, however, can be given by supplying the ``help=`` argument
1501 to :meth:`add_parser` as above.) 1521 to :meth:`add_parser` as above.)
1502 1522
1503 :: 1523 ::
1504 1524
1505 >>> parser.parse_args(['--help']) 1525 >>> parser.parse_args(['--help'])
(...skipping 16 matching lines...) Expand all
1522 1542
1523 optional arguments: 1543 optional arguments:
1524 -h, --help show this help message and exit 1544 -h, --help show this help message and exit
1525 1545
1526 >>> parser.parse_args(['b', '--help']) 1546 >>> parser.parse_args(['b', '--help'])
1527 usage: PROG b [-h] [--baz {X,Y,Z}] 1547 usage: PROG b [-h] [--baz {X,Y,Z}]
1528 1548
1529 optional arguments: 1549 optional arguments:
1530 -h, --help show this help message and exit 1550 -h, --help show this help message and exit
1531 --baz {X,Y,Z} baz help 1551 --baz {X,Y,Z} baz help
1552
1553 .. _title:
1532 1554
1533 The :meth:`add_subparsers` method also supports ``title`` and ``description`` 1555 The :meth:`add_subparsers` method also supports ``title`` and ``description``
1534 keyword arguments. When either is present, the subparser's commands will 1556 keyword arguments. When either is present, the subparser's commands will
1535 appear in their own group in the help output. For example:: 1557 appear in their own group in the help output. For example::
1536 1558
1537 >>> parser = argparse.ArgumentParser() 1559 >>> parser = argparse.ArgumentParser()
1538 >>> subparsers = parser.add_subparsers(title='subcommands', 1560 >>> subparsers = parser.add_subparsers(title='subcommands',
1539 ... description='valid subcommands', 1561 ... description='valid subcommands',
1540 ... help='additional help') 1562 ... help='additional help')
1541 >>> subparsers.add_parser('foo') 1563 >>> subparsers.add_parser('foo')
(...skipping 354 matching lines...) Expand 10 before | Expand all | Expand 10 after
1896 * Replace :class:`optparse.Values` with :class:`Namespace` and 1918 * Replace :class:`optparse.Values` with :class:`Namespace` and
1897 :exc:`optparse.OptionError` and :exc:`optparse.OptionValueError` with 1919 :exc:`optparse.OptionError` and :exc:`optparse.OptionValueError` with
1898 :exc:`ArgumentError`. 1920 :exc:`ArgumentError`.
1899 1921
1900 * Replace strings with implicit arguments such as ``%default`` or ``%prog`` with 1922 * Replace strings with implicit arguments such as ``%default`` or ``%prog`` with
1901 the standard Python syntax to use dictionaries to format strings, that is, 1923 the standard Python syntax to use dictionaries to format strings, that is,
1902 ``%(default)s`` and ``%(prog)s``. 1924 ``%(default)s`` and ``%(prog)s``.
1903 1925
1904 * Replace the OptionParser constructor ``version`` argument with a call to 1926 * Replace the OptionParser constructor ``version`` argument with a call to
1905 ``parser.add_argument('--version', action='version', version='<the version>')` ` 1927 ``parser.add_argument('--version', action='version', version='<the version>')` `
LEFTRIGHT
« no previous file | Lib/argparse.py » ('j') | Toggle Intra-line Diffs ('i') | Expand Comments ('e') | Collapse Comments ('c') | Toggle Comments ('s')

RSS Feeds Recent Issues | This issue
This is Rietveld 894c83f36cb7+