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

Andrey Vlasovskikh andrey.vlasovskikh at gmail.com
Thu Nov 7 13:53:33 CET 2013


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!"


More information about the code-quality mailing list