[Python] support type hints

[wing328]

Description

We want to support type hints, which was introduced for Python 3.5+. The feature will be added to Python API client as well as server (Flask).

Since this option is for 3.5+ only, we will need to use the option supportPython2 to selectively disable it if supportPython2 (default to false) is set to true

Python version: 3.5+

Ref: https://www.python.org/dev/peps/pep-0484/

Suggest a Fix

If anyone from the community has questions/suggestions or wants to work on it, please reply to let us know. Thank you.

[cbornet]

Note : Flask already has type hints.

[wing328]

@cbornet so we can simply copy the following over to api.mustache for Python API client?

https://github.com/swagger-api/swagger-codegen/blob/master/modules/swagger-codegen/src/main/resources/flaskConnexion/controller.mustache#L16-L51

[cbornet]

I may have written too fast. Those are docstrings and you also have them in the python generated code. Type hints are only generated for models in flask.
Now why do you want to use typings ? Aren't docstrings sufficient ?

[wing328]

From what I read, there are certain benefits using typing (assuming the IDE supports it), e.g. type checking when writing Python to avoid potential issue during runtime. Something nice to have but definitely not a must.

[cbornet]

Yes but IDEs generally also support type checking from docstrings (at least pyCharm does).

[wing328]

The following SO lists out some benefits:

http://stackoverflow.com/a/32558710/677735

Disclaimer: I've not evaluated Python type hint myself.

[cbornet]

Yes, all those benefits are also true with docstrings. And docstrings also document the parameters (not only their types) and are available in python 2.

[cbornet]

Also note that there is a PEP484 syntax for python2 if docstrings are not enough : https://www.python.org/dev/peps/pep-0484/#suggested-syntax-for-python-2-7-and-straddling-code

[cbornet]

So maybe the best would be to generate PEP484 annotations for py3, PEP484 type comments for py2 and Sphynx docstring but only for param documentation and not types.
But before it should be checked if Sphynx correctly assembles the docstrings params and PEP484 types to generate the doc.