classification
Title: argparse: PARSER option for nargs not documented
Type: Stage: resolved
Components: Documentation Versions: Python 3.4
process
Status: closed Resolution: not a bug
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Robert, bethard, chris.jerdonek, docs@python, jeffknupp, paul.j3, r.david.murray
Priority: normal Keywords:

Created on 2013-01-17 21:30 by Robert, last changed 2017-09-04 17:45 by r.david.murray. This issue is now closed.

Messages (4)
msg180155 - (view) Author: Robert Leenders (Robert) Date: 2013-01-17 21:30
There is a value for nargs: PARSER="A..." which is not documented at http://docs.python.org/3.4/library/argparse.html#nargs. The docstring for the action class in argparse.py also does not list PARSER as a valid value for nargs.

In argparse.py on line 2199-2201 it says:
# Allow one argument followed by any number of options or arguments
elif nargs == PARSER:
    nargs_pattern = '(-*A[-AO]*)'

This is the only hint that I could find on what it is about.
msg180195 - (view) Author: Jeff Knupp (jeffknupp) * Date: 2013-01-18 15:11
This is not a bug.

The 'PARSER' nargs choice is an implementation detail as a way to handle subparsers. The parser needs to know that the first value should be handled, but everything that follows will be handled by the subparser.

By using a subparser, you're effectively using 'PARSER', but it wouldn't make sense to allow 'PARSER' to be set directly as it only makes sense when used in conjunction with a subparser.
msg187140 - (view) Author: paul j3 (paul.j3) * (Python triager) Date: 2013-04-17 04:14
I've experimented with an argparse adaptation of profile.py:

    parser = argparse.ArgumentParser(usage=usage)
    parser.add_argument('-o', '--outfile', dest="outfile",
        help="Save stats to <outfile>", metavar="path")
    parser.add_argument('-s', '--sort', dest="sort",
        help="Sort order when printing to stdout ...",
        default=-1)
    parser.add_argument('args', nargs=argparse.PARSER,
        metavar="scriptfile [arg] ...") 
        # expect at least one positional, a py module

It is somewhat like subparsers, but without defined subparser choices.  Or you could say that PARSER (A...) is to REMAINDER (...) as '+' is to '*'.  It requires at least one argument.  I could, just as well, have created two arguments, 'scriptfile' and 'args' (with '...').

I don't know if that is an argument for documenting it or not.
msg301233 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2017-09-04 17:45
I don't think this use case is enough to justify documenting it, since this is not an intuitive meaning of the word PARSER.  I think if we wanted to expose this for this kind of use case, we'd want to rename the constant (with an alias for backward compatibility), which would be an enhancement.  I'm going to close this, but someone who wants this could open an enhancement request.
History
Date User Action Args
2017-09-04 17:45:19r.david.murraysetstatus: open -> closed

type: enhancement ->

nosy: + r.david.murray
messages: + msg301233
resolution: not a bug
stage: resolved
2013-04-17 04:14:36paul.j3setnosy: + paul.j3
messages: + msg187140
2013-01-18 15:11:01jeffknuppsetnosy: + jeffknupp
messages: + msg180195
2013-01-17 21:38:10chris.jerdoneksetnosy: + chris.jerdonek
2013-01-17 21:30:15Robertcreate