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!"
_______________________________________________
code-quality mailing list
code-quality@python.org
https://mail.python.org/mailman/listinfo/code-quality
