键入和文档字符串中的重复信息？

Question

我对类型提示和文档字符串的使用感到困惑。他们不是重复信息吗？

例如：

def my_func(name: str):
    """
    print a name.
    
    Parameters
    ----------
    name : str
       a given name
    """
    print(name)

信息name: str不是给了两次吗？

Answer 1

将类型作为类型提示和文档字符串的一部分是多余的。它也容易出现人为错误，因为人们很容易忘记更新其中一个，因此需要不断努力使它们保持同步。

type hints 的文档也提到了它：

文档字符串。现有的文档字符串约定基于 Sphinx 表示法 (:type arg1: description)。这非常冗长（每个参数多一行），而且不是很优雅。我们也可以创造一些新的东西，但是注解语法很难被击败（因为它就是为此目的而设计的）。

但这一切都取决于你的用例。

• 如果您正在使用诸如MyPy 之类的静态类型检查器（例如，如果您将一个int 123 传递给具有类型提示str 的变量，它将失败）或诸如PyCharm 之类的IDE（例如它会突出显示类型提示和传递的参数之间的不一致），那么您应该继续使用类型提示。这是最好的方法，因为它指出了您编写的代码中可能存在的错误。
• 如果您使用Sphinx、Swagger 或其他工具，请注意这些工具会显示您的类和方法以及它们的文档字符串以用于文档编制。因此，如果您想维护此类文档以使其他读者清楚了解并希望包含类型，那么您可能也希望将类型提示放入文档字符串中。但是如果你认为不需要这些细节，因为大多数时候只有文档字符串中的描述是相关的，那么就不需要在文档字符串中添加类型提示。

从长远来看，更可持续的方法是让这些工具（Sphinx、Swagger 等）使用类型提示作为文档的一部分，而不是仅仅依赖于文档字符串中的文本。对于 sphinx，我发现这个库 sphinx-autodoc-typehints 已经执行了它。

允许您从这里迁移：

def format_unit(value, unit):
    """
    Formats the given value as a human readable string using the given units.

    :param float|int value: a numeric value
    :param str unit: the unit for the value (kg, m, etc.)
    :rtype: str
    """
    return '{} {}'.format(value, unit)

到这里：

from typing import Union

def format_unit(value: Union[float, int], unit: str) -> str:
    """
    Formats the given value as a human readable string using the given units.

    :param value: a numeric value
    :param unit: the unit for the value (kg, m, etc.)
    """
    return '{} {}'.format(value, unit)

因此，似乎已经对该主题进行了增强，这将使类型的定义更加一致，减少冗余。