Bonnes pratiques Python : nommage, types, tests, logging

Qualite, lisibilite, maintenance et tests

🏷️

Nommage

Variables- En Python (convention PEP8), les variables s'ecrivent en snake_case (minuscules + underscores). Un nom explicite evite d'avoir a commenter ce que contient la variable.

vitesse_moteur = 1500      # explicite : on sait immediatement ce que c'est
temperature_max = 80.5
x = 1500                   # a eviter : aucune info sur le contenu
est_actif = True           # les booleens commencent souvent par est_/a_/peut_

Fonctions- Une fonction realise une action : son nom doit donc commencer par un verbe. Comme les variables, snake_case est la convention standard.

def calculer_vitesse():    # verbe + snake_case
    pass
def vitesse():             # a eviter : ressemble a une variable, pas a une action
    pass

Constantes et classes- Les constantes s'ecrivent en MAJUSCULES_AVEC_UNDERSCORES pour signaler qu'elles ne doivent pas changer. Les classes s'ecrivent en PascalCase (une majuscule a chaque mot).

VITESSE_MAX = 3000          # constante : valeur fixe du programme
TIMEOUT_SECONDES = 30
class MoteurAsynchrone:     # PascalCase pour les classes
    pass

🔤

Type hints

Annotations de base- Les type hints indiquent le type attendu des parametres et de la valeur retournee. Python ne les impose pas a l'execution, mais ils ameliorent la lisibilite et permettent aux outils (VS Code, mypy) de detecter des erreurs avant de lancer le code.

def addition(a: int, b: int) -> int:
    return a + b
nom: str = "Alice"          # annotation directement sur une variable
actif: bool = True

Types complexes (typing)- Pour les collections ou les cas ambigus (valeur optionnelle, plusieurs types possibles), le module 'typing' fournit des types plus expressifs.

from typing import Optional, Union
def chercher(nom: str) -> Optional[int]:
    # Optional[int] = int OU None (si rien n'est trouve)
    return None
def convertir(valeur: Union[int, float]) -> float:
    # Union[int, float] = accepte un int OU un float
    return float(valeur)
def liste_noms() -> list[str]:
    # depuis Python 3.9, list[str] remplace List[str]
    return ["Alice", "Bob"]

📘

Docstrings

Docstring de fonction- Une docstring documente une fonction directement dans le code : elle est accessible via help() ou l'infobulle de l'editeur. Elle se place juste apres la ligne def, entre triple guillemets.

def division(a: float, b: float) -> float:
    """Retourne le resultat de a / b."""
    return a / b
help(division)   # affiche la docstring dans la console

Docstring detaillee (style Google)- Pour une fonction complexe, on detaille les parametres, la valeur de retour et les exceptions possibles.

def diviser(a: float, b: float) -> float:
    """Divise a par b.
    Args:
        a: Le numerateur.
        b: Le denominateur (doit etre different de 0).
    Returns:
        Le resultat de la division.
    Raises:
        ZeroDivisionError: si b vaut 0.
    """
    return a / b

🧪

Tests unitaires

pytest - test simple- pytest reconnait automatiquement les fonctions commencant par 'test_'. Un simple 'assert' suffit : pas besoin d'ecrire soi-meme la gestion d'echec.

# fichier test_calculs.py
def addition(a, b):
    return a + b
def test_addition():
    assert addition(2, 3) == 5   # le test echoue si l'assertion est fausse
# executer les tests :
# pytest test_calculs.py -v

pytest.mark.parametrize- Permet de tester plusieurs cas avec la meme fonction de test, sans dupliquer le code.

import pytest
@pytest.mark.parametrize("a, b, resultat", [
    (2, 3, 5),
    (0, 0, 0),
    (-1, 1, 0),
])
def test_addition_plusieurs_cas(a, b, resultat):
    assert addition(a, b) == resultat

📝

Logging

Configuration de base- Le module logging remplace avantageusement print() : on peut filtrer par niveau de gravite, rediriger vers un fichier, et desactiver les messages sans supprimer le code.

import logging
logging.basicConfig(level=logging.INFO)   # niveau minimum affiche
logging.debug("Detail technique")     # non affiche (en dessous du niveau INFO)
logging.info("Demarrage du programme") # affiche
logging.warning("Valeur inhabituelle") # affiche
logging.error("Erreur rencontree")     # affiche

Logger par module- Dans un vrai projet, on cree un logger par fichier (via __name__) pour savoir immediatement d'ou vient chaque message.

import logging
logger = logging.getLogger(__name__)   # __name__ = nom du fichier/module courant
logger.info("Connexion etablie")
logger.error("Echec de connexion")

⚡

Optimisation

List comprehension- Plus rapide qu'une boucle for classique avec .append(), et plus concise a lire une fois l'habitude prise.

# avec une boucle classique
carres = []
for x in range(1000):
    carres.append(x * x)
# equivalent en list comprehension (plus rapide)
carres = [x * x for x in range(1000)]

Generator (economie de memoire)- Contrairement a une liste, un generateur ne stocke pas toutes les valeurs en memoire : il les calcule une par une, a la demande. Utile pour de tres grands volumes de donnees.

carres_liste = [x * x for x in range(1_000_000)]   # tout en memoire d'un coup
carres_gen = (x * x for x in range(1_000_000))     # calcule au fur et a mesure
for valeur in carres_gen:
    if valeur > 100:
        break   # arret immediat, le reste n'est jamais calcule

Utiliser la bonne structure de donnees- Chercher un element est quasi instantane (O(1)) dans un set ou un dict, contre potentiellement lent (O(n)) dans une liste.

ids_valides = [1, 2, 3, 4, 5]        # liste : recherche lente sur gros volume
ids_valides_set = {1, 2, 3, 4, 5}    # set : recherche quasi instantanee
if 3 in ids_valides_set:   # tres rapide, meme avec des milliers d'elements
    print("trouve")