The usage parameter of argparse.ArgumentParser no longer
affects the default value of the prog parameter in subparsers.
Previously the full custom usage of the main parser was used as
the prog prefix in subparsers.
* Only error messages for ArgumentError and ArgumentTypeError are now
translated.
* ArgumentError is now only used for command line errors, not for logical
errors in the program.
* TypeError is now raised instead of ValueError for some logical errors.
* The parser no longer changes temporarily during parsing.
* Default values are not processed twice.
* Required mutually exclusive groups containing positional arguments are
now supported.
* The missing arguments report now includes the names of all required
optional and positional arguments.
* Unknown options can be intermixed with positional arguments in
parse_known_intermixed_args().
Raise ValueError in add_argument() if either explicit nargs=0 or action
that does not consume arguments (like 'store_const' or 'store_true') is
specified for positional argument.
Also improve the documentation. Specify how dest and metavar are derived
from add_argument() positional arguments.
Co-authored-by: Simon Law <sfllaw@sfllaw.ca>
Previously, all nested mutually exclusive groups lost their connection
to the group containing them and were displayed as belonging directly
to the parser.
Co-authored-by: Danica J. Sutherland <djsutherland@users.noreply.github.com>
Previously, formatting help output or error message for positional argument
with a tuple metavar raised exception.
Co-authored-by: Cyker Way <cykerway@gmail.com>
It can now have one of three forms:
* basename(argv0) -- for simple scripts
* python arv0 -- for directories, ZIP files, etc
* python -m module -- for imported modules
Co-authored-by: Alyssa Coghlan <ncoghlan@gmail.com>
Positional arguments with nargs equal to '?' or '*' no longer check
default against choices.
Optional arguments with nargs equal to '?' no longer check const
against choices.
This allows to use positional argument with nargs='*' and without default
in mutually exclusive group and improves error message about required
arguments.
Arguments with the value identical to the default value (e.g. booleans,
small integers, empty or 1-character strings) are no longer considered
"not present".
In case of usage a long command along with max_help_position more than
the length of the command, the command's help was incorrectly started
on the new line.
Co-authored-by: Pavel Ditenbir <pavel.ditenbir@gmail.com>
* parse_intermixed_args() now raises ArgumentError instead of calling
error() if exit_on_error is false.
* Internal code now always raises ArgumentError instead of calling
error(). It is then caught at the higher level and error() is called if
exit_on_error is true.
Rationale
=========
argparse performs a complex formatting of the usage for argument grouping
and for line wrapping to fit the terminal width. This formatting has been
a constant source of bugs for at least 10 years (see linked issues below)
where defensive assertion errors are triggered or brackets and paranthesis
are not properly handeled.
Problem
=======
The current implementation of argparse usage formatting relies on regular
expressions to group arguments usage only to separate them again later
with another set of regular expressions. This is a complex and error prone
approach that caused all the issues linked below. Special casing certain
argument formats has not solved the problem. The following are some of
the most common issues:
- empty `metavar`
- mutually exclusive groups with `SUPPRESS`ed arguments
- metavars with whitespace
- metavars with brackets or paranthesis
Solution
========
The following two comments summarize the solution:
- https://github.com/python/cpython/issues/82091#issuecomment-1093832187
- https://github.com/python/cpython/issues/77048#issuecomment-1093776995
Mainly, the solution is to rewrite the usage formatting to avoid the
group-then-separate approach. Instead, the usage parts are kept separate
and only joined together at the end. This allows for a much simpler
implementation that is easier to understand and maintain. It avoids the
regular expressions approach and fixes the corresponding issues.
This closes the following GitHub issues:
- #62090
- #62549
- #77048
- #82091
- #89743
- #96310
- #98666
These PRs become obsolete:
- #15372
- #96311
When parsing positional vs optional arguments, the use of min with a
list comprehension inside of a loop results in quadratic time based
on the number of optional arguments given. When combined with use of
prefix based argument files and a large number of optional flags, this
can result in extremely slow parsing behavior.
This replaces the min call with a simple loop with a short circuit to
break at the next optional argument.
Co-authored-by: Zsolt Dollenstein <zsol.zsol@gmail.com>
Reproducer depends on terminal size - the traceback occurs when there's
an option long enough so the usage line doesn't fit the terminal width.
Option order is also important for reproducibility.
Excluding empty groups (with all options suppressed) from inserts
fixes the problem.
If the option with argument has short and long names,
output argument only once, after the long name:
-o, --option ARG description
instead of
-o ARG, --option ARG description
Serhiy Storchaka
Savannah Ostrowski
rindeal
Jérémie Detrey
Payton
Ali Hamdan
blhsing
Nikita Sobolev
Amethyst Reese
Emmanuel Arias
Daniel Mach
Frank Dana
Jokimax
Alex Waygood
Tian Gao