Python: 标准的返回值和参数类型表示方法

Question

有没有一种标准的、符合Python风格的方法来表示一个函数的参数类型和返回类型呢？

我在寻找一种表示法，它应该：

• 能被 help() 识别
• 能被开发工具（IDE）识别
• （最好）在PEP中有描述

我见过一些例子，比如这个reST语法：

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

不过，我不太确定这种格式有多官方或被支持。

Answer 1

据我所知，没有PEP（Python增强提案）专门描述这个问题；PEP257是关于文档字符串的，但内容其实很简单（而且标准库的文档字符串通常没有你的那么详细）。

现在有两个主要的标准，一个是你已经找到的，Sphinx中实现的标准，另一个是更详细（但也更容易阅读）的NumPy规范，这个规范是通过numpydoc这个Sphinx的扩展来实现的。

Answer 2

目前有3到4种格式在争夺Python文档字符串的主导地位。你可以查看这个教程来了解整体情况。以前的格式是Epytext，它是基于Javadoc风格的，但现在已经不再使用了。现在比较流行的是reStructuredText (reST)，这是为Sphinx格式设计的。还有Google风格也被广泛使用。当然，还有Numpydoc，它是受到Google风格的启发。

如果你想了解什么是官方或标准的写法，可以参考这个话题。

每种格式都有自己表示参数类型和返回类型的方式。下面是一些例子：

- Epytext / Javadoc

"""
@param param1: Description of param1
@type param1: type of param1

@return: description of returned value
@rtype: type of returned value
"""

- reST

"""
:param param1: Description of param1
:type param1: type of param1

:return: description of returned value
:rtype: type of returned value
"""

- Google

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

- Numpydoc

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

转换

如果你没有文档字符串，或者想要改变你Python项目的文档字符串格式，可以使用Pyment这个工具。