Support for Python 2/3 "straddling" type hint comments

[ches]

Many libraries will likely maintain Python 2 compatibility for some time yet. It would be fantastic if Sphinx apidoc supported the Python 2.7-friendly "straddling" syntax for type hints that was added to PEP 484 (i.e. # type: comments), for rendering in the same way as Python 3 type hints currently do. Additionally, support for .pyi files could also help for similar use cases.

PyCharm supports the # type: comments now, so demand might increase from people maintaining Python 2-compatible code.

I'm not at all familiar with Sphinx internals but I could try to work on this with a bit of guidance, perhaps.

Note that GvR directed me to dropbox/typed_ast for getting at the information, urging not to try to use mypy as a library due to instability of its API. typed_ast supports parsing Python 2.7 code but unfortunately itself only runs in Python 3.

[cbornet]

👍

[thomascobb]

I made a start on extracting type comments in another project, could be useful as a starting point for you:

https://github.com/dls-controls/annotypes/blob/master/annotypes/_calltypes.py#L81

I only attempt to parse comments where they exactly match the number of arguments given to the function, otherwise ast parsing would have been required rather than just tokenizing and comparing the type strings with the arguments of the function...

[Zac-HD]

annotypes permalink