Modules Python

Un module est un fichier contenant du code Python — fonctions, classes et variables — que vous pouvez réutiliser dans plusieurs programmes. Les modules constituent l'unité de base d'organisation du code en Python : au lieu de copier la logique entre les fichiers, vous l'écrivez une fois, la sauvegardez dans un fichier .py et l'importez où vous en avez besoin. Ce chapitre couvre tout, depuis la création de votre premier module jusqu'à la navigation dans la bibliothèque standard et la compréhension de la façon dont Python localise les modules au moment de l'exécution.

Qu'est-ce qu'un module Python ?

Tout fichier .py est un module. Lorsque vous écrivez :

# greetings.py
def hello(name):
    return f"Hello, {name}!"

def goodbye(name):
    return f"Goodbye, {name}!"

PI = 3.14159

vous avez créé un module nommé greetings. Le nom du module est le nom du fichier sans l'extension .py.

Les modules peuvent contenir :

• Des fonctions — des blocs de logique réutilisables (voir Fonctions Python)
• Des classes — des modèles pour les objets (voir Classes Python)
• Des variables et des constantes — des données partagées
• Des instructions exécutables — du code qui s'exécute lors de l'importation du module ou de son exécution directe

Importer un module

Utilisez l'instruction import suivie du nom du module (sans l'extension .py).

import greetings

print(greetings.hello("Alice"))    # Hello, Alice!
print(greetings.goodbye("Alice"))  # Goodbye, Alice!
print(greetings.PI)                # 3.14159

Après import greetings, tous les noms définis dans greetings.py sont accessibles via le préfixe greetings.. Cette notation pointée évite les conflits de noms — votre propre variable PI ne peut pas entrer en collision avec greetings.PI.

Importer des noms spécifiques avec from ... import

Si vous n'avez besoin que d'un ou deux noms, importez-les directement afin de pouvoir les utiliser sans le préfixe du module.

from greetings import hello, PI

print(hello("Bob"))   # Hello, Bob!
print(PI)             # 3.14159

Tout importer avec *

from greetings import *

Cela importe tous les noms publics (ceux ne commençant pas par _) dans l'espace de noms courant. Évitez cette pratique dans les programmes plus importants : elle pollue l'espace de noms et rend difficile l'identification de l'origine d'un nom.

Alias d'importation avec as

Les noms de modules longs deviennent fastidieux à taper. Utilisez as pour créer un alias plus court.

import greetings as gr

print(gr.hello("Carol"))   # Hello, Carol!

Vous pouvez également créer des alias pour des noms importés individuellement :

from greetings import hello as hi

print(hi("Dave"))   # Hello, Dave!

Les alias sont particulièrement courants avec les bibliothèques populaires :

import numpy as np
import pandas as pd
import matplotlib.pyplot as plt

La fonction dir()

dir(module) renvoie une liste triée de tous les noms définis dans un module — un moyen rapide d'explorer ce qui est disponible.

import math
print(dir(math))
# ['__doc__', '__loader__', ..., 'acos', 'acosh', 'asin', ..., 'sqrt', 'tan', 'tanh', 'tau']

Appelez dir() sans argument pour voir les noms dans la portée courante.

La variable __name__

Chaque module possède une variable intégrée appelée __name__. Lorsqu'un fichier est importé, __name__ est défini sur le nom du module. Lorsque le fichier est exécuté directement, __name__ est défini sur la chaîne "__main__".

Ce modèle est la façon standard d'écrire du code qui s'exécute uniquement lorsque le fichier est lancé en tant que script — et non lorsqu'il est importé comme bibliothèque :

# greetings.py

def hello(name):
    return f"Hello, {name}!"

if __name__ == "__main__":
    # This block only runs when you execute: python greetings.py
    print(hello("World"))

import greetings   # The if-block does NOT run here

Ce modèle est utilisé dans presque tous les fichiers Python non triviaux que vous rencontrerez.

Chemin de recherche des modules (sys.path)

Lorsque vous écrivez import greetings, Python recherche le module dans une liste de répertoires stockée dans sys.path :

1. Le répertoire du script en cours d'exécution (ou le répertoire courant en mode interactif)
2. Les répertoires listés dans la variable d'environnement PYTHONPATH
3. Les répertoires de la bibliothèque standard
4. Le répertoire site-packages (où vivent les paquets tiers installés par pip)

import sys
print(sys.path)
# ['/path/to/script', '/usr/lib/python3.11', ..., '/usr/lib/python3/dist-packages']

Vous pouvez ajouter un chemin au moment de l'exécution, mais cela est rarement nécessaire pour des projets bien structurés :

import sys
sys.path.append("/path/to/my/libs")

La bibliothèque standard Python

Python est livré avec une vaste bibliothèque standard — des centaines de modules couvrant tout, des entrées/sorties de fichiers aux protocoles réseau en passant par la compression de données. Vous n'avez rien à installer ; il suffit de les importer.

math — Fonctions mathématiques

import math

print(math.sqrt(16))       # 4.0
print(math.pi)             # 3.141592653589793
print(math.factorial(5))   # 120
print(math.ceil(4.2))      # 5
print(math.floor(4.8))     # 4

Voir Python Math pour une référence complète.

random — Nombres aléatoires

import random

print(random.randint(1, 10))          # random integer between 1 and 10
print(random.choice(["a", "b", "c"])) # random element
print(random.random())                 # float in [0.0, 1.0)

numbers = [1, 2, 3, 4, 5]
random.shuffle(numbers)
print(numbers)   # shuffled in place

