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, context_instance=_context_instance_undefined, content_type=None, status=None, current_app=_current_app_undefined, dirs=_dirs_undefined, using=None)[source]

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.

Changed in Django 1.8:

Le paramètre context était appelé dictionary. Ce nom est obsolète dans Django 1.8 et sera supprimé dans Django 1.10.

context_instance

L’instance de contexte avec laquelle effectuer le rendu du gabarit. Par défaut, le gabarit sera rendu avec une instance RequestContext (complétée par des valeurs de request et context).

Obsolète depuis la version 1.8: Le paramètre context_instance est obsolète. Utilisez simplement context.

content_type

Le type MIME à utiliser pour le document produit. La valeur par défaut est celle du réglage DEFAULT_CONTENT_TYPE.

status

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

current_app

Une indication de l’application contenant la vue actuelle. Consultez la stratégie de résolution des URL en espaces de noms pour plus d’informations.

Obsolète depuis la version 1.8: Le paramètre current_app est obsolète. Vous devriez plutôt définir request.current_app.

using

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

Changed in Django 1.8:

Le paramètre using a été ajouté.

Obsolète depuis la version 1.8: Le paramètre dirs a été rendu osbolète.

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')

render_to_response()

render_to_response(template_name, context=None, context_instance=_context_instance_undefined, content_type=None, status=None, dirs=_dirs_undefined, using=None)[source]

Cette fonction a précédé l’introduction de render() et fonctionne de manière similaire, sauf qu’elle ne rend pas la requête disponible dans la réponse. Elle n’est plus recommandée et va probablement être rendue obsolète à l’avenir.

Paramètres obligatoires

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.

Changed in Django 1.8:

Le paramètre context était appelé dictionary. Ce nom est obsolète dans Django 1.8 et sera supprimé dans Django 1.10.

context_instance

L’instance de contexte avec laquelle effectuer le rendu du gabarit. Par défaut, le gabarit sera rendu avec une instance Context (complétée par des valeurs de context). Si vous avez besoin d’utiliser des processeurs de contexte, produisez plutôt le gabarit avec une instance RequestContext. Votre code pourrait ressembler à ceci :

return render_to_response('my_template.html',
                          my_context,
                          context_instance=RequestContext(request))

Obsolète depuis la version 1.8: Le paramètre context_instance est obsolète. Utilisez plutôt la fonction render() qui rend toujours disponible l’objet RequestContext.

content_type

Le type MIME à utiliser pour le document produit. La valeur par défaut est celle du réglage DEFAULT_CONTENT_TYPE.

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.

Changed in Django 1.8:

Les paramètres status et using ont été ajoutés.

Obsolète depuis la version 1.8: Le paramètre dirs a été rendu osbolète.

redirect()

redirect(to, permanent=False, *args, **kwargs)[source]

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  : urlresolvers.reverse sera utilisée pour résoudre le nom.

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

Produit par défaut une redirection temporaire ; indiquez permanent=True pour produire une redirection permanente.

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):
        ...
        object = MyModel.objects.get(...)
        return redirect(object)
    
  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):
    ...
    object = MyModel.objects.get(...)
    return redirect(object, permanent=True)

get_object_or_404()

get_object_or_404(klass, *args, **kwargs)[source]

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 obligatoires

klass

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

**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):
    my_object = get_object_or_404(MyModel, pk=1)

Cet exemple est équivalent à :

from django.http import Http404

def my_view(request):
    try:
        my_object = 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)[source]

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 obligatoires

klass

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

**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.")
Back to Top