How To Specify Different Return Types In Python Docstring

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

Solution 1:

From the Sphinx documentation:

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

You might also benefit from:

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

So, as one example:

defget_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]