datetime — Dates et heures

import datetime

now = datetime.datetime.now()
print(now)                       # 2024-03-15 10:30:45.123456
print(now.year)                  # 2024
print(now.strftime("%B %d, %Y")) # March 15, 2024

today = datetime.date.today()
print(today)   # 2024-03-15

Voir Python Dates pour une couverture complète des calculs et du formatage de dates.

os et sys — Système d'exploitation et interpréteur

import os

print(os.getcwd())              # current working directory
print(os.listdir("."))          # files in the current directory
os.makedirs("new_dir", exist_ok=True)  # create a directory
print(os.path.join("folder", "file.txt"))  # 'folder/file.txt'

import sys

print(sys.version)    # Python version string
print(sys.platform)   # 'linux', 'darwin', 'win32', etc.
sys.exit(0)           # terminate the program with exit code 0

json — Encodage et décodage JSON

import json

data = {"name": "Alice", "age": 30, "active": True}

# Python → JSON string
json_string = json.dumps(data, indent=2)
print(json_string)

# JSON string → Python
parsed = json.loads(json_string)
print(parsed["name"])   # Alice

Voir Python JSON pour la lecture et l'écriture basées sur les fichiers.

collections — Structures de données spécialisées

from collections import Counter, defaultdict

# Count occurrences
words = ["apple", "banana", "apple", "cherry", "banana", "apple"]
counts = Counter(words)
print(counts)              # Counter({'apple': 3, 'banana': 2, 'cherry': 1})
print(counts.most_common(2))  # [('apple', 3), ('banana', 2)]

# Dict with default values
scores = defaultdict(int)
scores["Alice"] += 10
scores["Bob"] += 5
print(dict(scores))   # {'Alice': 10, 'Bob': 5}

Voir Module Collections Python pour namedtuple, deque et OrderedDict.

Créer votre propre module

Structure de base

Les modules fonctionnent mieux lorsqu'ils font bien une seule chose. Une bonne règle empirique : si un groupe de fonctions partage un thème, regroupez-les dans leur propre fichier.

# mathutils.py

def clamp(value, minimum, maximum):
    """Restrict value to the range [minimum, maximum]."""
    return max(minimum, min(value, maximum))

def average(numbers):
    """Return the arithmetic mean of a list of numbers."""
    if not numbers:
        raise ValueError("Cannot average an empty list")
    return sum(numbers) / len(numbers)

def is_prime(n):
    """Return True if n is a prime number."""
    if n < 2:
        return False
    for i in range(2, int(n ** 0.5) + 1):
        if n % i == 0:
            return False
    return True

# main.py
from mathutils import clamp, average, is_prime

print(clamp(15, 0, 10))          # 10
print(average([2, 4, 6, 8]))     # 5.0
print(is_prime(17))              # True

Docstrings dans les modules

Ajoutez une docstring au niveau du module tout en haut du fichier. Des outils comme help() et les générateurs de documentation l'utilisent.

"""
mathutils.py — Utility functions for common mathematical operations.

Functions:
    clamp(value, minimum, maximum) -> number
    average(numbers) -> float
    is_prime(n) -> bool
"""

Variables de module : __all__

__all__ est une liste de noms qui doivent être exportés lorsque quelqu'un effectue from module import *. Elle sert également de documentation sur l'API publique du module.

# mathutils.py
__all__ = ["clamp", "average", "is_prime"]

def _helper():   # leading underscore marks it as private
    pass

Recharger un module

Python met en cache les modules importés dans sys.modules. Importer le même module deux fois ne le ré-exécute pas — Python renvoie la version mise en cache. Lors du développement interactif ou du débogage, vous pouvez forcer un rechargement :

import importlib
import greetings

importlib.reload(greetings)

Cela est surtout nécessaire dans les sessions REPL ou les notebooks Jupyter après avoir modifié un fichier de module.

Pièges courants

Importations circulaires

Si module_a importe module_b et que module_b importe module_a, vous obtenez une importation circulaire. Python peut gérer certaines importations circulaires, mais elles sont sources de confusion et indiquent souvent un problème de conception. La solution consiste généralement à restructurer votre code — déplacer la logique partagée dans un troisième module, ou retarder l'importation à l'intérieur d'une fonction.

Masquer un module de la bibliothèque standard

Si vous nommez votre fichier math.py, random.py ou json.py, vous masquerez le module de la bibliothèque standard et briserez tout code qui l'importe. Utilisez des noms spécifiques et descriptifs pour vos propres modules.

# BAD: naming your file math.py shadows the stdlib
# GOOD: name it mathutils.py or geometry.py

ImportError et ModuleNotFoundError

ModuleNotFoundError (une sous-classe de ImportError) signifie que Python n'a pas pu trouver le module dans sys.path. Causes courantes :

• Une faute de frappe dans le nom du module
• Le module n'est pas installé (pip install <package-name>)
• Le fichier du module se trouve dans un répertoire absent de sys.path

try:
    import nonexistent_module
except ModuleNotFoundError as e:
    print(f"Import failed: {e}")
    # Import failed: No module named 'nonexistent_module'

Modules vs. paquets

Un module est un seul fichier .py. Un paquet est un répertoire contenant plusieurs modules et un fichier __init__.py. Les paquets vous permettent de construire des bibliothèques plus grandes avec une structure hiérarchique. Voir Paquets Python pour l'histoire complète.

Modules tiers populaires

Au-delà de la bibliothèque standard, l'écosystème Python sur PyPI compte des centaines de milliers de paquets. Installez-les avec pip.

Pratique