[code-quality] Python skeletons: type hinting for third-party libraries

[Vladimir Keleshev]

Hi Andrey,

1. I'm a docstring bigot, so the only thing I can recommend is that *if* you decide to use docstrings for type annotations, please, select the format that is readable and well-supported (i.e. NumPy).

2. I don't have much to comment on how the types should be specified, but you should take into account that python is duck-typed language. Sometimes the type is "anything that implements .read() and .write() methods", or "anything that follows `__contains__` protocol".

—Vladimir


07.11.2013, 13:53, "Andrey Vlasovskikh" <andrey.vlasovskikh at gmail.com>:
> Hi Vladimir,
>
>>  You should take a look at NumPy docstring conventions which are fully supported by Sphinx, and are actually human-readable.
>
> There are two questions here:
>
> 1. Where to put type information?
>
>     * Docstrings
>         * ReStructured Text (http://sphinx-doc.org/domains.html#the-python-domain)
>         * Epydoc
>         * NumPy
>     * Expressions
>         * Python 3 function annotations
>         * Decorators
>
> 2. What type system to use? (its syntax and semantics, see the related work section in the Python skeletons proposal [1])
>
> We think that the best place for type information would be function annotations, but they are available only in Python 3 and there is no de facto standard for describing types as Python expressions.
>
> We use docstring-based types in Python skeletons only as a simple temporary solution, since we believe that the effort should be put in creating an expression-based type system for Python that would be acceptable for a large number of static analysis projects and regular Python developers.
>
> We would like to discuss the current implementations [1] and come up with a unified expression-based language (perhaps, supported by a library) for describing Python types, or at least, a set of common patterns (e.g. using a class value as a type of its instances).
>
> [1]: https://github.com/JetBrains/python-skeletons#related-work
>
> --
> Andrey Vlasovskikh
> Senior Software Developer
> JetBrains
> http://www.jetbrains.com/
> "Develop with pleasure!"