在 docstring 中编写 "a or b" 类型提示的_正确_方法是什么？

Question

我有一个参数是“E”或“H”。

def my_func(name):
    """
    Parameters
    ----------
    name : str
    """

要指定它是 'E' 或 'H' 我看到有人写道：

    name : {'E', 'H'}

    name : ['E', 'H']

    name : ['E' | 'H']

    name : Union['E', 'H']

    name : 'E' or 'H'

或者，将它们放在第二行：

    name : str
        {'E', 'H'}

    name : str
        ['E', 'H']

    name : str
        ['E' | 'H']

    name : str
        Union['E', 'H']

    name : str
        'E' or 'H'

以上哪一项正确?

如果是int或float，下列哪一项是正确的？

  param : int or float

  param : Union[int, float]

  param : [int | float]

  param : {int, float}

Answer 1

恕我直言，没有正确的方式，但据我所知，pandas使用了很多这些方式。

对于pd.DataFrame.apply，有：

axis : {0 or ‘index’, 1 or ‘columns’}, default 0

result_type : {‘expand’, ‘reduce’, ‘broadcast’, None}, default None

对于pd.DataFrame.aggregate：

func : function, str, list or dict

对于 numpy array, np.array 有：

order : {‘K’, ‘A’, ‘C’, ‘F’}, optional

对于 np.zeros 你得到了：

shape : int or tuple of ints

而且typing.Union肯定也是经常用到的

所有这些都相当正确，这些 pandas 和 numpy 的使用被认为更多普通.

Answer 2

为了将来参考，这是 docstring 中“a 或 b”类型提示的 cheat sheet 被 pycharm 正确识别 以检查传递参数时的不一致性：

name : str or dict
name : str, dict
name : str | dict
name : {str or dict}
name : {str, dict}
name : {str | dict}

name : 'E', 123   # recognized as str or int
name : {'E', 123}  # recognized as str or int

name : list[float or dict]
name : list[float, dict]  # this will be understood as a list of a float and a dict, not as List[Union[float, dict]]
name : list[float | dict]

以下pycharm无法正确处理：

name : [str or dict]
name : [str, dict]
name : [str | dict]
name : Union[str, dict]

name : 'E' or 123
name : 'E' | 123
name : {'E' or 123}
name : {'E' | 123}
name : ['E' or 123]
name : ['E', 123]  # recognized as int
name : ['E' | 123]

list{float or dict}
list{float, dict}  # recognized as dict
list{float | dict}
list of ***  # No matter what you put here, e.g. list of {int, float}, it won't be corrected processed.#

# none of the expressions I can come up with can express "list of elements that are either 123 or 'abc'".

Answer 3

我总是会像这样从类型提示中使用 Union class：


from typing import Union

def my_func(name: Union[a, b]):
    """
    Parameters
    ----------
    name : a | b
    """
    pass

´´´

在 docstring 中编写 "a or b" 类型提示的_正确_方法是什么？

what is the _correct_ way to write "a or b" kind of type hints in docstring?

python

docstring

typing

python-typing