More informative exception on explicit vs inferred arg type clash about argh

[neithere]

This is by design

Please note how the pythonic notation maps to that of argparse:

• f(x) = arg('x') = positional
• f(x=y) = arg('--x', default=y) = optional (keyword)

You have defined a positional argument in your function signature and then refer to an optional argument (kwarg) which does not exist.

Let's define a command with both types of arguments with both "natural" and "explicit" notations:

#!/usr/bin/env python
import argh

@argh.arg('my-positional', help='a positional argument')
@argh.arg('--my-optional', help='an optional argument')
def mycommand(my_positional, my_optional='full'):
    print(my_positional, my_optional)

argh.dispatch_command(mycommand)

Run it:

$ python issue47.py foo
foo full

There's room for improvement

To sum up, there's no bug here but the confusion is certainly undesired.

I think we should raise a more informative exception if the @arg decorator refers to an argument of one type whereas an argument of different type exists with such name. Something like "optional argument --my-switch conflicts with positional my-switch from function signature".

[neithere]

Changed the issue title from "How do include optional arguments with hyphens/underscores" to "More informative exception on explicit vs inferred arg type clash".

[redstreet]

Thanks for the explanation, it makes much more sense now. For some reason, I didn't get this from the documentation including the tutorial part, so perhaps adding this example or something similar might help.

BTW, thanks for argh. It is simply fantastic to use, and I really like the DRY, pythonic design.

[neithere]

I've started writing tests for this issue and found out that the problem actually does not appear until there's a underscore/hyphen in argument name. If there isn't one, the application still works properly but another subtle bug may appear:

import argh

@argh.arg('--foo', default=1)
def f(foo):
    "Positional in signature, keyword in decorator"
    return foo

@argh.arg('foo')
def p(foo=1):
    "Keyword in signature, positional in decorator"
    return foo

argh.dispatch_commands([f, p])

and the call:

$ python issue47.py p 5
5
$ python issue47.py p
usage: issue47.py p [-h] foo
issue47.py p: error: the following arguments are required: foo

(Note that whether it may be OK to override some features of the original signature with decorators, here the very nature of the argument is distorted in a seemingly harmless and simple piece of code.)

So:

1. Underscores should be always converted to hyphens before comparison of inferred and declared arguments;
2. Assembling should ensure strict mutual conformance of definitions. This means that any combination of equally named positional arguments and flags should raise an error with an easily understandable message.

[redstreet]

Works great, thanks.