Tutoriel python niveau intermédiaire / tuto LA DOCUMENTATION

Bienvenue dans le tutoriel python niveau intermédiaire numéro 6.

LE PROBLÈME DOCUMENTAIRE

Le nombre de fonctions définies dans les différents modules Python est énorme, et ne cesse d’augmenter à chaque nouvelle version du langage. Comme vous le savez, chaque module regroupe des fonctions et des constantes liées entre elles (par exemple des fonctions mathématiques, pour les chaînes, pour gérer l’heure et la date, etc.).

Mais pour utiliser ces fonctions il faut se rappeler, pour chacune d’elles, le nombre de paramètres à indiquer dans l’appel, la valeur retournée, les éventuelles exceptions que cela peut provoquer… bref, même un programmeur expert ne pourra jamais pour se souvenir de toutes ces choses en mémoire, et devra souvent consulter une documentation qui lui rappelle rapidement les paramètres de chaque fonction. Pour cela, il existe différents sites qui donnent les soi-disant références, c’est-à-dire des listes détaillées de chaque fonction du langage avec l’explication relative de son comportement.

Les programmeurs Python ont décidé d’adopter une approche différente à ce problème, qui consiste à inclure la documentation dans le langage lui-même. Par exemple, essayons d’importer un module dans IDLE : en écrivant

help(nome_modulo)
une longue chaîne apparaîtra qui explique d’abord le nom du module, puis répertorie une par une toutes les fonctions contenues avec une explication de ce que fait chaque fonction et la signification de ses paramètres. Ceci est un exemple (je n’ai signalé que les premières lignes, toute la chaîne est très longue):

>>> import time
>>> help (time)

Help on built-in module time:

NAME
     time - This module provides various functions to manipulate time values.

DESCRIPTION
     There are two standard representations of time. One is the number
     of seconds since the Epoch, in UTC (a.k.a. GMT). It may be an integer
     or a floating point number (to represent fractions of seconds).
     The Epoch is system-defined; on Unix, it is generally January 1st, 1970.
     The actual value can be retrieved by calling gmtime (0).

Écrire à la place

help(nom_fonction)

(juste le nom de la fonction, sans les crochets nécessaires à l’appel), nous obtiendrons une chaîne plus courte avec les arguments de la fonction uniquement. Par exemple:

>>> help(time.sleep)
       
Help on built-in function sleep in module time:

sleep(...)
    sleep(seconds)
    
    Delay execution for a given number of seconds.  The argument may be
    a floating point number for subsecond precision.

Imaginons maintenant que vous êtes un programmeur professionnel et écrivez une série de fonctions qui devront ensuite être utilisées par d’autres. Nous devons également documenter notre code, sinon les personnes qui utiliseront nos fonctions devront continuellement nous contacter pour toute clarification. Mais un programmeur Python s’attend à pouvoir obtenir de l’aide sur n’importe quelle fonction simplement en tapant help (nom_fonction). Comment pouvons nous faire?

LES DOCUMENTS

Pour documenter une fonction, Python profite astucieusement du fait qu’une instruction ne contenant qu’une seule constante (sans aucune opération ni affectation) est parfaitement légale mais n’a aucun effet. Par exemple, dans un programme, nous pourrions insérer, dans n’importe quelle position, des lignes de code comme celles-ci :

100000000
"Bonjour; salut"

(évidemment correctement indenté) : ce code n’aurait aucun effet sur le programme, mais il ne causerait aucune erreur.

Une docstring est une chaîne (éventuellement sur plusieurs lignes) écrite comme première instruction dans un module, dans la définition d’une fonction ou d’une classe. Cette chaîne sera affichée par Python en tapant help (nom_fonction). Définissons, à titre d’exemple, une fonction simple dans IDLE (lorsque vous appuyez sur ENTREE après la première ligne, Python comprend que la définition continue dans les lignes suivantes : ajustez l’indentation et continuez, appuyez sur ENTREE sur une ligne vide pour terminer la définition) :

