Django shortcut functions

The package django.shortcuts collects helper functions and classes that“span” multiple levels of MVC. In other words, these functions/classesintroduce controlled coupling for convenience’s sake.

render()

• render(request, template_name, context=None, content_type=None, status=None, using=None)
• Combines a given template with a given context dictionary and returns anHttpResponse object with that rendered text.

Django does not provide a shortcut function which returns aTemplateResponse because the constructorof TemplateResponse offers the same levelof convenience as render().

Required arguments

• request
• The request object used to generate this response.
• template_name
• The full name of a template to use or sequence of template names. If asequence is given, the first template that exists will be used. See thetemplate loading documentation for moreinformation on how templates are found.

Optional arguments

• context
• A dictionary of values to add to the template context. By default, thisis an empty dictionary. If a value in the dictionary is callable, theview will call it just before rendering the template.
• content_type
• The MIME type to use for the resulting document. Defaults to'text/html'.
• status
• The status code for the response. Defaults to 200.
• using
• The NAME of a template engine to use forloading the template.

Example

The following example renders the template myapp/index.html with theMIME type 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')

This example is equivalent to:

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, **kwargs)
• Returns an HttpResponseRedirect to the appropriate URLfor the arguments passed.

The arguments could be:

• A model: the model’s get_absolute_url()function will be called.
• A view name, possibly with arguments: reverse() will beused to reverse-resolve the name.
• An absolute or relative URL, which will be used as-is for the redirectlocation.By default issues a temporary redirect; pass permanent=True to issue apermanent redirect.

Examples

You can use the redirect() function in a number of ways.

• By passing some object; that object’sget_absolute_url() method will be calledto figure out the redirect URL:

from django.shortcuts import redirect
 
def my_view(request):
    ...
    obj = MyModel.objects.get(...)
    return redirect(obj)

• By passing the name of a view and optionally some positional orkeyword arguments; the URL will be reverse resolved using thereverse() method:

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

• By passing a hardcoded URL to redirect to:

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

This also works with full URLs:

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

By default, redirect() returns a temporary redirect. All of the aboveforms accept a permanent argument; if set to True a permanent redirectwill be returned:

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

get_object_or_404()

• getobject_or_404(_klass, *args, **kwargs)
• Calls get() on a given model manager,but it raises Http404 instead of the model’sDoesNotExist exception.

Required arguments

• klass
• A Model class,a Manager,or a QuerySet instance from which to getthe object.
• **kwargs
• Lookup parameters, which should be in the format accepted by get() andfilter().

Example

The following example gets the object with the primary key of 1 fromMyModel:

from django.shortcuts import get_object_or_404
 
def my_view(request):
    obj = get_object_or_404(MyModel, pk=1)

This example is equivalent to:

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.")

The most common use case is to pass a Model, asshown above. However, you can also pass aQuerySet instance:

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

The above example is a bit contrived since it’s equivalent to doing:

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

but it can be useful if you are passed the queryset variable from somewhereelse.

Finally, you can also use a Manager. This is usefulfor example if you have acustom manager:

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

You can also userelated managers:

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

Note: As with get(), aMultipleObjectsReturned exceptionwill be raised if more than one object is found.

get_list_or_404()

• getlist_or_404(_klass, *args, **kwargs)
• Returns the result of filter() on agiven model manager cast to a list, raising Http404 ifthe resulting list is empty.

Required arguments

• klass
• A Model, Manager orQuerySet instance from which to get thelist.
• **kwargs
• Lookup parameters, which should be in the format accepted by get() andfilter().

Example

The following example gets all published objects from MyModel:

from django.shortcuts import get_list_or_404
 
def my_view(request):
    my_objects = get_list_or_404(MyModel, published=True)

This example is equivalent to:

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.")