Comment exprimer plusieurs types pour un seul paramètre ou une valeur de retour dans des docstrings traitées par Sphinx?
Parfois, une fonction en Python peut accepter un argument d'un type flexible. Ou elle peut renvoyer une valeur d'un type flexible. Maintenant, je ne me souviens pas d'un bon exemple d'une telle fonction en ce moment, par conséquent, je montre à quoi peut ressembler une telle fonction avec un exemple de jouet ci-dessous.
Je veux savoir comment écrire des docstrings pour de telles fonctions en utilisant la notation de documentation Sphinx. Dans l'exemple ci-dessous, les arguments peuvent être soit str ou int. De même, il peut renvoyer str ou int.
J'ai donné un exemple de docstrings (à la fois dans la notation Sphinx par défaut ainsi que dans la notation Google comprise par l'extension napoleon de Sphinx). Je ne sais pas si c'est la bonne façon de documenter les types flexibles.
Notation par défaut de Sphinx:
def add(a, b):
"""Add numbers or concatenate strings.
:param int/str a: String or integer to be added
:param int/str b: String or integer to be added
:return: Result
:rtype: int/str
"""
pass
Notation Google Sphinx Napoléon:
def add2(a, b):
"""Add numbers or concatenate strings.
Args:
a (int/str): String or integer to be added
b (int/str): String or integer to be added
Returns:
int/str: Result
"""
pass
Quelle est la bonne façon d'exprimer plusieurs types de paramètres ou de retourner des valeurs dans des docstrings destinés à être traités par Sphinx?
Conseils de type Python 3.5 Union
https://docs.python.org/3/library/typing.html#typing.Union
Pour l'instant, je recommande d'utiliser la même syntaxe exacte que ce module, qui:
- rendre le portage plus facile et éventuellement automatisable plus tard
- spécifie une manière canonique bien définie unique de faire les choses
Exemple:
def f(int_or_float):
"""
:type int_or_float: Union[int, float]
:rtype: float
"""
return int_or_float + 1.0
Ensuite, lorsque vous aurez 3.5, vous écrirez juste:
def f(list_of_int : Union[int, float]) -> float:
return int_or_float + 1.0
Je pense qu'il a déjà un support de génération de documentation, mais je ne l'ai pas encore testé: https://github.com/sphinx-doc/sphinx/issues/1968