Python 在docstring中使用类型别名

在docstring中使用类型别名或

键入对象是否有最佳实践

这个问题可能会吸引基于意见的答案。但也可能是这样
对于特定的解决方案，存在广泛接受的约定或外部工具支持



示例：函数返回带有字符串键和值的字典。您会在“返回”部分的docstring中输入什么类型？（我正在使用。）

选项1：只需说这是一个命令

import typing

strstrdict = typing.Dict[str, str]

def foo() -> strstrdict:
    '''
    bla bla

    Returns
    -------
    dict
        A dictionary with string keys and values that represents ...
    '''
    # code

选项2：使用类型别名

import typing

strstrdict = typing.Dict[str, str]

def foo() -> strstrdict:
    '''
    bla bla

    Returns
    -------
    strstrdict
        A dictionary with string keys and values that represents ...
    '''
    # code

选项3：将
“typing.Dict[str，str]”
放入docstring

import typing

strstrdict = typing.Dict[str, str]

def foo() -> strstrdict:
    '''
    bla bla

    Returns
    -------
    typing.Dict[str, str]
        A dictionary with string keys and values that represents ...
    '''
    # code

选项4：还有别的吗

编辑1

“我正在使用熊猫风格的文档字符串”您是在寻找这种风格的答案，还是在寻找一般的答案

我想最佳答案应该尽可能涵盖一般情况和具体情况。我提到了
pandas
样式，以明确为什么有一个“Returns”部分，而没有诸如“：param:”之类的指令。我对答案的风格不是一成不变的

您是否确实在文档中包含别名，即用户能否发现别名
strstrdict
是什么

目前没有关于别名的文档。用户可以查看module.strstrdict

。我愿意接受这里的建议

编辑2

我链接到的样式指南碰巧提到了一个带有字符串键和值的dict。我要寻找的答案也应该包括这样的情况：

from typing import Any, Callable, ContextManager, Iterable

ContextCallables = ContextManager[Iterable[Callable[[int, int], Any]]]

def foo() -> ContextCallabes:
    '''
    bla bla

    Returns
    -------
    ???
           some description
    '''
    # code

---

既然您明确提到了您正在遵循的文档样式约定，那么基于意见的答案就不应该存在问题

我们可以查看熊猫文档指南部分，了解：

对于复杂类型，请定义子类型。对于

dict

和

tuple

，由于存在多个类型，我们使用括号帮助读取该类型（对于

dict

使用花括号，对于

tuple

使用普通括号）

这意味着您应该按照以下方式记录

Dict[str，str]

：

Returns
-------
dict of {str : str}
    Some explanation here ...

---

您可以查看更多示例，包括其他类型。

“我使用的是熊猫风格的docstrings”您是在寻找这种风格的答案还是一般的答案？您是否真的在文档中包含别名，即用户能否发现别名

strstrdict

是什么？@MisterMiyagi问题只能询问特定的样式，否则，它们将不得不以基于意见的方式关闭。@对于通过注释/

键入

/别名提供的键入信息，来宾和都不具有权威性（根本不涉及该主题）。将问题限制在这些样式（我不是说这不好）并不能阻止它成为基于意见的（我不是说它是在第一位）。@Mistermiagi我编辑了我的问题以回应您的评论。我认为在文档字符串中包含输入/返回类型的做法早于PEP 484类型，可能需要重新考虑。现在，如果您使用的是类型提示，那么实际上最好完全从docstring中省略类型：它与签名中已有的内容是冗余的。类似地，我希望任何现代文档工具都知道如何使用类型提示/以干净的方式公开它们。例如，sphinx有几个插件（例如）。当然，这只是我的观点。这对于这个例子来说是非常具体的，刚好被样式简短的符号所涵盖。短符号中没有包含的类型呢？比如说一个

ContextManager[Iterable[Callable[[int，int]，Any]]]]

？@MisterMiyagi我认为样式指南仍然很清楚：“如果在Python模块中定义了类型，那么必须指定模块。”。详细信息可在参数文本中解释。因此，对于您的示例，这将是

键入.ContextManager

。现在，如果我们将其粘贴到dict中，并制作类似于

dict[str，ContextManager[…]]

？样式指南提到：“对于复杂类型，定义子类型。”它没有说“…并对每个类型递归地执行此操作。”因此它只需要一个详细级别：

dict of{str:typing.ContextManager}

。更多细节可以参考正文。我看不出样式指南对此有多清楚。本指南仅介绍具体类型，其中包含文字容器的特殊规则以及两个抽象数组like和iterable。没有抽象泛型类型或其别名的概念是通过键入来表示的。@MisterMiyagi本指南包括以下部分：“如果类型是在Python模块中定义的，[…]”。因此，对于要包含在类型定义中的任何类型，都可以检查是否满足此条件。如果将函数注释为

ContextManager[…]

，则由于

ContextManager

是在模块中定义的（

typing

），因此应将其定义为

typing.ContextManager

。另一方面，如果您使用了一个别名

my_alias=ContextManager[…]

，那么这不是在（其他）模块中定义的，因此您可以只使用

my_alias

。使用Sphinx``:data:`my_alias``可以用于链接。这就避开了这个问题。问题不在于

ContextManager[Iterable[Callable[[int，int]，Any]]]

是否应与模块前缀一起使用。问题是它是否应该一字不差地使用（选项3），缩写为无意义的

ContextManager

（选项1），还是与有意义但非通用的

contextalcalables

（选项2）一起使用。对于“样式指南”在一般情况下讨论的所有具体类型，所有选项都是相同的。对于使用抽象、泛型和别名类型的

键入

，情况并非如此。