在文档字符串中编写“a 或 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 数组，

np.array

有：

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

对于

np.zeros

，你得到：

shape : int or tuple of ints

而且

typing.Union

也肯定经常被使用。

所有这些都相当正确，这些pandas和numpy用途被认为更常见。

Answer 2

我总是会使用 typehint 中的 Union 类，如下所示：

from typing import Union

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

´´´

Answer 3

为了将来参考，这里是

docstring

中“

cheat sheet

或

a

”类型提示的 b，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'".