argparse.ArgumentParser() lists arguments in the wrong order

[roysmith]

BPO	13249
Nosy	@terryjreedy, @merwok, @asvetlov, @florentx, @akheron
Files	Issue13249.patch Issue13249-2.patch: Version 2 of patch, addressing Éric's suggestions. Issue13249-3.patch Issue13249-4.patch Issue13249-5.patch

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2013-04-07.11:49:25.652>
created_at = <Date 2011-10-23.18:32:39.141>
labels = ['easy', 'type-bug', 'library', 'docs']
title = 'argparse.ArgumentParser() lists arguments in the wrong order'
updated_at = <Date 2013-04-07.11:49:25.646>
user = 'https://bugs.python.org/roysmith'

bugs.python.org fields:

activity = <Date 2013-04-07.11:49:25.646>
actor = 'asvetlov'
assignee = 'docs@python'
closed = True
closed_date = <Date 2013-04-07.11:49:25.652>
closer = 'asvetlov'
components = ['Documentation', 'Library (Lib)']
creation = <Date 2011-10-23.18:32:39.141>
creator = 'roysmith'
dependencies = []
files = ['23505', '23667', '23703', '26490', '29704']
hgrepos = []
issue_num = 13249
keywords = ['patch', 'easy']
message_count = 19.0
messages = ['146238', '146241', '146246', '146248', '146250', '146254', '146257', '146258', '147481', '147511', '147616', '147631', '147651', '147749', '149529', '166244', '185935', '186186', '186196']
nosy_count = 11.0
nosy_names = ['terry.reedy', 'roysmith', 'bethard', 'eric.araujo', 'asvetlov', 'flox', 'santoso.wijaya', 'docs@python', 'BreamoreBoy', 'petri.lehtinen', 'Kostyantyn.Leschenko']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue13249'
versions = ['Python 2.7', 'Python 3.3', 'Python 3.4']

[roysmith]

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.

[florentx]

in 3.x, same issue.
IMHO documentation should be fixed.

[akheron]

Fixing the documentation is better, as changing the argument order would break existing code.

[terryjreedy]

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.

[roysmith]

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'.

[roysmith]

I'm working on a doc patch now...

[roysmith]

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.

[roysmith]

PS -- this is against the 2.7 branch.

[merwok]

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.

[roysmith]

New patch uploaded.

The added recommendation is around line 161 (look for 'Recommended usage is to only use keyword arguments')