argparse.ArgumentParser("blah")

[Terry Reedy]

On 10/23/2011 2:06 PM, Peter Otten wrote:
> Roy Smith wrote:
>
>> As I read the docs (http://tinyurl.com/3ww9scr), the following two calls
>> should result in the same object:
>>
>> parser = argparse.ArgumentParser(description="blah")
>> parser = argparse.ArgumentParser("blah")
>>
>> In the first case, I'm explicitly setting description to "blah", in the
>> second case, I'm passing "blah" as a positional parameter so it should
>> be taken as first parameter to the function, which happens to be
>> description.  Either way should end up the same.
>>
>> I don't, however, get the same behavior when run with "-h".  The first
>> gives what I would expect:
>>
>> ------------------------------------------------
>> usage: arg.py [-h]
>>
>> blah
>>
>> optional arguments:
>>    -h, --help  show this help message and exit
>> ------------------------------------------------
>>
>> and the second gives:
>>
>> ------------------------------------------------
>> usage: blah [-h]
>>
>> optional arguments:
>>    -h, --help  show this help message and exit
>> ------------------------------------------------
>>
>> Is this a bug, or am I just not reading the docs right?
>
> A quick look into the source code reveals the the documentation is not
> consistent with the actual implementation:
>
> http://hg.python.org/cpython/file/eef1027ab2f0/Lib/argparse.py#l1581
>
> """
> class ArgumentParser(_AttributeHolder, _ActionsContainer):
> [...]
>      def __init__(self,
>                   prog=None,
>                   usage=None,
>                   description=None,
>                   epilog=None,
>                   version=None,
>                   parents=[],
>                   formatter_class=HelpFormatter,
>                   prefix_chars='-',
>                   fromfile_prefix_chars=None,
>                   argument_default=None,
>                   conflict_handler='error',
>                   add_help=True):
> """

I would call this a doc bug. The explanation of the parameters is in a 
different order yet. That should be changed too.

help(ArgumentParser) gives them in the actual order.

> I suggest that you file a bug report.
>
> PS: My guess is that you are supposed to use keyword parameters only,

Parameters are just names local to the function. They are matched to 
argument objects by position or keyword, unless positional matching is 
disabled with the '*,' syntax, or unless the function is 'builtin' and 
keyword matching is not enabled.

> but that the implementation doesn't enforce that (yet?).

This would be an easy change in that adding '*, ' after 'self, ' in the 
parameter list would do it. It would be difficult in that it could break 
code that uses positional matching correctly, as given in the help 
message, and there is no way I know of to give a deprecation message. 
But there might be very little code that does so, given the 
mis-documentation in the manual.

-- 
Terry Jan Reedy