# Documentation Django 6.0.7

# Les fonctions raccourcis de Django

Le paquet `django.shortcuts` rassemble des fonctions et des classes utilitaires qui recouvrent plusieurs niveaux de l’architecture MVC. En d’autres termes, ces fonctions/classes introduisent un couplage contrôlé à des fins de commodité.

## `render()`

render(request, template_name, context=None, content_type=None, status=None, using=None)

  Combine un gabarit donné avec un dictionnaire contexte donné et renvoie un objet `HttpResponse` avec le texte résultant.

  Django ne met pas à disposition de fonction raccourci renvoyant une réponse `TemplateResponse` parce que le constructeur de `TemplateResponse` présente le même niveau de flexibilité que `render()`.

### Paramètres obligatoires

`request`

  L’objet requête utilisé pour générer la réponse.

`template_name`

  Le nom complet d’un gabarit à utiliser ou une liste de noms de gabarits. Si une liste est donnée, le premier gabarit de la liste qui est trouvé sera utilisé. Consultez la documentation du chargement de gabarits pour plus d’informations sur la façon dont les gabarits sont recherchés.

### Paramètres facultatifs

`context`

  Un dictionnaire de valeurs à ajouter un contexte du gabarit. Par défaut, ce dictionnaire est vide. Si une des valeurs du dictionnaire est exécutable, la vue l’appellera immédiatement avant de faire le rendu du gabarit.

`content_type`

  Le type MIME à utiliser pour le document produit. La valeur par défaut est `'text/html'`.

`status`

  Le code d’état de la réponse. La valeur par défaut est `200`.

`using`

  Le nom `NAME` d’un moteur de gabarit à utiliser pour charger le gabarit.

### Exemple

L’exemple suivant effectue le rendu du gabarit `myapp/index.html` avec le type MIME application/xhtml+xml:

    from django.shortcuts import render

    def my_view(request):
        # View code here...
        return render(
            request,
            "myapp/index.html",
            {
                "foo": "bar",
            },
            content_type="application/xhtml+xml",
        )

Cet exemple est équivalent à :

    from django.http import HttpResponse
    from django.template import loader

    def my_view(request):
        # View code here...
        t = loader.get_template("myapp/index.html")
        c = {"foo": "bar"}
        return HttpResponse(t.render(c, request), content_type="application/xhtml+xml")

## `redirect()`

redirect(to, *args, permanent=False, preserve_request=False, max_length=MAX_URL_REDIRECT_LENGTH, **kwargs)

  Renvoie une réponse `HttpResponseRedirect` à l’URL correspondant aux paramètres transmis.

  Les paramètres peuvent être :

  - Un modèle : la fonction `get_absolute_url()` du modèle sera appelée.

  - Un nom de vue, et potentiellement des paramètres : `reverse()` sera utilisée pour résoudre le nom.

  - Une URL absolue ou relative qui sera utilisée telle quelle comme emplacement de redirection.

  Par défaut, une redirection temporaire produit un code d’état 302. Si `permanent=True`, la redirection temporaire produit un code d’état 301.

  Si `preserve_request=True`, la réponse indique à l’agent utilisateur de préserver la méthode et le corps de la requête d’origine lors de la redirection. Dans ce cas, les redirections temporaires utilisent un code d’état 307 et les redirections permanentes un code 308. Le tableau suivant en présente une meilleure illustration :

  permanent | preserve_request | Code d’état HTTP
  --- | --- | ---
  `True` | `False` | 301
  `False` | `False` | 302
  `False` | `True` | 307
  `True` | `True` | 308

  An optional `max_length` keyword argument can be provided to override the maximum allowed length for the redirect URL. Set it to `None` to disable the length check.

  Changed in Django 6.1:

  `max_length` was added.

### Exemples

La fonction `redirect()` peut être utilisée de différentes manières.

1. En lui passant un objet ; la méthode `get_absolute_url()` de l’objet est appelée pour produire l’URL de redirection :

       from django.shortcuts import redirect

       def my_view(request):
           ...
           obj = MyModel.objects.get(...)
           return redirect(obj)

2. En lui passant le nom d’une vue et, en option, des paramètres positionnels ou nommés ; l’URL sera résolue en utilisant la méthode `reverse()`:

       def my_view(request):
           ...
           return redirect("some-view-name", foo="bar")

3. En lui passant une URL de redirection fixe :

       def my_view(request):
           ...
           return redirect("/some/url/")

   Cela fonctionne aussi avec des URL complètes :

       def my_view(request):
           ...
           return redirect("https://example.com/")

Par défaut, `redirect()` renvoie une redirection temporaire. Toutes les formes ci-dessus acceptent un paramètre `permanent` qui, s’il est défini à `True`, produit une redirection permanente :

    def my_view(request):
        ...
        obj = MyModel.objects.get(...)
        return redirect(obj, permanent=True)

De plus, l’argument `preserve_request` peut être utilisé pour préserver la méthode HTTP d’origine :

    def my_view(request):
        # ...
        obj = MyModel.objects.get(...)
        if request.method in ("POST", "PUT"):
            # Redirection preserves the original request method.
            return redirect(obj, preserve_request=True)
        # ...

