How to document limited values of input parameter in Docstring

Question

I have a function that accepts only accepts some limited values for the input parameter provider. Specifically, it only accepts the values provider_a, provider_b and provider_c. What is the best way to document the possible values of this parameter in Python Docstring?

This is what I've tried so far:

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

score 2 · Accepted Answer · answered Jun 03 '22 at 12:02

If you want to stick to docstring-only ways, your wording is pretty good; instead of the unspecific "some", I would opt to authoritatively state "the following" possible values.

But as usual, such docstrings tend to become stale fast. Instead, you might want to investigate changing the type of argument provider from str to either a lightweight Enum (see Enums in Python: How to enforce in method arguments for an old but relevant example), or even make your providers distinct classes (with an abstract Provider parent class).

How to document limited values of input parameter in Docstring

1 Answers1