Modules, bibliothèques, API et documentation

Donner une responsabilité à chaque module

Un module Python est notamment un fichier qui regroupe des définitions utiles. On peut séparer la lecture de données, les calculs et leur présentation. Chaque partie reçoit des informations par une interface explicite. Cette séparation permet de tester les calculs sans lancer une interface graphique ni lire un vrai fichier à chaque essai.

Le découpage doit suivre des responsabilités cohérentes. Créer un fichier pour chaque ligne n’améliore pas la compréhension. À l’inverse, un module qui lit, calcule, affiche et modifie des variables globales rend les dépendances difficiles à suivre. Une bonne question est : quelle fonction ce composant rend-il aux autres ?

Pour un projet de mesures, la lecture peut convertir les champs d’un CSV en nombres ; le calcul reçoit ensuite une liste numérique déjà validée ; l’affichage reçoit des indicateurs. Une dépendance utile se dessine par une flèche entre ces responsabilités. Une variable globale partagée contournerait cette interface et rendrait les tests moins autonomes.

Lire ce que l’API garantit

Une API est un ensemble d’opérations mises à disposition avec leurs règles d’usage. La documentation précise les noms, les paramètres, leurs types ou domaines, le résultat et les effets observables. Pour une fonction moyenne, on doit savoir si une liste vide est autorisée et comment ce cas est traité.

Un nom plausible ne remplace pas la documentation. Deux opérations peuvent sembler trier une liste, mais l’une modifie la liste reçue tandis que l’autre produit une nouvelle liste. Le choix dépend alors de ce que le programme appelant souhaite conserver. Les erreurs documentées font aussi partie du contrat utile.

Écrire un contrat réellement exploitable

Voici une fonction qui reçoit une séquence non vide de nombres et renvoie leur moyenne, sans la modifier. L’assertion matérialise une précondition pédagogique ; elle ne remplace pas une politique complète de validation de données externes. La documentation annonce explicitement le cas exclu.

def moyenne(valeurs):
    """Renvoie la moyenne d’une séquence non vide de nombres.
    Ne modifie pas valeurs.
    """
    assert len(valeurs) > 0
    return sum(valeurs) / len(valeurs)

Un exemple court complète utilement ce texte : moyenne([2, 4, 9]) renvoie 5.0. Un exemple ne remplace cependant pas la règle générale. La documentation doit permettre d’utiliser la fonction sur d’autres données que celles de la démonstration.

Importer et vérifier les composants

Si cette fonction se trouve dans statistiques.py, on peut écrire import statistiques puis statistiques.moyenne([2, 4, 9]). Le nom qualifié indique l’origine de la fonction et limite certaines ambiguïtés. La forme from statistiques import moyenne est également possible, mais place directement le nom moyenne dans l’espace de noms courant.

Un module destiné à être réutilisé ne devrait pas lancer involontairement une longue démonstration ou demander une saisie lors de son import. En Python, le garde if __name__ == "__main__" permet d’isoler un scénario exécuté seulement lorsque le fichier est lancé directement. On vérifie ensuite le contrat par des tests normaux et des cas limites pertinents.

Exemple suivi : intégrer une fonction documentée

Une API fictive propose normaliser(valeurs, maximum) : elle reçoit une séquence de nombres positifs ou nuls et un maximum strictement positif, renvoie une nouvelle liste où chaque valeur est divisée par ce maximum, sans modifier l’entrée. Avec [2,6] et maximum 8, le résultat attendu est [0.25,0.75]. La sortie nouvelle et l’absence de mutation permettent de conserver les mesures originales.

Avant l’appel, vérifiez le domaine, particulièrement maximum=0. Après l’appel, utilisez la valeur renvoyée : appeler la fonction sans conserver son résultat ne met pas à jour automatiquement votre liste. Un test peut conserver une copie des mesures, appeler la fonction, comparer le résultat attendu et vérifier que l’original n’a pas changé. La documentation décrit les deux propriétés ; lire seulement le nom de la fonction ne permettrait de deviner ni la formule ni son effet sur la mémoire.

Exemple suivi : écrire un module réutilisable

Dans indicateurs.py, placez une fonction de calcul recevant ses données en paramètre et renvoyant son résultat. Une démonstration peut être écrite sous if __name__ == "__main__":. Lorsque le fichier est lancé directement, ce bloc s’exécute ; lorsqu’un autre module importe les fonctions, la démonstration ne doit pas demander une saisie ni ouvrir une fenêtre. Cela rend l’import prévisible pour le programme utilisateur et pour les tests.

Une documentation suffisante précise les paramètres, les cas exclus ou acceptés, le résultat, les effets et un exemple. Elle n’a pas besoin d’expliquer le nom de chaque variable locale. Si une boucle est remplacée par une autre méthode respectant les mêmes garanties, les utilisateurs du module ne devraient pas changer leur code. En revanche, remplacer un résultat nouveau par une modification sur place change le contrat : il faut adapter explicitement les appelants et les tests concernés.

De la compréhension à l’autonomie

À vous de résoudre

Cherchez d’abord par vous-même. Vérifiez les résultats demandés, utilisez les indices si nécessaire, puis comparez votre méthode à la correction.

Les erreurs qui méritent un détour

Déduire un effet uniquement du nom de la fonction.

La documentation précise les modifications éventuelles et les résultats.

Créer des dépendances cachées par variables globales.

Des paramètres et retours explicites rendent les composants plus faciles à tester.

Cette notion au bac

Retrouvez ces idées dans un sujet complet, avec des indices, une correction expliquée et des ateliers.

• Bac 2026 · Centres étrangers groupe 1 · Jour 2 : Compagnie de taxis : objets, durée, tarif et échange de clés

Le prochain pas

• Paradigmes impératif, fonctionnel et objet
• Concevoir et mener un projet de NSI

Retrouver le catalogue de Terminale

Ce chapitre s’appuie sur le programme officiel de Terminale (PDF, nouvel onglet). Les explications et exercices sont proposés pour l’apprentissage.