Should helputils._UsageStringFromFullArgSpec show PEP 484 Type Hints if Available?

[keatinge]

PEP 484 introduced the standard syntax for type annotations in Python. Consider this example

import fire
def greeting(name:str, age:int) -> str:
    return "{name} will be {new_age} in 1 year".format(name=name, new_age=age+1)
fire.Fire(greeting)

Python fire currently will show the following when I type python test.py -- --help

Type:        function
String form: <function greeting at 0x00235738>
File:        c:\users\admin\desktop\test.py
Line:        4

Usage:       test.py NAME AGE
             test.py --name NAME --age AGE

Would it be helpful to give type hints here? Maybe something like this?

Usage:       test.py NAME:str AGE:int
             test.py --name NAME --age AGE

The implementation is very straightforward, I've already done it as a test on my local copy. We can use spec.annotations inside helputils._UsageStringFromFullArgSpec which gives a dict like this:

{'name': <class 'str'>, 'return': <class 'str'>, 'age': <class 'int'>}

Questions:

1. Are type hints useful here? Or are they just cluttering up the info?
2. Where should the type hints be? In both the usage lines? Just the first?
3. What should the syntax be? Should it be var:type or something else?
4. In the future could we use type hints to enhance parser.py.DefaultParseValue?
5. Show type hints for just the arguments or also for the return value of a function?
6. Support for Python 2 type hints? http://stackoverflow.com/questions/35230635/type-hinting-in-python-2

[dbieber]

Good idea.

I agree that annotations should be shown in the help information, when available. We should consider the design of this in conjunction with larger changes to the usage strings. I expect we'll want to show the type annotations separately from the "Usage" section, in order to 1. Keep the usage section clean, and 2. support non-type annotations.

As an example of other changes to help information that we want: When showing the usage info for an object, we should probably separate its callable properties from its noncallable ones visually, possibly showing usage information for its callable members, and maybe the members' docstrings too.

[keatinge]

Yeah you're right, they shouldn't be in the usage section, in that case I think just printing inspect.signature(func) would be a pretty good solution, that would look like this. Is this what you're thinking? Or do you have better design in mind?

Type:        function
String form: <function greeting at 0x00235738>
File:        c:\users\admin\desktop\test.py
Line:        4
Signature:   (name:str, age:int) -> str

Usage:       test.py NAME AGE
             test.py --name NAME --age AGE

[dbieber]

That looks nice. Not sure how that will look with more complex annotations. I'll have to play around with it some once I'm at a computer.

If it gets messy, we could consider something like only showing the Signature a) if we're in verbose mode or b) if it doesn't have any non-type annotations.

[arogozhnikov]

@keatinge I'm interested in exactly the case you described. Did you find a way to directly use annotations? (I see fire still doesn't support it, but are there other utilities that do?)