Chapitre 1: Modules et documentation

Jusqu'à maintenant, nous avons toujours programmé au sein d'un seul fichier (ou script). Cependant, lorsqu'on souhaite rédiger des programmes plus longs, il est souhaitable de séparer le code dans plusieurs fichiers. Chaque fichier est appelé un module et les définitions d'un module peuvent être importées dans un autre module grâce au mot-clé import.

Utilisation des modules

Lorsqu'on utilise Python, certaines fonctionnalités sont présentes par défaut, comme les fonctions print() et round().

Par contre, pour certaines fonctionnalités jugées moins «indispensables», il est nécessaire d'importer des modules de code qui vont permettre de rajouter les fonctionnalités souhaitées.

On a par exemple déjà utilisé les modules math ou random, nous allons dans cet exemple utiliser le module statistics moins connu ajouté à partir de la version 3.4 de Python.

# import du module
import statistics
# affiche l'aide
help(statistics)

Supposons que l'on souhaite utiliser les fonctions mean() moyenne et stdev() :écart-type. Plusieurs solutions s'offrent à nous:

1. Import du module et utilisation de son espace de noms avec une notation pointée(avec un point entre le nom du module et le nom de la fonction).

import statistics
notes = [11, 14, 18, 5, 12, 13, 15]
print("Moyenne:", statistics.mean(notes))
print("Écart-type:", statistics.stdev(notes))

SORTIE

Moyenne: 12.571428571428571
Écart-type: 4.035556254807296

On peut aussi renommer l'import avec le mot-clé as pour rendre le code plus lisible.

import statistics as stat
notes = [11, 14, 18, 5, 12, 13, 15]
print("Moyenne:", stat.mean(notes))
print("Écart-type:", stat.stdev(notes))

2. Vous pouvez également n'importer que les fonctions dont vous avez besoin.

from statistics import mean, stdev
notes = [11, 14, 18, 5, 12, 13, 15]
print("Moyenne:", mean(notes))
print("Écart-type:", stdev(notes))

3. Une autre méthode cependant déconseillée en raison de la pollution de l'espace des noms(de variables) est l'utilisation du * (wildcard, joker en anglais).

from statistics import *
# Toutes les objets du module sont disponibles sans notation pointée
notes = [11, 14, 18, 5, 12, 13, 15]
print("Moyenne:", mean(notes))
print("Écart-type:", stdev(notes))

Notre premier module

Nous allons créer un premier module dans un fichier fibo.py qui permet générer les nombres de la suite de Fibonacci.

La suite de Fibonacci est une suite de nombres entiers définie par récurrence.

Les deux premiers termes sont 0 et 1, puis un terme est la somme des deux termes précédents.

On obtient ainsi les nombres dits de Fibonacci: 0, 1, 1, 2, 3, 5, 8, 13, 21...

La définition mathématique est:

# Module sur les nombres de Fibonacci

def fib(n):    # affiche les nombres de Fibonacci jusqu'à n
    a, b = 0, 1
    while a < n:
        print(a, end=' ')
        a, b = b, a+b
    print()

def fib2(n):   # renvoie la liste des nombres de Fibonacci jusqu'à n
    result = []
    a, b = 0, 1
    while a < n:
        result.append(a)
        a, b = b, a+b
    return result

Si le module est correctement installé ou tout simplement présent dans le même dossier que celui ou vous exécutez python (cwd: Current Working Directory_).

On importe le module sous le nom fibo en python, l'extension ne doit pas être précisée.

Les imports fonctionnent comme d'habitude.

• Soit en important le module directement et en utilisant des notations pointées;

  import fibo
  fibo.fib(1000)
  # affiche 0 1 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987
  fibo.fib2(100)
  # renvoie [0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89]

• soit en important spécifiquement des fonctions pour pouvoir les utiliser sans rappeler le module d'origine.

  from fibo import fib, fib2
  fib(1000)
  # affiche 0 1 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987
  fib2(100)
  # renvoie [0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89]

