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

Question

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

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

Related question

---

示例：函数返回带有字符串键和值的字典。您会将什么类型放入“返回”部分下的文档字符串中？ （我使用的是pandas style docstrings。）

选项 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 风格的文档字符串”您是在寻找这种风格的答案还是一般的答案？

我想最佳答案将尽可能涵盖一般情况和具体情况。我提到了pandas 样式，以明确为什么有“返回”部分而没有像“:param:”这样的说明。关于答案，我并没有死心塌地。

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

目前没有关于别名的文档。用户可以查看themodule.strstrdict。我愿意在这里接受建议。

编辑 2

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

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

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

我们可以查看关于parameter types 的pandas 文档字符串指南部分：

对于复杂类型，定义子类型。对于dict 和tuple，由于存在不止一种类型，我们使用方括号来帮助读取类型（dict 是大括号，tuple 是普通括号）。

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

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

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