在文档字符串中使用类型别名

Question

是否有在文档字符串中使用类型别名或typing对象的最佳实践？

这个问题可能会吸引基于观点的答案。但也可能对于特定的解决方案，有一个被广泛接受的约定或外部工具支持。

相关问题

---

示例：函数返回一个包含字符串键和值的字典。您会在"返回"部分下的文档字符串中放入什么类型？(我使用的是熊猫风格的文档字符串。(

选项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]"放入文档字符串中。

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是什么？

目前没有关于别名的文档。用户可以查看themodule.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

Answer 1

由于您明确提到了所遵循的文档样式约定，因此基于意见的答案应该不会有问题。

我们可以查看pandas文档字符串指南中关于参数类型的部分：

对于复杂类型，请定义子类型。对于dict和tuple，由于存在多个类型，我们使用括号来帮助读取类型(大括号用于dict，普通括号用于tuple(。

这意味着您应该按如下方式记录Dict[str, str]：

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

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