classification
Title: argparse.ArgumentParser() lists arguments in the wrong order
Type: behavior Stage: resolved
Components: Documentation, Library (Lib) Versions: Python 3.3, Python 3.4, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: BreamoreBoy, Kostyantyn.Leschenko, asvetlov, bethard, docs@python, eric.araujo, flox, petri.lehtinen, roysmith, santoso.wijaya, terry.reedy
Priority: normal Keywords: easy, patch

Created on 2011-10-23 18:32 by roysmith, last changed 2013-04-07 11:49 by asvetlov. This issue is now closed.

Files
File name Uploaded Description Edit
Issue13249.patch roysmith, 2011-10-23 21:12 review
Issue13249-2.patch roysmith, 2011-11-12 16:44 Version 2 of patch, addressing Éric's suggestions. review
Issue13249-3.patch roysmith, 2011-11-16 03:34 review
Issue13249-4.patch bethard, 2012-07-23 19:15 review
Issue13249-5.patch Kostyantyn.Leschenko, 2013-04-07 10:09 review
Messages (19)
msg146238 - (view) Author: Roy Smith (roysmith) Date: 2011-10-23 18:32
The docs list the arguments in the order:

class argparse.ArgumentParser([description][, epilog][, prog]...

but the code (I'm looking at the 2.7.2 source) lists them as:

 class ArgumentParser(_AttributeHolder, _ActionsContainer):
   [...]
   def __init__(self,
                 prog=None,
                 usage=None,
                 description=None,
                 [...]

If you create a parser with just:

parser = argparse.ArgumentParser("foo")

you end up setting the 'prog' argument instead of the expected 'description'.  

It's unclear if the order in the code should be fixed to match the docs, or the order in the docs fixed to match the code, or just a note added to the docs saying you should not rely on positional argument ordering and always create a parser with named arguments.
msg146241 - (view) Author: Florent Xicluna (flox) * (Python committer) Date: 2011-10-23 18:39
in 3.x, same issue.
IMHO documentation should be fixed.
msg146246 - (view) Author: Petri Lehtinen (petri.lehtinen) * (Python committer) Date: 2011-10-23 19:02
Fixing the documentation is better, as changing the argument order would break existing code.
msg146248 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2011-10-23 19:11
In the doc, the signature line is followed by a list of short descriptions in a third order. That perhaps should be changed to follow the same corrected order as the signature line. On the other hand, it matches the order of the detail sections that follow. On the third hand, that current order is confusing as it intermixes parameters that affect the help message behavior with those that affect the actual argument parsing behavior. I think these should be separated with one group following the other.
msg146250 - (view) Author: Roy Smith (roysmith) Date: 2011-10-23 19:16
An Nth place is in the docstring:

    Keyword Arguments:                                                                              
        - prog -- The name of the program (default: sys.argv[0])                                    
        - usage -- A usage message (default: auto-generated from arguments)                         
        - description -- A description of what the program does                                     
        - epilog -- Text following the argument descriptions                                        
        - parents -- Parsers whose arguments should be copied into this one                         
        - formatter_class -- HelpFormatter class for printing help messages                         
        - prefix_chars -- Characters that prefix optional arguments                                 
        - fromfile_prefix_chars -- Characters that prefix files containing                          
            additional arguments                                                                    
        - argument_default -- The default value for all arguments                                   
        - conflict_handler -- String indicating how to handle conflicts                             
        - add_help -- Add a -h/-help option

which omits 'version'.
msg146254 - (view) Author: Roy Smith (roysmith) Date: 2011-10-23 20:31
I'm working on a doc patch now...
msg146257 - (view) Author: Roy Smith (roysmith) Date: 2011-10-23 21:12
Patch attached.  I just deal with putting all the items into the same order, not terry.reedy's idea for separating them into two groups.

Added a recommendation to only use keywords, which seems sane given the number of arguments.
msg146258 - (view) Author: Roy Smith (roysmith) Date: 2011-10-23 21:14
PS -- this is against the 2.7 branch.
msg147481 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-11-12 13:37
Thanks, I’ve made some comments on Rietveld.

> Added a recommendation to only use keywords, which seems sane given
> the number of arguments.
I looked for that but couldn’t find it.
msg147511 - (view) Author: Roy Smith (roysmith) Date: 2011-11-12 16:44
New patch uploaded.

The added recommendation is around line 161 (look for 'Recommended usage is to only use keyword arguments')
msg147616 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-11-14 16:58
I would not use a note directive.  Notes and warnings distract and sometimes scare readers.  For a simple coding recommendation like this, I think a regular paragraph would suffice.  To make sure it’s not lost after pages of options description, maybe it could be put right after the signature?  Also, it would be nice to explicit the why of this recommendation (e.g. “due to the number of arguments, it is recommended to always use keyword arguments for this function”).
msg147631 - (view) Author: Roy Smith (roysmith) Date: 2011-11-14 20:44
Before I build another patch, would you be OK with leaving it as a note, but adding the "due to the number of arguments" language?  There's a lot of text here, and people tend to just zoom in on the bits and pieces they need right now.  I think there is value in making this stand out as a note.

If you feel strongly this should not be a note, let me know and I'll change it.
msg147651 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2011-11-15 01:45
I agree with Eric both as to placement (first paragraph) and wording (with explanation). I don't have time to review otherwise at the moment.
msg147749 - (view) Author: Roy Smith (roysmith) Date: 2011-11-16 03:34
Another patch, with the most recent review suggestions incorporated.
msg149529 - (view) Author: Steven Bethard (bethard) * (Python committer) Date: 2011-12-15 10:56
The ArgumentParser constructor is definitely only intended to be called with keyword arguments, so it's definitely a documentation bug that it doesn't say this. I haven't actually applied the patch, but the basic approach and wording look fine to me.
msg166244 - (view) Author: Steven Bethard (bethard) * (Python committer) Date: 2012-07-23 19:15
I've updated the patch for the current trunk. Should be ready to commit.
msg185935 - (view) Author: Mark Lawrence (BreamoreBoy) * Date: 2013-04-03 16:43
Can someone please review the latest patch and commit if appropriate.
msg186186 - (view) Author: Kostyantyn Leschenko (Kostyantyn.Leschenko) Date: 2013-04-07 10:09
I've updated patch to work with current trunk.
msg186196 - (view) Author: Andrew Svetlov (asvetlov) * (Python committer) Date: 2013-04-07 11:49
Fixed in 4712f9f8a90d, 5e5081cdc086, e4beda7cca2f.
Thanks.
History
Date User Action Args
2013-04-07 11:49:25asvetlovsetstatus: open -> closed
resolution: fixed
messages: + msg186196

stage: needs patch -> resolved
2013-04-07 10:09:51Kostyantyn.Leschenkosetfiles: + Issue13249-5.patch
versions: + Python 3.4, - Python 3.2
nosy: + asvetlov, Kostyantyn.Leschenko

messages: + msg186186
2013-04-03 16:43:14BreamoreBoysetnosy: + BreamoreBoy
messages: + msg185935
2012-07-23 19:15:31bethardsetfiles: + Issue13249-4.patch

messages: + msg166244
2011-12-15 10:56:43bethardsetmessages: + msg149529
2011-11-16 03:34:32roysmithsetfiles: + Issue13249-3.patch

messages: + msg147749
2011-11-15 01:45:02terry.reedysetmessages: + msg147651
2011-11-14 20:44:01roysmithsetmessages: + msg147631
2011-11-14 16:58:11eric.araujosetmessages: + msg147616
2011-11-12 16:44:48roysmithsetfiles: + Issue13249-2.patch

messages: + msg147511
2011-11-12 13:37:34eric.araujosetnosy: + eric.araujo
messages: + msg147481
2011-10-23 21:14:31roysmithsetmessages: + msg146258
2011-10-23 21:12:58roysmithsetfiles: + Issue13249.patch
keywords: + patch
messages: + msg146257
2011-10-23 20:31:55roysmithsetmessages: + msg146254
2011-10-23 19:16:12roysmithsetmessages: + msg146250
2011-10-23 19:11:02terry.reedysetnosy: + terry.reedy
messages: + msg146248
2011-10-23 19:06:00santoso.wijayasetnosy: + santoso.wijaya
2011-10-23 19:02:12petri.lehtinensetkeywords: + easy
nosy: + petri.lehtinen
messages: + msg146246

2011-10-23 18:39:11floxsetassignee: docs@python
components: + Documentation
versions: + Python 3.2, Python 3.3
nosy: + docs@python, flox, bethard

messages: + msg146241
stage: needs patch
2011-10-23 18:32:39roysmithcreate