## `resolve_url()`

resolve_url(to, *args, **kwargs)

  Renvoie une chaîne URL en résolvant et normalisant l’argument `to` dans une URL concrète. Le paramètre `to` peut être :

  - Un objet implémentant `get_absolute_url()`, auquel cas la méthode sera appelée et son résultat renvoyé.

  - Un nom de vue, une fonction de vue ou une classe de vue, avec de potentiels paramètres transmis dans `*args` et `**kwargs`, auquel cas `reverse()` sera appelée pour résoudre/déterminer la vue.

  - Une chaîne d’URL qui sera renvoyée telle quelle.

  Cette fonction est utilisée en interne par le raccourci `redirect()` pour déterminer l’URL cible de l’emplacement de redirection.

### Exemples

1. Résolution d’une URL pour un modèle définissant `get_absolute_url()`:

   `models.py`

       from django.db import models
       from django.urls import reverse

       class Article(models.Model):
           title = models.CharField(max_length=100)

           def get_absolute_url(self):
               return reverse("article-detail", args=[self.pk])

   `views.py`

       from django.http import JsonResponse
       from django.shortcuts import get_object_or_404, resolve_url
       from .models import Article

       def article_api_view(request, pk):
           """Return metadata about an article, including its canonical URL."""
           article = get_object_or_404(Article, pk=pk)
           return JsonResponse(
               {
                   "id": article.pk,
                   "title": article.title,
                   "url": resolve_url(article),
               }
           )

2. Résolution d’une URL cible à utiliser pour une redirection, comme dans un en-tête de réponse HTTP :

       from django.conf import settings
       from django.http import HttpResponse
       from django.shortcuts import resolve_url

       def login_success(request):
           response = HttpResponse("Login successful")
           response["X-Next-URL"] = resolve_url(settings.LOGIN_REDIRECT_URL)
           return response

## `get_object_or_404()`

get_object_or_404(klass, *args, **kwargs)

aget_object_or_404(klass, *args, **kwargs)

  Version asynchrone : `aget_object_or_404()`

  Appelle `get()` d’un gestionnaire de modèle donné, mais génère une exception `Http404` au lieu de l’exception `DoesNotExist` du modèle.

### Paramètres

`klass`

  Une classe `Model`, un `Manager` ou une instance `QuerySet` comme source de l’objet.

`*args`

  Objets Q().

`**kwargs`

  Paramètres de recherche, dans un format accepté par `get()` et `filter()`.

### Exemple

L’exemple suivant obtient l’objet``MyModel`` ayant la clé primaire 1 :

    from django.shortcuts import get_object_or_404

    def my_view(request):
        obj = get_object_or_404(MyModel, pk=1)

Cet exemple est équivalent à :

    from django.http import Http404

    def my_view(request):
        try:
            obj = MyModel.objects.get(pk=1)
        except MyModel.DoesNotExist:
            raise Http404("No MyModel matches the given query.")

Le cas le plus courant est de transmettre un `Model`, comme montré ci-dessus. Cependant, vous pouvez aussi transmettre une instance `QuerySet`:

    queryset = Book.objects.filter(title__startswith="M")
    get_object_or_404(queryset, pk=1)

L’exemple ci-dessus est un peu tiré par les cheveux, car il est équivalent à :

    get_object_or_404(Book, title__startswith="M", pk=1)

mais cela reste utile dans les cas où vous recevez une variable `queryset` par un autre moyen.

Finalement, vous pouvez aussi utiliser un gestionnaire (`Manager`). C’est utile par exemple si vous avez un gestionnaire personnalisé

    get_object_or_404(Book.dahl_objects, title="Matilda")

Il est aussi possible d’utiliser des `gestionnaires de liaison`:

    author = Author.objects.get(name="Roald Dahl")
    get_object_or_404(author.book_set, title="Matilda")

Note : comme pour `get()`, une exception `MultipleObjectsReturned` sera levée si plus d’un objet est renvoyé.

## `get_list_or_404()`

get_list_or_404(klass, *args, **kwargs)

aget_list_or_404(klass, *args, **kwargs)

  Version asynchrone : `aget_list_or_404()`

  Renvoie le résultat de `filter()` sur un gestionnaire de modèle donné transformé en liste, générant `Http404` si la liste résultante est vide.

### Paramètres

`klass`

  Une instance de `Model`, `Manager` ou `QuerySet` comme source de la liste d’objets.

`*args`

  Objets Q().

`**kwargs`

  Paramètres de recherche, dans un format accepté par `get()` et `filter()`.

### Exemple

L’exemple suivant récupère tous les objets publiés de

    from django.shortcuts import get_list_or_404

    def my_view(request):
        my_objects = get_list_or_404(MyModel, published=True)

Cet exemple est équivalent à :

    from django.http import Http404

    def my_view(request):
        my_objects = list(MyModel.objects.filter(published=True))
        if not my_objects:
            raise Http404("No MyModel matches the given query.")