# Documentation Django 3.1.9.dev

# Intergiciels (« Middleware »)

Les intergiciels représentent un système de points d’entrée dans le traitement des requêtes et des réponses de Django. C’est un système de greffons léger et de bas niveau pour modifier de façon globale les entrées et sorties HTTP de Django.

Chaque composant d’intergiciel est responsable d’effectuer une tâche spécifique. Par exemple, Django contient un intergiciel, `AuthenticationMiddleware`, qui associe les utilisateurs aux requêtes et aux sessions.

Ce document explique comment fonctionnent les intergiciels, la manière de les activer et d’écrire vos propres intergiciels. Django est livré avec quelques intergiciels intégrés qu’il est possible d’utiliser tels quels. Ils sont documentés dans la référence des intergiciels intégrés.

## Écriture de son propre intergiciel

Une fabrique d’intergiciel est un objet exécutable acceptant un exécutable `get_response` et renvoyant un intergiciel. Un intergiciel est un objet exécutable acceptant une requête et renvoyant une réponse, tout comme une vue.

Un intergiciel peut être écrit comme une fonction qui ressemble à ceci :

    def simple_middleware(get_response):
        # One-time configuration and initialization.

        def middleware(request):
            # Code to be executed for each request before
            # the view (and later middleware) are called.

            response = get_response(request)

            # Code to be executed for each request/response after
            # the view is called.

            return response

        return middleware

Ou il peut être écrit comme une classe dont les instances peuvent être appelées, comme ceci :

    class SimpleMiddleware:
        def __init__(self, get_response):
            self.get_response = get_response
            # One-time configuration and initialization.

        def __call__(self, request):
            # Code to be executed for each request before
            # the view (and later middleware) are called.

            response = self.get_response(request)

            # Code to be executed for each request/response after
            # the view is called.

            return response

L’exécutable `get_response` fournit par Django pourrait être la vue elle-même (s’il s’agit du dernier intergiciel) ou alors le prochain intergiciel dans la chaîne. L’intergiciel actuel n’a pas besoin de savoir ou de se préoccuper de ce que c’est exactement, il lui suffit de savoir que ça représente ce qui vient ensuite.

Nous avons un peu simplifié l’explication ci-dessus, car l’exécutable `get_response` du dernier intergiciel dans la chaîne est en fait une méthode enveloppant la vue, créée par le gestionnaire se chargeant d’appliquer les intergiciels de vue; cette méthode appelle la vue avec les paramètres appropriés et applique les intergiciels template-response et exception.

Un intergiciel peut soit uniquement prendre en charge le code Python synchrone (par défaut), soit uniquement du code asynchrone, ou encore les deux. Consultez Gestion du code asynchrone pour des détails sur la manière d’informer sur ce qui est pris en charge et pour connaître le genre de requête que vous obtenez.

Les intergiciels peuvent se trouver n’importe où dans votre chemin Python.

### `__init__(get_response)`

Les fabriques d’intergiciel doivent accepter un paramètre `get_response`. Il est aussi possible d’initialiser de l’état global pour l’intergiciel. Gardez à l’esprit quelques précautions :

- Django initialise les intergiciels avec le seul paramètre `get_response`, il n’est donc pas possible de définir d’autres paramètres obligatoires à `__init__()`.
- Contrairement à la méthode `__call__()` qui est appelée une fois par requête, `__init__()` n’est appelée qu”une seule fois, lorsque le serveur Web démarre.

### Signalement d’un intergiciel à exclure

Il est parfois utile de déterminer au moment du démarrage si un intergiciel doit être utilisé. Dans ces cas, la méthode `__init__()` de l’intergiciel peut générer l’exception `MiddlewareNotUsed`. Django se charge alors d’enlever cet intergiciel du processus des intergiciels et jouranlise un message de débogage vers le journaliseur django.request lorsque `DEBUG` vaut `True`.

## Activation des intergiciels

Pour activer un intergiciel, ajoutez son chemin dans la liste `MIDDLEWARE` de vos réglages Django.

Dans `MIDDLEWARE`, chaque intergiciel est représenté par une chaîne : le chemin Python complet vers le nom de la classe ou de la fonction de fabrique d’intergiciel. Par exemple, voici la valeur par défaut créée par `django-admin startproject`:

    MIDDLEWARE = [
        'django.middleware.security.SecurityMiddleware',
        'django.contrib.sessions.middleware.SessionMiddleware',
        'django.middleware.common.CommonMiddleware',
        'django.middleware.csrf.CsrfViewMiddleware',
        'django.contrib.auth.middleware.AuthenticationMiddleware',
        'django.contrib.messages.middleware.MessageMiddleware',
        'django.middleware.clickjacking.XFrameOptionsMiddleware',
    ]

