Chapitre 1: Modules et documentation
![](../../images/640px-PyPI_logo.svg.png)
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
.
1 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.
Supposons que l’on souhaite utiliser les fonctions mean()
moyenne et stdev()
:écart-type. Plusieurs solutions s’offrent à nous:
- 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))
- 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))
- 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))
2 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;
-
soit en important spécifiquement des fonctions pour pouvoir les utiliser sans rappeler le module d’origine.
3 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 docstring
s 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
4 Annotations de types
Depuis la version 3.5, Python propose des annotations de types dans les fonctions.
Cette fonction prend en paramètre un nom de type chaîne de caractères str
et renvoie également
une chaine de caractères str
.
On peut ainsi rendre plus compacte la documentation de nos fonctions.
5 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()
.
SORTIE
['__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']