Type hinting ("typing" module)

[jacobsvante]

First of all, THANKS @neithere for this awesome project, it's never been easier to set up a command line tool!

Just wanted to check on you to see how you feel about supporting the new typing module? This way it would be possible to specify type on positional arguments without using the @argh.arg decorator.. This would make argh even more great i.m.o.

[neithere]

Hi Jacob,

Thank you for your interest and for the idea. I agree that we should support typing. Originally there was no convention on the usage of annotations, so I chose to tuck argument documentation there. It allowed to get rid of the @arg decorator when it was used solely for the help. However, as annotations now seem to be used mostly with typing and it would be at least useful as the docs are, we should change the way argh interprets annotations.

Possible approach:

• deprecate textual annotations;
• introspect the annotation and show deprecation warning if it's a string;
• remove old behaviour in some later version.

Obstacles:

• @arg('x', help='blah') will have to be added in certain cases;
• it's not clear how exactly we would use types.Generic e.g. for string coercion.

[jacobsvante]

Thanks for your input @neithere. I did not think of the annotation functionality of Python 3 and tbh I've never used it. Is there a way to combine both? I like the ability to idea of inlining the documentation also 😅.

[neithere]

So, the library began its life when I had some free time in an airport. Today I had a similar time slot in the same place, so I decided to give argh+typing a try :) Unfortunately, when I started writing unit tests, I couldn't come up with anything meaningful. I kinda feel that it should make sense, but how? ))

Do you have any hypothetical example that we could put into unit tests and try to make it work?

Andy

[cottrell]

Where did this land in the last few years? I might have a look unless someone would suggest another library that does similar things? I have been quite happy with argh over the time I've been using it so might just try to kick this along. A typed example might be something like this:

def f(*, a: int, b: str, c: float):
    pass

[presheaf]

I also found myself wanting this. Currently, if you have a function you want to argh.dispatch_command on with some arguments you want to type, in the absence of default values argh can use to infer types, you're forced to do something like the following for x, y, z to end up being ints.

@argh.arg('x', type=int)
@argh.arg('y', type=int)
@argh.arg('z', type=int)
def myfunc(x, y, z):
    ...

It would be a lot nicer IMO if you could just write

def myfunc(x: int, y: int, z: int):
    ...

This would take the place of th documentation-type annotations argh currently supports. I can't think of a clean way to make them go together which wouldn't abuse the type hinting system, Maybe those are a better fit for a decorator?

@argh.doc({
    'x': 'information about x',
    'z': 'information about z'
})
def myfunc(x: int, y: int, z: int):
    ...

I think I would be up for implementing this, if there is interest.

[neithere]

So... This is definitely something that needs to go into Argh 1.0. Will bring the library to a whole new level of DRYness that was not technically achievable at the time when its first versions were created.

Issue #144 adds more ideas which I like a lot: using Optional and List/Tuple to infer more than just type.

So e.g. for func(foo: Optional[List[str]]: None) we would typing.get_args(hint) for foo and:

• descend into the first nested item, do typing.get_origin(x), discover that it's a list → set flag "multi-value"
• descend into the second nested item, discover that it's NoneType → set flag "optional"
• set nargs to * because it's "multi-value" and "optional".

Mapping the typing hints to argparse argument declarations is not an easy task. There will be dubious cases.

I think we need to start by drafting a list of possible mappings, from simple and obvious ones to complicated ones (with Union and so on).

For example:

• foo: 'hello' → add_argument('foo', help='hello')
  • the original "hack" to document arguments via annotations, should be deprecated as it is considered an error by mypy.
• foo: str → add_argument('foo', help='str')
• foo: Optional[str]: None → add_argument('foo', type=str, default=None, help='Optional[str]') (I'll omit help in the rest)
• foo: List[str] → add_argument('foo', nargs='+')
• foo: Optional(List[str]) → add_argument('foo', nargs='*')
• foo: Dict[str, str] → ?
  • I can imagine parsing JSON or something in that vein but it's "too smart" for default behaviour; could be enabled via some decorator like @argh.hints(parse_json_for=[Dict, List]) or @argh.plugin('json').enable_for_args('foo', 'bar').

[presheaf]

Here are some suggestions for two somewhat complex but (I think) useful type hints.

• foo: Literal['one', 'two', 'three'] -> add_argument('foo', choices=['one', 'two', 'three'] (it would be very cool if argument completion could also hook into this)
• foo: Tuple[str, int, float] -> add_argument('foo', nargs=3), followed by (e.g.) args = parser.parse_args(); args.foo[1] = int(args.foo[1]); args.foo[2] = float(args.foo[2])

I'm a little unsure about what I'd expect to happen for foo: UnsupportedType. UnsupportedType(passed_arg) seems a sane default, but sometimes won't be what is expected, so probably some care should be taken with informative error messages and where conversion functions can be passed via decorator. Provided common ones like JSON parsing are easily available, I don't think this will be too annoying.