How to specify different return types in python docstring
I am currently writing documentation for my python package using Sphinx and the autodoc plugin. For the return value of a function, I can, for example, write :returns: int: count
that tells sphinx that there is a return value of type int, named count.
Now I have a function that returns me the predecessors of the 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 element and returns an instance of the class AlphaRelease
, BetaRelease
or VRelease
depending on the content of the name
elements field .
What is the best practice for defining a return value with different possible types in a docstring?
source to share
From Sphinx Documentation :
returns, return: Description of the return value.
rtype: Return type. Creates a link if possible.
You can also use:
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 no strict or canonical choice in Sphinx grammar and vocabulary for multiple return types. It is often possible to specify the supertype of all types that can be returned if they exist ( GenericRelease
eg.). But Python is only now, in its mid-to-late Python 3 era, defining clearer type notation. The module defines a new grammar for these types, independent of the old Sphinx definitions. If you want to use this new standard, you can try something like:
:rtype: Union[AlphaRelease, BetaRelease, VRelease]
source to share