Swagger-codegen: [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.

[kirpit]

@cbornet is there any harm leaving the docstrings along with the type hinting? Sphinx should just do fine, maybe even better because there are now 2 different source of hinting..

This will actually lead to less if - else logic introduced in the template files that I believe things should be kept as simple as possible. I would actually suggest to implement type hinting both for py2 and py3 and simply use the official backported package typing for py2, just like here:

http://mypy.readthedocs.io/en/stable/python2.html

or maybe even simpler like this again by using the backported package:
http://python-future.org/func_annotations.html

Also check out that stackoverflow question.

This will completely avoid having many other {{^supportPython2}} .. {{/supportPython2}} in the template files as they will be identical in that context.

[abe1911]

Hey, I am not sure about the status of this issue right now, but some of the things are incorrectly hinted according to PEP 484.

Following are the errors and the correct typing respectively.

• In any Model:
  ( if default Values are None for a property):

  • Incorrect:
    @property def some_property(self) -> sometype:

  • Correct:
    @property def some_property(self) -> Optional[sometype]:

  • Incorrect:
    @classmethod def from_dict(cls, dikt) -> 'SomeModel':

  • Correct:
    @classmethod def from_dict(cls: Type[Model], dikt: Dict) -> Model:

• In base_model_:

  • Incorrect:
    @classmethod def from_dict(cls: Type[T], dikt) -> T:

  • Correct:
    @classmethod def from_dict(cls: Type['Model'], dikt: Dict) -> 'Model':

Would be great if these can be patched soon.

[keymone]

any progress on this?

[WoLpH]

Since Python 3.4 and below are all EOL it won't hurt any actively supported Python release to switch or add type hints. So... please let's add it :)

[kevinmu]

Currently, you can't run mypy to typecheck code that queries the generated APIs. Unfortunately mypy doesn't read the :param docstrings; it only knows about the syntax defined in PEP484 (https://www.python.org/dev/peps/pep-0484/#suggested-syntax-for-python-2-7-and-straddling-code) as mentioned above.

So one more reason to migrate to using typehints!