API et Documentation
Comment utiliser une fonction sans connaître son code source ? C'est le principe de l'API : définir un contrat clair entre le créateur et l'utilisateur d'un module.
Objectifs du cours
- Comprendre le concept d'API (Interface de Programmation)
- Savoir documenter une fonction avec des docstrings
- Distinguer interface publique et implémentation privée
- Utiliser les annotations de types en Python
- Appliquer les bonnes pratiques de documentation
Erreurs courantes à éviter
- Confondre API et implémentation interne
- Oublier de documenter les paramètres et la valeur de retour
- Ne pas spécifier les types attendus
- Documentation obsolète par rapport au code
Une **API** (Application Programming Interface) est l'ensemble des fonctions, classes et constantes qu'un module expose à ses utilisateurs. C'est le **contrat** qui définit comment utiliser le module sans avoir besoin de connaître son fonctionnement interne.
**Analogie** : Pensez à une télécommande de télévision. Vous savez que le bouton "Volume +" augmente le son, mais vous n'avez pas besoin de comprendre l'électronique interne. Les boutons sont l'API de la télécommande.
**Principe fondamental** : - L'**interface** (API) : ce que l'utilisateur peut voir et utiliser - L'**implémentation** : le code interne qui fait le travail
Ce découpage permet de : 1. Modifier l'implémentation sans impacter les utilisateurs 2. Cacher la complexité derrière une interface simple 3. Définir un contrat stable entre modules
# Exemple : Module de calcul de statistiques
# L'utilisateur voit SEULEMENT ces fonctions (l'API)
def moyenne(donnees: list[float]) -> float:
"""Calcule la moyenne d'une liste de nombres."""
pass
def ecart_type(donnees: list[float]) -> float:
"""Calcule l'écart-type d'une liste de nombres."""
pass
def mediane(donnees: list[float]) -> float:
"""Calcule la médiane d'une liste de nombres."""
pass
# L'utilisateur n'a pas besoin de savoir comment c'est calculé !
# Il utilise juste : moyenne([1, 2, 3, 4, 5]) → 3.0Quiz de validation
1. Que représente une API dans le contexte de la programmation modulaire ?
2. Quelle est la convention Python pour indiquer qu'une fonction est privée (usage interne) ?
3. À quoi servent les annotations de types en Python ?
4. Comment accéder à la docstring d'une fonction ma_fonction ?
5. Que définit la variable __all__ dans un module Python ?
