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

Question

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

例如：

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

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

Answer 1

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

type hints 的文档也提到了它：

Docstrings. There is an existing convention for docstrings, based on the Sphinx notation (:type arg1: description). This is pretty verbose (an extra line per parameter), and not very elegant. We could also make up something new, but the annotation syntax is hard to beat (because it was designed for this very purpose).

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

如果您正在使用静态类型检查器，例如 MyPy (e.g. it would fail if you passed an int 123 to a variable with type hint str) or an IDE such as PyCharm（例如，它会突出显示类型提示和传递的参数之间的不一致），那么您应该继续使用类型提示。这是更好的方法，因为它会指出您编写的代码中可能存在的错误。
如果您使用的是 Sphinx, or Swagger 等工具或其他工具，请注意这些工具会显示您的类和方法及其文档字符串以供记录之用。因此，如果您想维护此类文档以便其他读者清楚并希望包含这些类型，那么您可能还想将类型提示放在文档字符串中。但是如果你认为不需要这样的细节，因为大多数时候只有文档字符串中的描述是相关的，那么就没有必要在文档字符串中添加类型提示。

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

Allowing you to migrate from this:

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)

to this:

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)

因此，似乎已经有关于此主题的增强功能，将使类型的定义更加一致且冗余更少。

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

duplicate information in typing and docstring?

python

docstring

type-hinting

python-typing