Une installation de Django n’a pas nécessairement des intergiciels, `MIDDLEWARE` pouvant très bien être vide si vous le souhaitez, mais il est fortement recommandé d’utiliser au moins `CommonMiddleware`.

L’ordre dans `MIDDLEWARE` a son importance car un intergiciel peut dépendre d’un autre. Par exemple, `AuthenticationMiddleware` stocke l’utilisateur non authentifié dans la session ; il doit donc être exécuté après `SessionMiddleware`. Voir Ordre des intergiciels pour d’autres indications utiles concernant l’ordre des classes d’intergiciel de Django.

## Ordre des intergiciels et empilement

Durant la phase de requête, avant d’appeler la vue, Django applique les intergiciels dans l’ordre où ils sont définis dans `MIDDLEWARE`, de haut en bas.

Vous pouvez l’imaginer comme un oignon : chaque classe d’intergiciel est une « couche » qui enveloppe la vue, elle-même le cœur de l’oignon. Si la requête traverse toutes les couches de l’oignon (chacune appelant `get_response` pour passer la requête à la prochaine couche), jusqu’à atteindre la vue au cœur, la réponse va ensuite traverser elle-même toutes les couches (dans l’ordre inverse) jusqu’à sa sortie du mécanisme.

Si l’une des couches décide de court-circuiter et de renvoyer une réponse sans jamais appeler `get_response`, aucune des couches de l’oignon plus à l’intérieur de cette couche (y compris la vue) ne verra la requête ou la réponse. La réponse ne traversera toujours que les mêmes couches traversées par la requête.

## Autres points d’entrée d’intergiciel

En dehors du modèle basique requête/réponse d’intergiciel présenté précédemment, vous pouvez ajouter trois autres méthodes spéciales aux intergiciels basés sur des classes :

### `process_view()`

`process_view`(request, view_func, view_args, view_kwargs)

`request` est un objet `HttpRequest`. `view_func` et la fonction python que Django s’apprête à utiliser (il s’agit bien de l’objet fonction, pas du nom textuel de la fonction). `view_args` est une liste de paramètres positionnels qui seront transmis à la vue, et `view_kwargs` est un dictionnaire de paramètres nommés qui seront transmis à la vue. Ni `view_args` ni `view_kwargs` ne comprennent le premier paramètre de la vue (`request`).

`process_view()` est appelée juste avant que Django n’appelle la vue.

Elle doit renvoyer soit `None`, soit un objet `HttpResponse`. Si elle renvoie `None`, Django continue le traitement de la requête, en appliquant d’éventuels autres intergiciels `process_view()`, puis exécute la vue appropriée. Si elle renvoie un objet `HttpResponse`, Django ne prend pas la peine d’appeler la vue correspondante ; il va simplement appliquer les intergiciels de réponse à cet objet `HttpResponse` et renvoyer le résultat.

Note

L’accès à `request.POST` depuis un intergiciel avant que la vue ne soit exécutée ou dans `process_view()` empêche toute vue exécutée après les intergiciels de pouvoir modifier les gestionnaires de téléversement de la requête, et devrait donc être évité.

La classe `CsrfViewMiddleware` peut être considérée comme une exception, car elle fournit les décorateurs `csrf_exempt()` et `csrf_protect()` qui permettent aux vues de contrôler explicitement le moment de la validation CSRF.

### `process_exception()`

`process_exception`(request, exception)

`request` est un objet `HttpRequest`. `exception` est un objet `Exception` généré par la fonction de vue.

Django appelle `process_exception()` lorsqu’une vue génère une exception. `process_exception()` doit renvoyer `None` ou un objet `HttpResponse`. Si elle renvoie un objet `HttpResponse`, les intergiciels de réponse par gabarit et de réponse sont appliqués, et la réponse résultante sera renvoyée au navigateur. Sinon, la gestion par défaut des exceptions intervient.

Encore une fois, les intergiciels sont exécutés dans l’ordre inverse lors de la phase de réponse, ce qui comprend `process_exception`. Si un intergiciel d’exception renvoie une réponse, les méthodes `process_exception` des classes d’intergiciels situées au-dessus ne seront pas du tout appelées.

### `process_template_response()`

`process_template_response`(request, response)

`request` est un objet `HttpRequest`. `response` est l’objet `TemplateResponse` (ou équivalent) renvoyé par une vue Django ou par un intergiciel.

