Is there a standard, Pythonic way to express the parameter type and return type of a function?
I am looking for a notation that is:
help()I have seen some examples, like this reSt syntax:
"""replaces template place holder with values
:param timestamp: formatted date to display
:type timestamp: str or unicode
:param priority: priority number
:type priority: str or unicode
:param priority_name: priority name
:type priority_name: str or unicode
:param message: message to display
:type message: str or unicode
:returns: formatted string
:rtype: str or unicode
"""
However, I am not sure how official / supported is this format.
There are mainly 3/4 formats competiting for the Python docstrings. See this tuto to have an overview. The older format, now discontinued, is the Epytext for Epydoc based on Javadoc style. The probably more popular is the reStructuredText (reST) for Sphinx format. The Google style is also quite used. And of course the Numpydoc inspired from the Google style.
Concerning what should be the official/standard way you can refer to this topic.
Each format has its own way to represent the parameters types and return type. There follows some examples:
"""
@param param1: Description of param1
@type param1: type of param1
@return: description of returned value
@rtype: type of returned value
"""
"""
:param param1: Description of param1
:type param1: type of param1
:return: description of returned value
:rtype: type of returned value
"""
"""
Args:
param1(int): Description of parameter `param1`.
param2(str, optional): Description of a parameter. Defaults to None.
Returns:
bool: True or False depending on the result.
"""
"""
Parameters
----------
param1 : int
Description of parameter `param1`.
param2 : {'value1', 'value2'}
Description of a parameter with two possible values.
Returns
-------
int
Description of the returned value
"""
Note that if you have no docstrings or you want to change your docstring format for your Python project, you can use Pyment.