argparse: undocumented `nargs` constants `ONE_OR_MORE`, `OPTIONAL`, `PARSER`, `REMAINDER`, `ZERO_OR_MORE`, `SUPPRESS`

[rindeal]

Concerning the possible values of the nargs parameter of add_argument().

The following values are already described in the documentation, so only a mention of the constants is needed:

• OPTIONAL = ?
• ZERO_OR_MORE = *
• ONE_OR_MORE = +

The following constants and their values do not seem to be documented anywhere:

• PARSER
• REMAINDER

SUPPRESS constant was documented for help parameter in https://github.com/python/cpython/issues/53595, but not for nargs.

[vadmium]

The nargs=REMAINDER documentation was removed on purpose in #61252; see also #101472

[savannahostrowski]

I'm not really convinced that we should do this. While we could document these constants for completeness, doing so would probably add unnecessary redundancy to the docs and potentially confuse newer users.

Using *, +, ?, etc. is far and away more common than using these constants (e.g., nargs='*' has 110k hits vs. nargs=argparse.ZERO_OR_MORE has 96 hits). There are probably some scenarios where folks might want to use the constants (e.g., linters, editors/autocomplete), but again, the search yielded few results...leading me to believe this is uncommon.

A cursory search on GitHub also showed very little usage for PARSER and SUPPRESS. To the best of my knowledge, unlike REMAINDER, these were never documented.

[rindeal]

I'm not really convinced that we should do this. While we could document these constants for completeness, doing so would probably add unnecessary redundancy to the docs and potentially confuse newer users.

Using *, +, ?, etc. is far and away more common than using these constants (e.g., nargs='*' has 110k hits vs. nargs=argparse.ZERO_OR_MORE has 96 hits). There are probably some scenarios where folks might want to use the constants (e.g., linters, editors/autocomplete), but again, the search yielded few results...leading me to believe this is uncommon.

A cursory search on GitHub also showed very little usage for PARSER and SUPPRESS. To the best of my knowledge, unlike REMAINDER, these were never documented.

Thank you for your input @savannahostrowski. However, the argument based on search frequency may reflect a statistical bias. The low usage of these constants could be a direct result of their lack of documentation, rather than an indication of their irrelevance or redundancy. Proper documentation could potentially increase their usage, especially in scenarios where constants are preferred for clarity or consistency (e.g., linters, editors/autocomplete). Therefore, documenting these constants would enhance completeness and potentially benefit users who prefer or require explicit constants.

[rindeal]

https://github.com/python/cpython/issues/118920#issuecomment-2105347251:

The nargs=REMAINDER documentation was removed on purpose in #61252; see also #101472

The decision was highly sub-optimal, like sweeping the problems under the rug. It would have been far better to either deprecate and remove it or clearly document it as a legacy, buggy feature.