>>> def double(num):
 """Returns the double of num"""
 return num * 2


>>>

Maintenant, nous demandons de l’aide sur la fonction que nous venons de définir, et nous voyons que IDLE répond avec la docstring que nous avons saisie :

>>> help(double)        
 
Help on function double in module __main__:

double(num)
    Returns the double of num

Si vous programmez comme passe-temps, vous n’aurez probablement jamais besoin d’écrire des docstrings, mais cela devient une nécessité (avec les règles « d’étiquette » appropriées que nous verrons dans le paragraphe suivant) si vous voulez faire connaître votre travail à la communauté de programmation , car personne ne serait prêt à vous casser la tête pour comprendre ce que fait votre code, et donc vous seriez considéré comme non professionnel. Bien sûr, écrire en anglais est également essentiel !

CONVENTIONS

Les programmeurs Python se sont donné des règles qui tentent de normaliser l’écriture des docstrings. Pour les experts c’est le document officiel pour faire référence à la PEP 257 – Docstring Conventions, ici je ne ferai qu’un bref résumé sur la façon de commenter les fonctions et les modules

• Les docstrings doivent toujours être écrites entre guillemets triples «  » « String » «  », afin d’être immédiatement reconnaissables en tant que telles ;
• Dans des cas très simples, une docstring peut occuper une seule ligne (max 72 caractères pour la lisibilité), avec une description concise de ce qu’elle décrit ;

"""This is a very simple docstring"""

• Sinon la docstring doit être développée sur plusieurs lignes, et avoir ce format : une première ligne de description concise, puis une ligne vide et enfin la description détaillée. Cette subdivision (en anglais bref / détaillé) est adoptée par de nombreux programmes qui génèrent automatiquement la documentation, en utilisant les mémoires pour compiler un index de liens qui font référence au détail respectif et conduiraient donc ces programmes à se confondre s’ils ne sont pas adoptés ;

"""This is the brief description

This is the detailed description, which explains all you want to know.
It can span many
many,
many lines of code"""

Toutes les lignes d’une docstring multiligne doivent être en retrait au même niveau que les trois guillemets de tête. Certains utilisent (mais pas obligatoire) pour fermer le docsring avec une ligne vide et des guillemets sur la ligne suivante.

def func():
    """This is the brief description

    This is the detailed description, which explains all you want to know.
    It can span many
    many,
    many lines of code"""

• Dans les descriptions il ne faut pas commencer par inclure le sujet (par exemple « Cette fonction… ») mais commencer directement par le verbe. La description d’une fonction doit contenir les significations (et les types) de ses paramètres, la valeur de retour et toutes les exceptions levées par la fonction.

NOUS CRÉONS UN MODULE DE TEST

Comme exercice final, nous créons notre propre module en le documentant avec les docstrings. Ouvrez l’éditeur de fichiers et écrivez ces lignes de code :

"""This is a sample module showing how docstrings work

It contains two documented functions and nothing else.
This was done for didactic purposes"""


def double(num):
    """Returns the double of num"""

    return 2 * num


def hypotenuse(s1, s2):
    """Returns the hypotenuse of a right triangle

    s1, s2 are the other two sides of the triangle.
    It uses the Pythagorean theorem"""

    return (s1 ** 2 + s2 ** 2) ** 0.5

Enregistrez le fichier sous sampledoc.py, puis essayez de l’importer depuis IDLE, en appelant help() avec le nom du module et le nom des différentes fonctions.

>>> import sampledoc

>>> help(sampledoc) 
 
Help on module sampledoc:

NAME
    sampledoc - This is a sample module showing how docstrings work

DESCRIPTION
    It contains two documented functions and nothing else.
    This was done for didactic purposes

FUNCTIONS
    double(num)
        Returns the double of num
    
    hypotenuse(s1, s2)
        Returns the hypotenuse of a right triangle
        
        s1, s2 are the other two sides of the triangle.
        It uses the Pythagorean theorem

FILE
    c:\users\nicola\python\sampledoc.py