Documentation et commentaires

Nous avons déjà vu en première comment prototyper des fonctions pour décrire le rôle de la fonction, le type des paramètres et le type de la valeur de retour. C'est ce que l'on appelle une docstring.

Les docstrings sont utilisées pour afficher les documentations en ligne ou directement dans Python avec la fonction help()

Pour documenter un module, il suffit de créer la docstring au début du fichier en utilisant les chaines de caractères multilignes délimitées par """, pour une lecture aisée on limite souvent le nombre de caractères par ligne à 80(ou 100 suivant les projets).

Si on prend l'exemple précédent on pourrait le documenter avec une description générale au début du module ainsi qu'une liste des fonctions, et en pensant à documenter également les fonctions bien sûr.

Les fonctions ont également été renommées pour être plus explicites:

• fib: fib_print
• fib2: fib_to_array

""" Module fibo relatif à la création de nombres de Fibionacci

Pour rappel, la suite de Fibonacci est une suite d'entiers dans laquelle chaque terme est la somme 
des deux termes qui le précèdent.(voir: https://fr.wikipedia.org/wiki/Suite_de_Fibonacci)

Ce module présente deux fonctions:

- fib_print: affiche les nombres de Fibionacci
- fib_to_array: renvoie la liste des nombres de Fibionacci

"""

def fib_print(n):
    """Affiche les nombres de Fibionacci

    Arguments
    ---------
    n: int
        dernier rang de la suite de Fibonacci affiché
    """
    a, b = 0, 1
    while a < n:
        print(a, end=' ')
        a, b = b, a+b
    print()

def fib_to_array(n):
    """Renvoie la liste des nombres de Fibionacci

    Arguments
    ---------
    n: int
        dernier rang de la suite de Fibonacci renvoyé dans la liste
    
    Returns
    -------
    list
        La liste des nombres de Fibionnaci jusqu'au rang n
    """
    result = []
    a, b = 0, 1
    while a < n:
        result.append(a)
        a, b = b, a+b
    return result

Annotations de types

Depuis la version 3.5, Python propose des annotations de types dans les fonctions.

def dit_bonjour(nom: str) -> str:
    return 'Bonjour ' + nom

On peut ainsi rendre plus compacte la documentation de nos fonctions.

API (Application Programming Interface)

Lorsqu'un projet grandit, il y a de plus en plus de personnes qui doivent travailler dessus et l'utiliser et il devient de plus en plus complexe à comprendre. C'est pour cela qu'une bonne documentation est indispensable, mais aussi une bonne organisation du code afin de le rendre plus facile à utiliser.

Il conviendra de bien organiser les divers modules et fonctions accessibles, ce qu'on appelle l'API.

La liste des fonctions disponibles dans l'API est disponible avec la fonction dir().

import math
dir(math)

['__doc__', '__file__', '__loader__', '__name__', '__package__', '__spec__', 'acos', 'acosh', 'asin', 'asinh', 'atan', 'atan2', 'atanh', 'ceil', 'comb', 'copysign', 'cos', 'cosh', 'degrees', 'dist', 'e', 'erf', 'erfc', 'exp', 'expm1', 'fabs', 'factorial', 'floor', 'fmod', 'frexp', 'fsum', 'gamma', 'gcd', 'hypot', 'inf', 'isclose', 'isfinite', 'isinf', 'isnan', 'isqrt', 'lcm', 'ldexp', 'lgamma', 'log', 'log10', 'log1p', 'log2', 'modf', 'nan', 'nextafter', 'perm', 'pi', 'pow', 'prod', 'radians', 'remainder', 'sin', 'sinh', 'sqrt', 'tan', 'tanh', 'tau', 'trunc', 'ulp']

def _privée():
    print("Je suis cachée et n'apparait pas dans la documentation")