document “--” as a way to distinguish option w/ narg='+' from positional argument in argparse

[grayhemp]

BPO	9182
Nosy	@freddrake, @rhettinger, @ericvsmith, @merwok, @berkerpeksag, @shihai1991, @jacksonriley, @ananthan-123, @slateny
PRs	bpo-9182: Add a section on specifying positional arguments #31810
Files	issue9182.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 = None
created_at = <Date 2010-07-06.16:24:38.683>
labels = ['easy', 'type-bug', '3.9', 'docs']
title = "document \xe2\x80\x9c--\xe2\x80\x9d as a way to distinguish option w/ narg='+' from positional argument in argparse"
updated_at = <Date 2022-03-11.05:58:21.838>
user = 'https://bugs.python.org/grayhemp'

bugs.python.org fields:

activity = <Date 2022-03-11.05:58:21.838>
actor = 'slateny'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2010-07-06.16:24:38.683>
creator = 'gray_hemp'
dependencies = []
files = ['19732']
hgrepos = []
issue_num = 9182
keywords = ['patch', 'easy']
message_count = 21.0
messages = ['109402', '109412', '109420', '109423', '109425', '109426', '109427', '109431', '121519', '121532', '121534', '121724', '121850', '121891', '121893', '121935', '121950', '166243', '355749', '362151', '362265']
nosy_count = 14.0
nosy_names = ['fdrake', 'rhettinger', 'bethard', 'eric.smith', 'eric.araujo', 'docs@python', 'gray_hemp', 'Kotan', 'berker.peksag', 'paul.j3', 'shihai1991', 'jacksonriley', 'Ananthakrishnan', 'slateny']
pr_nums = ['31810']
priority = 'normal'
resolution = None
stage = 'patch review'
status = 'open'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue9182'
versions = ['Python 3.9']

[grayhemp]

Hello,

I am starting to use argparse package and faced the problem where an optional argument w/ nargs='+' conflicts w/ a positional argument.

Here is the test case:

>>> import argparse
>>> p = argparse.ArgumentParser()
>>> p.add_argument('foo', type=str)
_StoreAction(option_strings=[], dest='foo', nargs=None, const=None, default=None, type=<type 'str'>, choices=None, help=None, metavar=None)
>>> p.add_argument('-b', '--bar', type=int, nargs='+')
_StoreAction(option_strings=['-b', '--bar'], dest='bar', nargs='+', const=None, default=None, type=<type 'int'>, choices=None, help=None, metavar=None)
>>> p.print_help()
usage: [-h] [-b BAR [BAR ...]] foo

positional arguments:
foo

optional arguments:
  -h, --help            show this help message and exit
  -b BAR [BAR ...], --bar BAR [BAR ...]
>>> p.parse_args('-b 123 456 bla'.split())
usage: [-h] [-b BAR [BAR ...]] foo
: error: argument -b/--bar: invalid int value: 'bla'

It prints this usage string "usage: [-h] [-b BAR [BAR ...]] foo" so it is assumed that I could use this " -b 123 456 bla" but it does not works.

How could it be and how to solve it?

Thank you in advance.

[merwok]

Thanks for the bug report. Can you try separating option arguments from positional arguments with “--”? If yes, this would be a doc bug.

Also, can you reproduce it with Python 2.7?

[ericvsmith]

I get the same behavior in 2.7. Adding '--', I get:

>>> p.parse_args('-b 123 456 -- bla'.split())
Namespace(bar=[123, 456], foo='bla')

Which is what I expect.

Éric: From your comment, I'm not sure if you think it's a doc bug because '--' does work, or because it doesn't work without it. But I think it's working as designed. I'm closing this. If you think it's a doc bug, please reopen and change to the Documentation component.

[merwok]

Using “--” to explicitly signal positional arguments is most certainly right and standard, but people have to read about that for the first time somewhere. In a perfect world, that would be in their shell’s man page, but better add a word about it in the reference. The “--” marker is actually mentioned in one section: http://docs.python.org/dev/library/argparse#arguments-containing

I’m reopening, suggesting that a line be added to explain the standard “--” separator for use cases like Sergey’s.

[merwok]

Duh, please ignore the first two lines, I forgot to remove them after rephrasing my comment. Sorry.

[freddrake]

On Tue, Jul 6, 2010 at 4:33 PM, Éric Araujo <report@bugs.python.org> wrote:

Using “--” to explicitly signal positional arguments is most certainly
right and standard, but people have to read about that for the first
time somewhere. In a perfect world, that would be in their shell’s man
page, but better add a word about it in the reference.

It's a convention; not all applications in the larger world support it at all.

It needs to be documented for argparse, and also for specific applications
(which may or may not be built using argparse or Python.

This does not belong in the shell documentation unless needed for the shell
itself.