# Documentation Django 5.2.8

# Écriture de vues

Une fonction de vue, ou vue pour faire simple, est une fonction Python acceptant une requête web et renvoyant une réponse web. Cette réponse peut contenir le contenu HTML d’une page web, une redirection, une erreur 404, un document XML, une image… ou vraiment n’importe quoi d’autre. La vue elle-même contient la logique nécessaire pour renvoyer une réponse. Ce code peut se trouver à l’emplacement de votre choix, pour autant qu’il soit dans le chemin Python. Il n’y a pas d’autres exigences, pas de « magie » comme on dit. Mais comme il faut bien mettre ce code quelque part, la convention est de placer les vues dans un fichier nommé `views.py` se trouvant dans un projet ou un répertoire d’application.

## Une vue simple

Voici une vue qui renvoie l’heure et la date actuelle, sous forme d’un document HTML :

    from django.http import HttpResponse
    import datetime

    def current_datetime(request):
        now = datetime.datetime.now()
        html = '<html lang="en"><body>It is now %s.</body></html>' % now
        return HttpResponse(html)

Passons ce code en revue ligne par ligne :

- Nous importons d’abord la classe `HttpResponse` à partir du module `django.http`, ainsi que la bibliothèque `datetime` de Python.

- Puis, nous définissons une fonction nommée `current_datetime`. C’est la fonction de vue. Chaque fonction de vue accepte un objet `HttpRequest` comme premier paramètre, typiquement nommé `request`.

  Remarquez que le nom de la fonction de vue n’a aucune importance ; la vue ne doit pas être nommée d’une certaine manière pour que Django puisse la reconnaître. Nous l’avons appelée `current_datetime` ici car ce nom indique clairement ce qu’elle fait.

- La vue renvoie un objet `HttpResponse` contenant la réponse générée. Chaque fonction de vue est chargée de renvoyer un objet `HttpResponse` (il y a des exceptions, mais nous les aborderons plus tard).

Le fuseau horaire de Django

Django contient un réglage `TIME_ZONE` (fuseau horaire) valant par défaut `America/Chicago`. Vous ne vivez probablement pas à cet endroit, vous allez donc la modifier dans votre fichier de réglages.

## Correspondance entre URL et vues

Ainsi, pour résumer, cette fonction de vue renvoie une page HTML contenant la date et l’heure actuelles. Pour afficher cette vue avec une URL particulière, il est nécessaire de créer une configuration d’URL. Voir Distribution des URL pour les instructions.

## Renvoi d’erreurs

Django propose de l’aide pour renvoyer des codes d’erreur HTTP. Il existe des sous-classes de `HttpResponse` pour tous les codes de statut HTTP les plus courants autres que 200 (qui signifie « OK »). La liste complète des sous-classes disponibles se trouve dans la documentation des requêtes/réponses. Renvoyez une instance de l’une de ces sous-classes au lieu d’une réponse `HttpResponse` normale afin de signaler une erreur. Par exemple :

    from django.http import HttpResponse, HttpResponseNotFound

    def my_view(request):
        # ...
        if foo:
            return HttpResponseNotFound("<h1>Page not found</h1>")
        else:
            return HttpResponse("<h1>Page was found</h1>")

Il n’existe pas de sous-classe spécialisée pour chaque code de réponse HTTP possible, car la plupart ne se rencontrent que très rarement. Cependant, comme décrit dans la documentation de `HttpResponse`, il est aussi possible de transmettre le code de statut HTTP au constructeur de `HttpResponse` pour créer une classe à renvoyer pour n’importe quel code de statut. Par exemple :

    from django.http import HttpResponse

    def my_view(request):
        # ...

        # Return a "created" (201) response code.
        return HttpResponse(status=201)

Comme les erreurs 404 sont de loin les erreurs HTTP les plus fréquentes, il existe une façon simplifiée de les traiter.

### L’exception `Http404`

class django.http.Http404

Lorsque vous renvoyez une erreur telle que `HttpResponseNotFound`, vous êtes chargé de définir le code HTML de la page d’erreur résultante :

    return HttpResponseNotFound("<h1>Page not found</h1>")

