如何记录 Docstring 中输入参数的有限值

Question

我有一个函数只接受一些有限的输入参数值 provider。具体来说，它只接受值 provider_a、provider_b 和 provider_c。在 Python Docstring 中记录此参数的可能值的最佳方法是什么？

这是我目前尝试过的方法：

def my_func(provider: str) -> str:
    """ Sample function description goes here
    :param str provider: Provider parameter that only accepts some possible values. Possible values:
        - 'provider_a': Description of provider_a
        - 'provider_b': Description of provider_b
        - 'provider_c': Description of provider_c
    :return: provider passed as input
    :rtype: str
    """

    # DO SOMETHING

    return provider

Answer 1

如果你想坚持docstring-only的方式，你的措辞很好；而不是不具体的“一些”，我会选择权威地陈述“以下”可能的值。

但像往常一样，此类文档字符串往往很快就会过时。相反，您可能想研究将参数 provider 的类型从 str 更改为轻量级枚举（有关旧但相关的示例，请参见 ），或者甚至使您的提供者与众不同 classes（有一个抽象的 Provider 父级 class）。