Docstrings
Écrire des fonctions en Python
Shayne Miel
Software Architect @ Duo Security
Une fonction complexe
def split_and_stack(df, new_names):
half = int(len(df.columns) / 2)
left = df.iloc[:, :half]
right = df.iloc[:, half:]
return pd.DataFrame(
data=np.vstack([left.values, right.values]),
columns=new_names
)
def split_and_stack(df, new_names):
"""Diviser les colonnes d'un DataFrame en deux moitiés, puis
les empiler verticalement et retourner un nouveau DataFrame dont les
noms de colonnes sont `new_names`.
Args:
df (DataFrame): Le DataFrame à diviser.
new_names (iterable of str): Les noms de colonnes du nouveau DataFrame.
Returns:
DataFrame
"""
half = int(len(df.columns) / 2)
left = df.iloc[:, :half]
right = df.iloc[:, half:]
return pd.DataFrame(
data=np.vstack([left.values, right.values]),
columns=new_names
)
Anatomie d'une docstring
def function_name(arguments):
"""
Description de ce que fait la fonction.
Description des arguments, s'il y a lieu.
Description de la valeur de retour, s'il y a lieu.
Description des erreurs levées, s'il y a lieu.
Notes ou exemples d'utilisation facultatifs.
"""
Formats de docstring
- Style Google
- Numpydoc
- reStructuredText
- EpyText
Style Google - description
def function(arg_1, arg_2=42):
"""Description de ce que fait la fonction.
"""
Style Google - arguments
def function(arg_1, arg_2=42):
"""Description de ce que fait la fonction.
Args:
arg_1 (str): Description de arg_1 qui peut se poursuivre sur la ligne
suivante au besoin.
arg_2 (int, optional): Indiquez optional quand un argument a une valeur
par défaut.
"""
Style Google - valeur(s) de retour
def function(arg_1, arg_2=42):
"""Description de ce que fait la fonction.
Args:
arg_1 (str): Description de arg_1 qui peut se poursuivre sur la ligne
suivante au besoin.
arg_2 (int, optional): Indiquez optional quand un argument a une valeur
par défaut.
Returns:
bool: Description facultative de la valeur de retour
Les lignes supplémentaires ne sont pas indentées.
"""
def function(arg_1, arg_2=42):
"""Description de ce que fait la fonction.
Args:
arg_1 (str): Description de arg_1 qui peut se poursuivre sur la ligne
suivante au besoin.
arg_2 (int, optional): Indiquez optional quand un argument a une valeur
par défaut.
Returns:
bool: Description facultative de la valeur de retour
Les lignes supplémentaires ne sont pas indentées.
Raises:
ValueError: Indiquez tout type d'erreur que la fonction lève
intentionnellement.
Notes:
Voir https://www.datacamp.com/community/tutorials/docstrings-python
pour plus d'info.
"""
Numpydoc
def function(arg_1, arg_2=42):
"""
Description de ce que fait la fonction.
Parameters
----------
arg_1 : expected type of arg_1
Description de arg_1.
arg_2 : int, optional
Indiquez optional quand un argument a une valeur par défaut.
Default=42.
Returns
-------
The type of the return value
Peut inclure une description de la valeur de retour.
Remplacez « Returns » par « Yields » si cette fonction est un générateur.
"""
Récupérer des docstrings
def the_answer(): """Return the answer to life, the universe, and everything. Returns: int """ return 42print(the_answer.__doc__)
Return the answer to life,
the universe, and everything.
Returns:
int
import inspect
print(inspect.getdoc(the_answer))
Return the answer to life,
the universe, and everything.
Returns:
int
Passons à la pratique !
Écrire des fonctions en Python
