Décorateurs en Python : ce que c'est, comment ils fonctionnent et comment en écrire un

Un décorateur en Python est une fonction qui reçoit une fonction et renvoie une autre fonction, généralement un wrapper qui entoure la première. C'est ainsi qu'on ajoute un comportement à une fonction — journalisation, mesure du temps, cache, nouvelles tentatives — sans modifier son code. Les décorateurs s'écrivent avec la syntaxe @nom au-dessus de la déclaration de la fonction, et on les rencontre partout : dans Flask et FastAPI, dans pytest, dans la bibliothèque standard.

Ce qu'est un décorateur, en termes simples

Pensez à un cadeau et à son papier d'emballage. Le cadeau (la fonction) reste le même, mais une couche extérieure entre en action en premier. Un décorateur est exactement cet emballage : à l'appel, le code du wrapper s'exécute d'abord, appelle la fonction d'origine, et peut ensuite traiter le résultat.

Cela fonctionne parce qu'en Python les fonctions sont des objets ordinaires. On peut les passer à d'autres fonctions, les renvoyer depuis une fonction, et les déclarer à l'intérieur d'une fonction. Les décorateurs reposent sur ces trois propriétés.

Comment fonctionne un décorateur : @ est un raccourci de syntaxe

Prenons le décorateur le plus simple : il affiche un message avant et après l'appel.

def journaliser(func):
    def wrapper():
        print(f"J'appelle {func.__name__}")
        resultat = func()
        print(f"{func.__name__} est terminée")
        return resultat
    return wrapper

@journaliser
def bonjour():
    print("Salut !")

bonjour()

J'appelle bonjour
Salut !
bonjour est terminée

L'écriture @journaliser placée au-dessus de def est strictement équivalente à la ligne suivante, écrite après la déclaration :

def bonjour():
    print("Salut !")

bonjour = journaliser(bonjour)

Le nom bonjour désigne désormais wrapper, et la fonction d'origine vit à l'intérieur de la fermeture : wrapper conserve la variable func de la fonction externe. Point important : le décorateur n'est appliqué qu'une fois, au moment où def s'exécute, c'est-à-dire à l'import du module ; le wrapper, lui, se déclenche à chaque appel.

Fermetures et décorateurs

Une fermeture (closure) est une fonction imbriquée qui mémorise les variables de la fonction externe après la fin de celle-ci. Sans fermetures, il n'y aurait pas de décorateurs : c'est grâce à elles que wrapper accède à func. Une fermeture peut aussi conserver un état, par exemple un compteur d'appels :

def compter_appels(func):
    appels = 0
    def wrapper(*args, **kwargs):
        nonlocal appels
        appels += 1
        print(f"{func.__name__} : appel n°{appels}")
        return func(*args, **kwargs)
    return wrapper

Écrire un décorateur en Python : modèle universel

Le premier exemple a deux défauts : le wrapper n'accepte pas d'arguments, et il « avale » le nom de la fonction d'origine. Voici le modèle de départ, valable pour presque tous les décorateurs :

import functools

def mon_decorateur(func):
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        # code avant l'appel
        resultat = func(*args, **kwargs)
        # code après l'appel
        return resultat
    return wrapper

Trois règles pour ce modèle :

1. *args, **kwargs — le wrapper accepte n'importe quels arguments et les transmet tels quels.
2. return resultat — ne pas oublier de renvoyer le résultat, sinon la fonction décorée renverra toujours None.
3. @functools.wraps(func) — recopier les métadonnées de la fonction d'origine sur le wrapper.

Exemple de décorateur qui mesure le temps d'exécution :

import functools
import time

def chronometre(func):
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        debut = time.perf_counter()
        resultat = func(*args, **kwargs)
        duree = time.perf_counter() - debut
        print(f"{func.__name__} a pris {duree:.3f} s")
        return resultat
    return wrapper

@chronometre
def somme_lente(n):
    return sum(range(n))

somme_lente(10_000_000)   # somme_lente a pris 0.142 s

À quoi sert functools.wraps

Sans wraps, le nom, la docstring et d'autres attributs de la fonction décorée sont remplacés : de l'extérieur, on voit wrapper :