`process_template_response()` est appelée juste après la fin de l’exécution de la vue, pour autant que l’instance réponse possède une méthode `render()`, ce qui laisse penser qu’il s’agit d’un objet `TemplateResponse` ou d’un équivalent.

Elle doit renvoyer un objet réponse qui implémente une méthode `render`. Elle peut modifier la réponse donnée en changeant `response.template_name` et `response.context_data`, ou elle peut créer et renvoyer une toute nouvelle classe `TemplateResponse` ou un équivalent.

Il n’est pas nécessaire d’effectuer explicitement le rendu des réponses, celles-ci étant automatiquement « rendues » après que tous les intergiciels de réponse ont été appelés.

Les intergiciels sont exécutés dans l’ordre inverse lors de la phase de réponse, ce qui inclut `process_template_response()`.

## Gestion des réponses en flux

Au contraire de `HttpResponse`, `StreamingHttpResponse` ne possède pas d’attribut `content`. En conséquence, les intergiciels ne peuvent plus compter sur le fait que toutes les réponses possèdent un attribut `content`. S’ils ont besoin d’accéder au contenu, ils doivent savoir s’ils ont affaire avec une réponse de type flux (streaming) et ajuster leur comportement en fonction de cela :

    if response.streaming:
        response.streaming_content = wrap_streaming_content(response.streaming_content)
    else:
        response.content = alter_content(response.content)

Note

Il faut toujours partir du principe que `streaming_content` est trop volumineux pour être stocké en mémoire. Les intergiciels de réponse peuvent l’adapter dans un nouveau générateur, mais ils ne devraient pas le consommer. L’adaptation s’implémente typiquement de cette façon :

    def wrap_streaming_content(content):
        for chunk in content:
            yield alter_content(chunk)

## Gestion des exceptions

Django convertit automatiquement les exceptions produites par la vue ou par l’intergiciel en une réponse HTTP appropriée avec un code de statut d’erreur. Certaine exceptions sont converties en codes de statut 4xx, alors qu’une exception inconnue est convertie en un code de statut 500.

Cette conversion a lieu avant et après chaque intergiciel (vous pouvez vous représenter cela comme la fine peau entre chaque couche de l’oignon), afin que chaque intergiciel puisse toujours compter sur l’obtention d’un certain type de réponse HTTP en retour de son appel à `get_response`. Les intergiciels n’ont pas besoin se se soucier d’envelopper leur appel à `get_response` dans un bloc `try/except` pour gérer une exception qui aurait pu être générée par un intergiciel suivant ou par la vue. Même si l’intergiciel suivant dans la chaîne génère une exception `Http404`, par exemple, votre intergiciel ne verra pas cette exception ; il obtiendra à la place un objet `HttpResponse` avec un code `status_code` 404.

## Gestion du code asynchrone

New in Django 3.1.

Les intergiciels peuvent prendre en charge n’importe quelle combinaison de requêtes synchrones et asynchrones. Django adapte les requêtes pour correspondre aux exigences des intergiciels si ceux-ci ne gèrent pas les deux types de requêtes, mais avec une baisse de performance.

Par défaut, Django part du principe qu’un intergiciel n’est capable de traiter que des requêtes synchrones. Pour modifier ce présupposé, définissez les attributs suivants sur la classe ou la fonction fabriquante d’intergiciel :

- `sync_capable` est une variable booléenne indiquant si l’intergiciel peut gérer des requêtes synchrones. Vaut `True` par défaut.
- `async_capable` est une variable booléenne indiquant si l’intergiciel peut gérer des requêtes asynchrones. Vaut `False` par défaut.

Si un intergiciel possède à la fois `sync_capable = True` et `async_capable = True`, Django lui transmet la requête sans la modifier. Dans ce cas, l’intergiciel peut savoir si la requête qu’il reçoit est asynchrone ou pas en vérifiant si l’objet `get_response` qu’il reçoit est une fonction coroutine, à l’aide de `asyncio.iscoroutinefunction()`.

Le module `django.utils.decorators` contient les décorateurs `sync_only_middleware()`, `async_only_middleware()` et `sync_and_async_middleware()` qui permettent d’attribuer les drapeaux adéquats aux fonctions fabriquantes d’intergiciels.

L’objet exécutable renvoyé doit correspondre à la nature synchrone ou asynchrone de la méthode `get_response`. Si vous recevez un `get_response` asynchrone, vous devez renvoyer une fonction coroutine (`async def`).

Les méthodes `process_view`, `process_template_response` et `process_exception`, quand elles sont présentes, doivent aussi être adaptées pour les modes synchrones/asynchrones. Cependant, Django les adapte individuellement si vous ne le faites pas, mais avec une perte de performance supplémentaire.

