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

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

"I am using pandas style docstrings" Are you looking for answer for just this style or in general?

我想最佳答案将尽可能涵盖一般和特定情况。我提到了 pandas样式来说明为什么有一个“返回”部分，而没有像“:param:”这样的说明。我对答案的风格并没有死心塌地。

Do you actually include the aliases in your documentation, i.e. can users discover what the alias strstrdict is?

目前没有关于别名的文档。用户可以查看 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 文档字符串指南部分:

For complex types, define the subtypes. For dict and tuple, as more than one type is present, we use the brackets to help read the type (curly brackets for dict and normal brackets for tuple).

这意味着您应该记录 Dict[str, str]如下:

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

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