def simple(func):
    def wrapper(*args, **kwargs):
        return func(*args, **kwargs)
    return wrapper

@simple
def additionner(a, b):
    """Additionne deux nombres."""
    return a + b

print(additionner.__name__, additionner.__doc__)   # wrapper None

Avec @functools.wraps(func), le wrapper reçoit __name__, __doc__, __module__, __qualname__ et __annotations__ de la fonction d'origine, et l'attribut __wrapped__ conserve une référence vers l'original. C'est important pour le débogage et les traces d'erreur, pour help(), pour les frameworks qui enregistrent les fonctions par leur nom, et pour inspect.signature, qui affiche la vraie signature.

Décorateur avec paramètres (avec arguments)

Parfois, un décorateur a besoin de réglages : @retry(times=3), @app.route("/"). On ajoute alors un niveau d'imbrication. La fonction externe reçoit les paramètres et renvoie le véritable décorateur : c'est ce qu'on appelle une fabrique de décorateurs.

import functools

def repeter(fois):
    def decorateur(func):
        @functools.wraps(func)
        def wrapper(*args, **kwargs):
            resultat = None
            for _ in range(fois):
                resultat = func(*args, **kwargs)
            return resultat
        return wrapper
    return decorateur

@repeter(fois=3)
def ping():
    print("ping")

ping()   # ping, ping, ping — trois lignes

Ordre d'évaluation : repeter(fois=3) renvoie decorateur, qui est appliqué à ping et renvoie wrapper. Autrement dit, @repeter(fois=3) revient à écrire ping = repeter(fois=3)(ping).

Exemple pratique : relancer l'appel en cas d'erreur.

import functools
import time

def reessayer(fois=3, delai=1.0, exceptions=(Exception,)):
    def decorateur(func):
        @functools.wraps(func)
        def wrapper(*args, **kwargs):
            for tentative in range(1, fois + 1):
                try:
                    return func(*args, **kwargs)
                except exceptions:
                    if tentative == fois:
                        raise
                    time.sleep(delai)
        return wrapper
    return decorateur

@reessayer(fois=5, delai=0.5, exceptions=(ConnectionError,))
def obtenir_taux():
    ...

Plusieurs décorateurs sur une même fonction

On peut empiler les décorateurs. Ils s'appliquent de bas en haut : celui qui est le plus proche du def agit en premier.

@chronometre
@journaliser
def rapport():
    ...

# équivalent à :
rapport = chronometre(journaliser(rapport))

À l'appel, le décorateur externe (chronometre) se déclenche en premier, il mesure donc aussi le temps passé dans journaliser. L'ordre compte : si l'un vérifie les droits d'accès et l'autre met le résultat en cache, leur ordre change le comportement.

Décorateurs standard et intégrés de Python

Beaucoup de décorateurs utiles existent déjà dans le langage et dans la bibliothèque standard :

Mise en cache : functools.cache et lru_cache

Un décorateur de cache mémorise le résultat pour chaque ensemble d'arguments et, à l'appel suivant, le renvoie sans recalcul. L'exemple classique est la suite de Fibonacci récursive, qui, sans cache, demande un temps exponentiel :

import functools

@functools.cache
def fib(n):
    return n if n < 2 else fib(n - 1) + fib(n - 2)

print(fib(100))   # 354224848179261915075

functools.cache (disponible depuis Python 3.9) conserve tous les résultats sans limite. @functools.lru_cache(maxsize=128) ne garde que les derniers résultats et évince les plus anciens : c'est plus sûr pour les services qui tournent longtemps. On consulte les statistiques avec fib.cache_info() et on vide le cache avec fib.cache_clear(). Les arguments de ces fonctions doivent être hachables : une liste passée en argument provoque TypeError: unhashable type: 'list'. Et il ne faut mettre en cache que des fonctions pures, c'est-à-dire qui renvoient toujours la même chose pour les mêmes arguments et n'ont pas d'effets de bord.

Ce que fait le décorateur property

@property permet d'accéder à une méthode comme à un attribut, sans parenthèses, et de contrôler l'affectation si nécessaire :

