Documenter les fonctions Python avec des docstrings

Introduction

Dans ce laboratoire, vous apprendrez l'importance de documenter votre code Python à l'aide de docstrings. Nous explorerons comment accéder aux docstrings existantes pour les fonctions intégrées (built-in functions) en utilisant la fonction help() et l'attribut __doc__.

De plus, vous acquerrez une expérience pratique dans l'écriture de vos propres docstrings pour des fonctions personnalisées et dans la vérification de leur accessibilité, rendant votre code plus compréhensible et maintenable pour vous-même et pour les autres.

Accéder à la documentation avec help()

Une docstring est une chaîne littérale qui apparaît comme la première instruction dans la définition d'un module, d'une fonction, d'une classe ou d'une méthode. Elle est utilisée pour documenter ce que fait le code. La fonction intégrée help() de Python est un excellent outil pour visualiser cette documentation dans un format clair et lisible. La fonction help() est conçue pour une utilisation interactive.

Commençons par visualiser la documentation de la fonction intégrée print().

Tout d'abord, ouvrez un terminal dans le WebIDE. Vous pouvez le faire en cliquant sur le menu Terminal en haut de l'écran et en sélectionnant New Terminal.

Dans le terminal, démarrez l'interpréteur interactif Python en tapant la commande suivante et en appuyant sur Entrée :

python

Vous verrez l'invite Python (>>>). Maintenant, utilisez la fonction help() pour obtenir des informations sur print() :

help(print)

Le terminal affichera la documentation de la fonction print.

Help on built-in function print in module builtins:

print(value, ..., sep=' ', end='\n', file=sys.stdout, flush=False)
    Prints the values to a stream, or to sys.stdout by default.

    Optional keyword arguments:
    file:  a file-like object (stream); defaults to the current sys.stdout.
    sep:   string inserted between values, default a space.
    end:   string appended after the last value, default a newline.
    flush: whether to forcibly flush the stream.

(END)

Cette sortie explique ce que fait la fonction, quels paramètres elle accepte et leurs valeurs par défaut. Appuyez sur la touche q pour quitter la visionneuse d'aide et revenir à l'invite Python.

Maintenant, quittez l'interpréteur interactif Python en tapant :

exit()

Accéder aux docstrings brutes avec __doc__

Bien que help() soit excellent pour une utilisation interactive, vous pouvez également accéder à la docstring brute d'un objet par programmation en utilisant son attribut spécial __doc__. Cet attribut contient la docstring sous forme de chaîne de caractères simple (plain string).

Voyons cela en action. Dans l'explorateur de fichiers du WebIDE à gauche, trouvez et ouvrez le fichier nommé access_docstring.py.

Ajoutez le code Python suivant dans le fichier. Ce code affichera la docstring de la fonction intégrée len().

## This script prints the docstring of the len() function.
print(len.__doc__)

Enregistrez le fichier (vous pouvez utiliser le raccourci Ctrl+S).

Revenez maintenant au terminal et exécutez le script avec la commande suivante :

python access_docstring.py

Le résultat sera la docstring brute de la fonction len.

Return the number of items in a container.

Comme vous pouvez le constater, __doc__ vous donne le contenu textuel direct de la documentation, ce qui peut être utile pour des outils ou des scripts personnalisés qui traitent la documentation.

Écrire une docstring de fonction personnalisée

Documenter ses propres fonctions est une pratique fondamentale pour écrire du code propre et maintenable. Une bonne docstring explique l'objectif de la fonction, ses paramètres et ce qu'elle retourne.

Écrivons une fonction et documentons-la. Ouvrez le fichier my_function.py depuis l'explorateur de fichiers.

Tout d'abord, ajoutez la définition de fonction suivante au fichier :

def greet(name, greeting="Hello"):
    print(f"{greeting}, {name}!")

Maintenant, ajoutons une docstring. La docstring doit être placée immédiatement après la ligne def et être indentée au même niveau que le code de la fonction. Nous utiliserons des triples guillemets ("""...""") pour une docstring multi-lignes.

Modifiez my_function.py pour inclure la docstring. Nous ajouterons également une ligne pour imprimer la docstring afin de vérifier qu'elle fonctionne.

def greet(name, greeting="Hello"):
    """Greets a person with a given message.

    Args:
        name (str): The name of the person to greet.
        greeting (str, optional): The greeting message. Defaults to "Hello".
    """
    print(f"{greeting}, {name}!")

## Print the docstring of our greet function
print(greet.__doc__)

Enregistrez le fichier. Maintenant, exécutez le script depuis votre terminal :

python my_function.py

Vous verrez votre docstring personnalisée s'afficher dans la console.

Greets a person with a given message.

    Args:
        name (str): The name of the person to greet.
        greeting (str, optional): The greeting message. Defaults to "Hello".

Ceci confirme que vous avez réussi à documenter votre fonction et que vous pouvez accéder à sa docstring en utilisant l'attribut __doc__.

Utiliser help() avec votre fonction personnalisée

À l'étape précédente, nous avons accédé à notre docstring personnalisée en utilisant __doc__. Maintenant, utilisons la fonction help() pour obtenir une vue plus soignée et conviviale de notre documentation, tout comme nous l'avons fait pour la fonction intégrée print().

Nous allons importer notre fonction greet dans l'interpréteur interactif Python pour utiliser help().

Dans votre terminal, démarrez à nouveau l'interpréteur Python :

python

Une fois que vous voyez l'invite >>>, importez la fonction greet depuis votre module my_function (le nom du fichier my_function.py est traité comme un module nommé my_function).

from my_function import greet

Maintenant, utilisez help() pour visualiser la documentation de votre fonction greet :

help(greet)

Vous verrez une sortie joliment formatée générée à partir de votre docstring.

Help on function greet in module my_function:

greet(name, greeting='Hello')
    Greets a person with a given message.

    Args:
        name (str): The name of the person to greet.
        greeting (str, optional): The greeting message. Defaults to "Hello".

(END)

Remarquez comment help() inclut automatiquement la signature de la fonction (greet(name, greeting='Hello')) et formate la docstring pour une lecture facile. C'est pourquoi écrire de bonnes docstrings est si précieux — cela s'intègre directement au système d'aide intégré de Python.

Appuyez sur q pour quitter la visionneuse d'aide, puis tapez exit() pour quitter l'interpréteur Python.

Résumé

Dans ce laboratoire, vous avez appris les bases de la documentation du code Python à l'aide des docstrings. Vous vous êtes exercé à accéder à la documentation des fonctions intégrées en utilisant la fonction interactive help() et l'attribut __doc__. Vous avez ensuite appliqué ces connaissances en écrivant vos propres docstrings sur une seule ligne et sur plusieurs lignes pour une fonction personnalisée, en suivant les conventions standard. Enfin, vous avez vérifié que votre documentation personnalisée est accessible à la fois via __doc__ et le système help() de Python, ce qui est une compétence clé pour créer du code lisible, réutilisable et maintenable.