Par commodité et parce qu’il est conseillé d’avoir une page d’erreur 404 cohérente pour tout un site, Django fournit une exception `Http404`. Si vous générez `Http404` quelque part dans une fonction de vue, Django l’intercepte et renvoie la page d’erreur standard de l’application, en compagnie du code d’erreur HTTP 404.

Exemple d’utilisation :

    from django.http import Http404
    from django.shortcuts import render
    from polls.models import Poll

    def detail(request, poll_id):
        try:
            p = Poll.objects.get(pk=poll_id)
        except Poll.DoesNotExist:
            raise Http404("Poll does not exist")
        return render(request, "polls/detail.html", {"poll": p})

Afin de pouvoir afficher du HTML personnalisé lorsque Django répond avec une page 404, il est possible de créer un gabarit HTML nommé `404.html` et de le placer au premier niveau de l’arborescence des gabarits. Ce gabarit sera alors utilisé lorsque le réglage `DEBUG` est défini à `False`.

Lorsque `DEBUG` vaut `True`, vous pouvez fournir un message à `Http404` et il apparaîtra dans le gabarit 404 standard de débogage. Utilisez ces messages à des fins de débogage ; ils ne sont généralement pas adaptés aux gabarits 404 de production.

## Personnalisation des vues d’erreur

Les vues d’erreur par défaut de Django conviennent bien à la majorité des applications web, mais elles peuvent aisément être surchargées en cas de besoin particulier. Redéfinissez les gestionnaires correspondants comme démontré ci-dessous, dans la configuration d’URL racine (leur définition à tout autre endroit est sans effet).

La vue `page_not_found()` est surchargée par `handler404`:

    handler404 = "mysite.views.my_custom_page_not_found_view"

La vue `server_error()` est surchargée par `handler500`:

    handler500 = "mysite.views.my_custom_error_view"

La vue `permission_denied()` est surchargée par `handler403`:

    handler403 = "mysite.views.my_custom_permission_denied_view"

La vue `bad_request()` est surchargée par `handler400`:

    handler400 = "mysite.views.my_custom_bad_request_view"

Voir aussi

Utilisez le réglage `CSRF_FAILURE_VIEW` pour surcharger la vue d’erreur CSRF.

### Test des vues d’erreur personnalisées

Pour tester la réponse d’un gestionnaire d’erreur personnalisé, générez l’exception appropriée dans une vue de test. Par exemple

    from django.core.exceptions import PermissionDenied
    from django.http import HttpResponse
    from django.test import SimpleTestCase, override_settings
    from django.urls import path

    def response_error_handler(request, exception=None):
        return HttpResponse("Error handler content", status=403)

    def permission_denied_view(request):
        raise PermissionDenied

    urlpatterns = [
        path("403/", permission_denied_view),
    ]

    handler403 = response_error_handler

    # ROOT_URLCONF must specify the module that contains handler403 = ...
    @override_settings(ROOT_URLCONF=__name__)
    class CustomErrorHandlerTests(SimpleTestCase):
        def test_handler_renders_template_response(self):
            response = self.client.get("/403/")
            # Make assertions on the response here. For example:
            self.assertContains(response, "Error handler content", status_code=403)

## Vues asynchrones

Même si les vues sont généralement des fonctions synchrones, elles peuvent également être asynchrones (« async »), c’est-à-dire définie par la syntaxe Python `async def`. Django les détecte automatiquement et les exécute dans un contexte asynchrone. Cependant, vous devrez utiliser un serveur asynchrone basé sur ASGI pour obtenir les bénéfices de performance.

Voici un exemple d’une vue asynchrone

    import datetime
    from django.http import HttpResponse

    async def current_datetime(request):
        now = datetime.datetime.now()
        html = '<html lang="en"><body>It is now %s.</body></html>' % now
        return HttpResponse(html)

Vous trouverez plus d’informations au sujet de la prise en charge du code asynchrone par Django et sur la meilleure manière d’utiliser les vues asynchrones dans Gestion du code asynchrone.