class Compte:
    def __init__(self, solde):
        self._solde = solde

    @property
    def solde(self):
        return self._solde

    @solde.setter
    def solde(self, valeur):
        if valeur < 0:
            raise ValueError("Le solde ne peut pas être négatif")
        self._solde = valeur

compte = Compte(100)
print(compte.solde)   # 100
compte.solde = -5     # ValueError

staticmethod et classmethod

class Montant:
    def __init__(self, centimes):
        self.centimes = centimes

    @classmethod
    def depuis_euros(cls, euros):
        return cls(round(euros * 100))

    @staticmethod
    def est_valide(valeur):
        return valeur >= 0

m = Montant.depuis_euros(12.5)
print(m.centimes, Montant.est_valide(-1))   # 1250 False

C'est @classmethod qui permet à une méthode de travailler avec la classe elle-même et non avec ses instances : depuis_euros crée correctement un objet de sous-classe.

Décorateurs de classes et classes utilisées comme décorateurs

Un décorateur peut s'appliquer à une classe : il reçoit la classe et renvoie une classe, identique ou modifiée. C'est ainsi que fonctionne @dataclass. Exemple simple : un registre de classes.

registre = {}

def enregistrer(cls):
    registre[cls.__name__] = cls
    return cls

@enregistrer
class ExportateurCsv:
    pass

print(registre)   # {'ExportateurCsv': <class '__main__.ExportateurCsv'>}

Le cas inverse, où une classe joue le rôle de décorateur, est aussi possible. Il suffit d'un objet doté de la méthode __call__ ; l'état est commodément stocké dans les attributs de l'instance :

import functools

class CompteurAppels:
    def __init__(self, func):
        functools.update_wrapper(self, func)
        self.func = func
        self.appels = 0

    def __call__(self, *args, **kwargs):
        self.appels += 1
        return self.func(*args, **kwargs)

@CompteurAppels
def tic():
    pass

tic(); tic()
print(tic.appels)   # 2

Décorateur asynchrone

Pour les fonctions async def, le wrapper doit lui aussi être une coroutine et attendre le résultat avec await, sinon on récupère un objet coroutine non exécuté :

import functools

def journaliser_async(func):
    @functools.wraps(func)
    async def wrapper(*args, **kwargs):
        print(f"Début de {func.__name__}")
        resultat = await func(*args, **kwargs)
        print(f"Fin de {func.__name__}")
        return resultat
    return wrapper

À quoi servent les décorateurs en Python

• Logique transversale — journalisation, métriques, mesure du temps sans copier le code dans chaque fonction.
• Mise en cache — @functools.cache pour les calculs coûteux et purs.
• Contrôles — droits d'accès, validation des arguments, autorisation dans les gestionnaires web.
• Enregistrement — routes dans Flask et FastAPI (@app.get("/")), fixtures pytest.
• Fiabilité — nouvelles tentatives, délais d'attente, gestion des erreurs.

Le principal avantage est la séparation des responsabilités : la fonction s'occupe de sa tâche, et le comportement annexe s'ajoute en une ligne, tout aussi facile à retirer.

Erreurs typiques

• Le wrapper ne renvoie pas le résultat — après décoration, la fonction renvoie None.
• Pas de *args, **kwargs — TypeError lors d'un appel avec des arguments.
• Oubli de wraps — __name__ et docstring erronés, confusion dans les journaux.
• Parenthèses oubliées sur une fabrique — @repeter au lieu de @repeter(3) : la fonction est passée au paramètre fois.
• Code lourd dans le corps du décorateur — il s'exécute à l'import du module, et non à l'appel.

En bref

Les décorateurs en Python sont des fonctions d'ordre supérieur : elles reçoivent une fonction, renvoient un wrapper, et le @ n'est qu'une écriture courte d'affectation. Commencez par le modèle avec *args, **kwargs, return resultat et functools.wraps, puis ajoutez un niveau de fabrique pour les réglages. Les fonctions, les fermetures et les annotations sur lesquelles reposent les décorateurs sont mises en pratique dans le cours sur Python.