How to specify different return types in python docstring

Question

I'm currently writing documentation for my python package using Sphinx and the autodoc plugin. For a function return value I can e.g. write :returns: int: count which tells sphinx that there is a return value of type int, named count.

I now got a function which gets me predecessors of items in my database:

def get_previous_release(release_id):
    """ Holt Vorgängeritem eines Items mit der ID release_id

        :param release_id: ID des items für das Release
        :type release_id: int

    """

    if not isinstance(release_id, int):
        raise ValueError('get_previous_release expects an Integer value for the parameter release_id')

    try:
        release = my_queries.core.get_by_id(release_id)
    except IndexError:
        raise LookupError('The item with id {} could no be found'.format(release_id))

    if 'Alpha-Release' in release.name:
        release = AlphaRelease(release.key, release.name, release.state)
    elif 'Beta-Release' in release.name:
        release = BetaRelease(release.key, release.name, release.state)
    elif '-Release' in release.name:
        release = VRelease(release.key, release.name, release.state)
    else:
        raise TypeError('The item with the id {} does not contain \'-Release\' in the Summary ' + \
                        'and is therefore not considered a Release')

    previous_release = release.get_predecessor()

    if not previous_release:
        raise LookupError('Could not find a predecessor for item with id {}'.format(release_id))

    return previous_release

As you can see, it fetches the original item and either returns an instance of class AlphaRelease, BetaRelease or VRelease depending on the content of the field name of the items.

What is best practice to define a return value with various possible types in the docstring?

Answer 1

From the Sphinx documentation:

returns, return: Description of the return value.
rtype: Return type. Creates a link if possible.

You might also benefit from:

raises, raise, except, exception: That (and when) a specific exception is raised.

So, as one example:

def get_previous_release(release_id):
    """ 
    Holt Vorgängeritem eines Items mit der ID release_id

    :param release_id: ID des items für das Release
    :type release_id: int
    :returns: appropriate release object
    :rtype: AlphaRelease, BetaRelease, or VRelease
    :raises ValueError: if release_id not an int
    :raises LookupError: if given release_id not found
    :raises TypeError: if id doesn't reference release
    """
    ... # your code here

Unfortunately there is not a strict or canonical choice in the Sphinx grammar and vocabulary for multiple return types. Often one would state a super-type of all the types that might be returned, if one existed (GenericRelease e.g.). But Python is just now, in its mid- to late-Python 3 era, defining a richer type notation. The typing module defines an evolving new grammar for such types independent of the old Sphinx definitions. If you wished to use this emerging standard, you might try something like:

:rtype: Union[AlphaRelease, BetaRelease, VRelease]