Cómo especificar diferentes tipos de retorno en la cadena de documentación de Python

Actualmente estoy escribiendo documentación para mi paquete de Python usando Sphinx y el complemento autodoc. Para un valor de retorno de una función, por ejemplo, puedo escribir :returns: int: count que le dice a sphinx que hay un valor de retorno de tipo int, conteo llamado

Ahora tengo una función que me permite predecesores de elementos en mi base de datos:

 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 

Como puede ver, recupera el elemento original y devuelve una instancia de la clase AlphaRelease , BetaRelease o VRelease según el contenido del name de campo de los elementos.

¿Cuál es la mejor práctica para definir un valor de retorno con varios tipos posibles en la cadena de documentos?

De la documentación de Sphinx :

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

También podría beneficiarse de:

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

Entonces, como un ejemplo:

 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 

Desafortunadamente, no hay una opción estricta o canónica en la gramática y el vocabulario de Sphinx para múltiples tipos de devolución. A menudo, uno GenericRelease un GenericRelease de todos los tipos que podrían devolverse, si existiera uno ( GenericRelease por ejemplo). Pero Python se encuentra en este momento, en su era de mediados a finales de Python 3, definiendo una notación de tipo más rica. El módulo de escritura define una nueva gramática en evolución para tales tipos, independientemente de las antiguas definiciones de Sphinx. Si desea utilizar este estándar emergente, puede intentar algo como:

 :rtype: Union[AlphaRelease, BetaRelease, VRelease]