Django shortcut functions

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

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]

Combines a given template with a given context dictionary and returns an HttpResponse object with that rendered text.

render() is the same as a call to render_to_response() with a context_instance argument that forces the use of a RequestContext.

Django does not provide a shortcut function which returns a TemplateResponse because the constructor of TemplateResponse offers the same level of 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.

Optional arguments

context

A dictionary of values to add to the template context. By default, this is an empty dictionary. If a value in the dictionary is callable, the view will call it just before rendering the template.

The context argument used to be called dictionary. That name is deprecated in Django 1.8 and will be removed in Django 1.10.

context_instance

The context instance to render the template with. By default, the template will be rendered with a RequestContext instance (filled with values from request and context).

Deprecated since version 1.8: The context_instance argument is deprecated. Simply use context.

content_type
The MIME type to use for the resulting document. Defaults to the value of the DEFAULT_CONTENT_TYPE setting.
status
The status code for the response. Defaults to 200.
current_app

A hint indicating which application contains the current view. See the namespaced URL resolution strategy for more information.

Deprecated since version 1.8: The current_app argument is deprecated. Instead you should set request.current_app.

using
The NAME of a template engine to use for loading the template.

The using parameter was added.

The dirs parameter was added.

Deprecated since version 1.8: The dirs parameter was deprecated.

Example

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

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]

Renders a given template with a given context dictionary and returns an HttpResponse object with that rendered text.

Required arguments

template_name
The full name of a template to use or sequence of template names. If a sequence is given, the first template that exists will be used. See the template loading documentation for more information on how templates are found.

Optional arguments

context

A dictionary of values to add to the template context. By default, this is an empty dictionary. If a value in the dictionary is callable, the view will call it just before rendering the template.

The context argument used to be called dictionary. That name is deprecated in Django 1.8 and will be removed in Django 1.10.

context_instance

The context instance to render the template with. By default, the template will be rendered with a Context instance (filled with values from context). If you need to use context processors, render the template with a RequestContext instance instead. Your code might look something like this:

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

Deprecated since version 1.8: The context_instance argument is deprecated. Use the render() function instead which always makes RequestContext available.

content_type
The MIME type to use for the resulting document. Defaults to the value of the DEFAULT_CONTENT_TYPE setting.
status
The status code for the response. Defaults to 200.
using
The NAME of a template engine to use for loading the template.

The status and using parameters were added.

The dirs parameter was added.

Deprecated since version 1.8: The dirs parameter was deprecated.

Example

The following example renders the template myapp/index.html with the MIME type application/xhtml+xml:

from django.shortcuts import render_to_response

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

This example is equivalent to:

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

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

redirect

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

Returns an HttpResponseRedirect to the appropriate URL for 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: urlresolvers.reverse will be used to reverse-resolve the name.
  • An absolute or relative URL, which will be used as-is for the redirect location.

By default issues a temporary redirect; pass permanent=True to issue a permanent redirect.

The ability to use relative URLs was added.

Examples

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

  1. By passing some object; that object’s get_absolute_url() method will be called to figure out the redirect URL:

    from django.shortcuts import redirect
    
    def my_view(request):
        ...
        object = MyModel.objects.get(...)
        return redirect(object)
    
  2. By passing the name of a view and optionally some positional or keyword arguments; the URL will be reverse resolved using the reverse() method:

    def my_view(request):
        ...
        return redirect('some-view-name', foo='bar')
    
  3. 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('http://example.com/')
    

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

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]

Calls get() on a given model manager, but it raises Http404 instead of the model’s DoesNotExist exception.

Required arguments

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

Example

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

from django.shortcuts import get_object_or_404

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

This example is equivalent to:

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

The most common use case is to pass a Model, as shown above. However, you can also pass a QuerySet 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 somewhere else.

Finally, you can also use a Manager. This is useful for example if you have a custom manager:

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

You can also use related managers:

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

Note: As with get(), a MultipleObjectsReturned exception will be raised if more than one object is found.

get_list_or_404

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

Returns the result of filter() on a given model manager cast to a list, raising Http404 if the resulting list is empty.

Required arguments

klass
A Model, Manager or QuerySet instance from which to get the list.
**kwargs
Lookup parameters, which should be in the format accepted by get() and filter().

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

© Django Software Foundation and individual contributors
Licensed under the BSD License.
https://docs.djangoproject.com/en/1.8/topics/http/shortcuts/