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
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
``os.geteuid() == 0`` is not a reliable check whether the current user
has the capability to bypass permission checks. Tests now probe for DAC
override.
Add methods enterContext() and enterClassContext() in TestCase.
Add method enterAsyncContext() in IsolatedAsyncioTestCase.
Add function enterModuleContext().
Help for other actions omit the default value if default is SUPPRESS or
already contains the special format string '%(default)'. Add those
special cases to BooleanOptionalAction's help formatting too.
Fixes https://bugs.python.org/issue44587 so that default=SUPPRESS is not
emitted.
Fixes https://bugs.python.org/issue38956 as this code will detect
whether '%(default)s' has already been specified in the help string.
Signed-off-by: Micky Yun Chan (michiboo): <chanmickyyun@gmail.com>
Co-authored-by: Micky Yun Chan <michan@redhat.com>
Raise an ArgumentError when the same subparser name is added twice to an
ArgumentParser. This is consistent with the (default) behavior when the
same option string is added twice to an ArgumentParser.
(Support for `conflict_handler="resolve"` could be considered as a
followup feature, although real use cases seem even rarer than
"resolve"ing option-strings.)
Automerge-Triggered-By: GH:rhettinger
# Adding 'required' to names in Lib.argparse.Action
gh-91832:
Added 'required' to the list `names` in `Lib.argparse.Action`.
Changed constant strings that test the Action object.
Automerge-Triggered-By: GH:merwok
Also made modes containing 'a' or 'x' act the same as a mode containing 'w' when argument is '-'
(so 'a'/'x' return sys.stdout like 'w', and 'ab'/'xb' return sys.stdout.buffer like 'wb').
Fix an uncaught exception during help text generation when
argparse.BooleanOptionalAction is used with default=argparse.SUPPRESS
and help is specified.
Instead of explicitly enumerate test classes for run_unittest()
use the unittest ability to discover tests. This also makes these
tests discoverable and runnable with unittest.
load_tests() can be used for dynamic generating tests and adding
doctests. setUpModule(), tearDownModule() and addModuleCleanup()
can be used for running code before and after all module tests.
When `allow_abbrev` was first added, disabling the abbreviation of
long options broke the grouping of short flags ([bpo-26967](https://bugs.python.org/issue26967)). As a fix,
b1e4d1b603 (contained in v3.8) ignores `allow_abbrev=False` for a
given argument string if the string does _not_ start with "--"
(i.e. it doesn't look like a long option).
This fix, however, doesn't take into account that long options can
start with alternative characters specified via `prefix_chars`,
introducing a regression: `allow_abbrev=False` has no effect on long
options that start with an alternative prefix character.
The most minimal fix would be to replace the "starts with --" check
with a "starts with two prefix_chars characters". But
`_get_option_tuples` already distinguishes between long and short
options, so let's instead piggyback off of that check by moving the
`allow_abbrev` condition into `_get_option_tuples`.
https://bugs.python.org/issue39546
BPO -16970: Adding error message for invalid args
Applied the patch argparse-v2 patch issue 16970, ran patch check and the test suite, test_argparse with 0 errors
https://bugs.python.org/issue16970
The `allow_abbrev` option for ArgumentParser is documented and intended to disable support for unique prefixes of --options, which may sometimes be ambiguous due to deferred parsing.
However, the initial implementation also broke parsing of grouped short flags, such as `-ab` meaning `-a -b` (or `-a=b`). Checking the argument for a leading `--` before rejecting it fixes this.
This was prompted by pytest-dev/pytest#5469, so a backport to at least 3.8 would be great 😄
And this is my first PR to CPython, so please let me know if I've missed anything!
https://bugs.python.org/issue26967
There is a possibility that someone (like me) accidentally will omit parentheses with `FileType` arguments after `FileType`, and parser will contain wrong file until someone will try to use it.
Example:
```python
parser = argparse.ArgumentParser()
parser.add_argument('-x', type=argparse.FileType)
```
https://bugs.python.org/issue37150
Nikita Sobolev
Ali Hamdan
Daniel Mach
Serhiy Storchaka
Jokimax
Tian Gao
Oleg Iarygin
Yeojin Kim
Hai Shi
Harry
Christian Heimes
Toshio Kuratomi
Antony Lee
Abhigyan Bose
MojoVampire
Felix Fontein
Irit Katriel
Raymond Hettinger
andrei kulakov
Adam Schwalm
Maximilian Hils
Jack DeVries
Anthony Sottile
Inada Naoki
Rémi Lapeyre
alclarks
Kyle Meyer
Brandt Bucher
Rémi Lapeyre
Flavian Hautbois
tmblweed
Zac Hatfield-Dodds
Victor Stinner
zygocephalus
Batuhan Taşkaya