python - Python 函数注释与文档

Question

Python3 具有注释功能。我应该使用它来代替文档字符串吗？IE。什么是正确的方法：

def func(points: [{'x': int, 'y': int}]): -> int
    pass

对比

def func(points):
    ''' Take a list of dicts, dict present a point, and contain keys:
    'x' - int, x position
    'y' - int, y position
    Return int

    '''
    pass

Answer 1

不，它们是对文档字符串的补充。来自官方函数注释pep：

Because Python's 2.x series lacks a standard way of annotating a function's
parameters and return values, a variety of tools and libraries have appeared to
fill this gap.

但是 Python 社区喜欢标准化事物（参考PEPs）。所以他们想出了函数注解，主要针对第三方库和工具——IDE、代码质量/静态分析工具等。正如PEP自己所说：

By itself, Python does not attach any particular meaning or significance to
annotations.(...)meaning comes from third-party libraries alone.

编辑：可以在这里找到一篇关于注释使用（早期错误检测、代码完成和工具支持）的非常好的文章。