>> But patching the module to allow explicitly setting dest via keyword 
>> argument shouldn't hurt anybody.
>
> I agree that it wouldn't hurt anybody. If you can find a way to do
> this, feel free to provide a patch.
>
> However, the correct way to have one name for the attribute (i.e.
> dest=) and one name for the help (i.e. metavar=) is to use the
> metavar argument like so:
>
>     parser.add_argument('positional_args', metavar='positional-args')

I don't think that making ``dest`` more magical is a good idea. In the
included patch, you'll find a change that makes the ValueError tell
people about ``metavar``, which is the right way to go about things
anyway.

> That said, this is not the first time I've seen someone run into this
> problem. I think the documentation could be improved in a few ways:
>
> (1) In the "name or flags" section, describe how the flags (for
> optional arguments) are translated into both a default "dest"
> (stripping initial '-' and converting '-' to '_') and into a default
> "metavar" (stripping initial '-' and uppercasing). Part of this is
> in the "dest" and "metavar" documentation, but probably belongs up
> in the "name or flags" documentation. Add cross-references to "dest"
> and "metavar" sections.

In the included patch.

> (2) In the "name or flags" section, describe how the name (for
> positional arguments) are translated into the same default "dest"
> and "metavar" (no string munging at all). Again, move stuff from the
> "dest" and "metavar" sections as necessary. Add cross-references to
> "dest" and "metavar" sections.
>
> (3) In the "dest" section and somewhere in the "parse_args" section,
> describe how "getattr" can be used to get attributes whose names
> aren't valid Python identifiers. Maybe cross-reference this section
> from the edits in (2).

If we make optional and positional arguments consistent, and provide
backwards-compatibility for positional arguments, then these two are
not necesssary.