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

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

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

相关问题

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

选项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]" 选项 4

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

：其他内容？ 编辑 1

“我正在使用 pandas 样式文档字符串”您是否正在寻找此样式或中的答案一般？

我想最佳答案将尽可能涵盖一般情况和具体情况。我提到

样式是为了明确为什么有“Returns”部分并且没有像“:param:”这样的指令。我对答案的风格并没有死心塌地。 pandas 您实际上在文档中包含别名吗，即用户可以发现别名

是什么吗？ strstrdict 当前没有关于别名的文档。用户可以查看

我愿意在这里接受建议。 themodule.strstrdict 编辑 2

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

The style guide I linked to coincidentally mentions a dict with string keys and values. The answer I am looking for should also cover cases like this:

from typing import Any, Callable, ContextManager, Iterable

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

def foo() -> ContextCallabes:
    '''
    bla bla
    
    Returns
    -------
    ???
           some description
    '''
    # code

我将把我的意见和其他人的意见集中在一起，提出我认为是 Python 文档字符串中类型提示的最佳实践：

一般来说，在文档字符串中尽量使用简单易懂的类型描述。

• 文档字符串面向的是 用户 ，他们可能不熟悉或不需要你的代码库中使用的特定类型别名。 重点应该放在传达 是什么 类型的信息，而不是它在你的代码中是如何表示的。
• 像 dict 、 list 或 str 这样的简单类型通常就足够了。
• 对于更复杂的类型，请使用简洁的描述。例如，不要使用 typing.Dict[str, typing.Tuple[int, int]] ，而应使用 "一个字典，将字符串键映射到表示坐标的整数元组"。

什么时候在文档字符串中使用类型别名：

• 当类型别名是公开 API 的一部分并且有文档记录时。 在这种情况下，用户可以通过查看别名的文档来了解有关该类型的更多信息。然后，你可以在文档字符串中链接到别名。
• 当类型特别复杂并且简短描述不足以解释时。 即使在这种情况下，你也可以考虑在文档字符串中添加对类型别名的解释。

回到你的例子：

我会选择选项 1 或其变体：

import typing

strstrdict = typing.Dict[str, str]

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

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

• 它清楚地传达了返回类型，而不会用不必要的细节使用户感到困惑。
• 如果 strstrdict 有文档记录并且是你的公共 API 的一部分，你可以在 "Returns" 部分添加一个指向它的链接。

对于像 ContextCallables 这样的更复杂的例子，简洁和清晰是关键：

from typing import Any, Callable, ContextManager, Iterable

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

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

    Returns
    -------
    ContextManager
        A context manager that yields an iterable of callables. 
        Each callable takes two integers as arguments and returns Any.
    '''
    # code

请记住，目标是让你的文档对使用你的代码的人来说易于理解和使用。如果对类型提示有疑问，最好是错误地更详细而不是更简洁。