Voici un exemple de la manière de créer une fonction d’intergiciel qui prend en charge les deux modes

    import asyncio
    from django.utils.decorators import sync_and_async_middleware

    @sync_and_async_middleware
    def simple_middleware(get_response):
        # One-time configuration and initialization goes here.
        if asyncio.iscoroutinefunction(get_response):
            async def middleware(request):
                # Do something here!
                response = await get_response(request)
                return response

        else:
            def middleware(request):
                # Do something here!
                response = get_response(request)
                return response

        return middleware

Note

Si vous déclarez un intergiciel hybride qui prend en charge à la fois les appels synchrones et asynchrones, le type d’appel que vous obtenez pourrait ne pas correspondre à la vue sous-jacente. Django optimise la pile d’appel des intergiciels pour qu’il y ait le moins de transitions synchrones/asynchrones que possible.

Ainsi, même si vous enveloppez une vue asynchrone, elle pourrait être appelée en mode synchrone s’il y a d’autres intergiciels synchrones entre son exécution et la vue.

## Mise à jour d’intergiciels écrits avant Django 1.10

class `django.utils.deprecation.``MiddlewareMixin`

Django fournit `django.utils.deprecation.MiddlewareMixin` pour faciliter la création de classes d’intergiciel qui sont compatibles à la fois avec `MIDDLEWARE` et l’ancien `MIDDLEWARE_CLASSES`, et qui prennent en charge les requêtes synchrones et asynchrones. Toutes les classes d’intergiciel incluses dans Django sont compatibles avec les deux réglages.

Cette classe « mixin » fournit une méthode `__init__()` exigeant un paramètre `get_response` et le stockant dans `self.get_response`.

La méthode `__call__()`:

1. Appelle `self.process_request(request)` (si elle est définie).
2. Appelle `self.get_response(request)` pour obtenir la réponse du dernier intergiciel et de la vue.
3. Appelle `self.process_response(request, response)` (si elle est définie).
4. Renvoie la réponse.

Quand elle est utilisée avec `MIDDLEWARE_CLASSES`, la méthode `__call__()` ne sera jamais utilisée ; Django appelle directement `process_request()` et `process_response()`.

Dans la plupart des cas, l’héritage de cette classe « mixin » suffit à rendre compatible un intergiciel ancien style avec le nouveau système avec suffisamment de rétro-compatibilité. La nouvelle sémantique de court-circuitage ne fera pas de mal ou sera même avantageuse pour l’intergiciel existant. Dans quelques cas, une classe d’intergiciel pourrait avoir besoin de certains changements pour s’ajuster à la nouvelle sémantique.

Voici les différences de comportement entre l’utilisation de `MIDDLEWARE` et de `MIDDLEWARE_CLASSES`:

1. Avec `MIDDLEWARE_CLASSES`, chaque intergiciel verra toujours sa méthode `process_response` appelée, même si un intergiciel précédent a court-circuité le processus en renvoyant une réponse de sa méthode `process_request`. Avec `MIDDLEWARE`, les intergiciels se comportent plus comme un oignon : les couches que parcourt une réponse jusqu’à sa sortie sont les mêmes que la requête a vu passer dans le sens inverse. Si un intergiciel court-circuite, seul cet intergiciel et ceux qui le précèdent dans `MIDDLEWARE` verront passer la réponse.
2. Avec `MIDDLEWARE_CLASSES`, `process_exception` est appliquée aux exceptions générées depuis une méthode `process_request` d’intergiciel. Avec `MIDDLEWARE`, `process_exception` ne s’applique qu’aux exceptions générées dans la vue (ou depuis la méthode `render` d’une réponse `TemplateResponse`). Les exceptions générées depuis un intergiciel sont converties en une réponse HTTP appropriée puis transmises à l’intergiciel suivant.
3. Avec `MIDDLEWARE_CLASSES`, si une méthode `process_response` génère une exception, les méthodes `process_response` de tous les intergiciels précédents sont omises et une réponse HTTP `500 erreur de serveur interne` est toujours renvoyée (même si l’exception générée était par exemple `Http404`). Avec `MIDDLEWARE`, une exception générée depuis un intergiciel est immédiatement convertie en une réponse HTTP appropriée, puis le prochain intergiciel dans la chaîne verra la réponse. Les intergiciels ne sont jamais outrepassés en raison d’une exception générée dans un autre intergiciel.

Changed in Django 3.1:

La prise en charge des requêtes asynchrones a été ajoutée dans `MiddlewareMixin`.