Function-Based Views & Shortcuts

Returning HttpResponseNotFound(…​) makes you responsible for the page’s HTML. Raising an exception instead lets Django pick the standard error view, so every error page on the site looks the same and can be customised in one place. The exceptions views usually raise are:

Source: Django: Built-in views - error views

The first two lines of the table are what the shortcuts below rely on: get_object_or_404() is nothing more than a lookup that raises Http404. The error views and how to customise them are covered in Built-in views.

A function declared with def is a synchronous view; one declared with async def is an asynchronous view. Django detects which it is and adapts: under a WSGI server a sync view runs in the worker thread and an async view gets a one-off event loop per request (it works, but there is no concurrency benefit); under an ASGI server an async view runs on the event loop, while a sync view is run in a thread pool through sync_to_async() so it cannot block the loop. Mixing both styles in one project is supported; the cost is a thread hop for each sync view or sync middleware on an ASGI stack.

Source: Django: Asynchronous support - async views

Source: Django: Testing asynchronous code

Inside an async view, synchronous ORM calls (Book.objects.get(), iterating a QuerySet) raise SynchronousOnlyOperation; use the async API (aget(), async for, acount()) as described on Making Queries, the a-prefixed shortcuts below, or sync_to_async(). The decorators on this page work on both kinds of view (Decorators and async views). The full async model, including ASGI deployment, is the subject of Async Support.

render(request, template_name, context=None, content_type=None, status=None, using=None) loads the template, renders it with the context and the request (so context processors such as request, user and messages run) and returns an HttpResponse. template_name may be a sequence, in which case the first template that exists is used. status sets the status code and using names the template engine. Callable values in context are called just before rendering. It always returns a normal HttpResponse; if you want a lazily rendered response that middleware or decorators can still modify, build a TemplateResponse yourself (the docs note that TemplateResponse’s constructor is as convenient as `render(), so there is no shortcut for it).

Source: Django: Shortcuts - render

The detail template contains a small form; the {% csrf_token %} tag is what lets the POST in redirect() and resolve_url() pass CSRF validation:

Source: Django: Cross Site Request Forgery protection

The template language itself is covered on Templates. Note that render() replaced the Django 1.x idiom render_to_response("page.html", ctx, context_instance=RequestContext(request)); render_to_response() was removed in Django 3.0 (see Where the books are outdated).

get_object_or_404(klass, *args, **kwargs) calls get() and raises Http404 instead of DoesNotExist. klass may be a model class, a Manager or a QuerySet; positional arguments are Q objects and keyword arguments are ordinary lookups. Because a QuerySet is accepted, the lookup can be restricted to rows the caller may see, which is how the detail view above hides unpublished books. MultipleObjectsReturned is not translated: a lookup that matches several rows is a bug and surfaces as a 500.

get_list_or_404(klass, *args, **kwargs) returns list(filter(…​)) and raises Http404 when that list is empty. Use it only when "empty" really means "no such page" (a category with no items); for a search that may legitimately return nothing, render an empty result instead. Both have async twins, aget_object_or_404() and aget_list_or_404(), added in Django 5.0.

Source: Django: Shortcuts - get_object_or_404 and get_list_or_404

Source: Django: Testing tools - assertions

redirect(to, *args, permanent=False, preserve_request=False, max_length=MAX_URL_REDIRECT_LENGTH, **kwargs) returns an HttpResponseRedirect (or its permanent twin). The to argument is resolved in this order:

By default the redirect is temporary (302); permanent=True makes it 301. preserve_request=True (Django 5.2) asks the browser to repeat the method and body at the new URL, which uses the 307 and 308 codes:

Source: Django: Shortcuts - redirect

max_length (Django 6.1) overrides the maximum URL length the redirect classes accept; pass None to disable the check. Leave it alone unless you really redirect to very long URLs.

resolve_url(to, *args, **kwargs) is the resolution step of redirect() on its own: it returns the URL string for a model, a view name or callable, or a literal string, which is useful when the URL goes somewhere other than a redirect, such as a response header or a JSON payload.

The classic use of redirect() is Post/Redirect/Get: after a successful POST, answer with a redirect to a GET page so a browser refresh does not resubmit the form. The reservation view below also shows the two other things a state-changing view needs: @require_POST (a link or a crawler can never trigger it with GET) and a transaction around a read-modify-write:

Source: Django: Shortcuts - resolve_url

Running the redirects:

Source: Django: Testing tools - assertRedirects

Two details of the reservation view are deliberate. F("reserved") + 1 makes the database do the increment, so two simultaneous requests cannot overwrite each other’s count; and raise Http404("Sold out") inside atomic() rolls the block back before the error page is produced. Transactions, select_for_update() and F() are explained on Transactions, Raw SQL & Multiple Databases and Aggregation, Expressions & Functions. Never redirect to a URL taken from the request (?next=…​) without checking it with url_has_allowed_host_and_scheme(); see Security.

require_http_methods(["GET", "POST"]) lets only the listed methods through (names must be uppercase); require_GET, require_POST and require_safe are shortcuts. require_safe allows GET and HEAD, which the docs prefer over require_GET because link checkers and caches send HEAD. The rejected request gets 405 and an Allow header listing what is accepted:

Source: Django: View decorators - allowed HTTP methods

The decorator does not make state changes safe by itself; it only enforces the verb. The state-changing view still needs CSRF protection (the next section) and authentication.

These decorators describe how clients and shared caches may reuse the response; they are separate from the server-side cache framework, which is covered on Caching.

Source: Django: View decorators - caching and Django: Cache framework - Vary headers

Response headers seen through curl against runserver, and the test-client output for book_export:

A POST to /catalog/report/ is answered 405 with Allow: GET, HEAD by the test client, but 403 over HTTP with curl: the CSRF middleware rejects the token-less POST before the view’s require_safe is reached, and the test client skips CSRF checks unless created with enforce_csrf_checks=True.

In Django 6.1 the cache keys produced for pages that vary on extra headers changed, so the first request to a previously cached page after upgrading is a miss (release notes, "Miscellaneous");

gzip_page compresses the response body when the browser sends Accept-Encoding: gzip and adds Vary: Accept-Encoding so caches store both variants. It is useful for a few large text responses; for a whole site, compress in the front-end web server instead, because compressing a response that contains a secret next to attacker-controlled text can leak the secret (the BREACH attack). The documentation of GZipMiddleware explains the risk and the mitigation Django applies (a few random bytes appended to each compressed response); a per-view decorator lets you limit compression to responses that carry no secrets.

Source: Django: View decorators - GZip compression

CsrfViewMiddleware is normally enabled for the whole project and rejects unsafe-method requests that lack a valid token. The decorators in django.views.decorators.csrf give per-view control: csrf_protect applies the protection to a view when the middleware is not installed; requires_csrf_token makes the token available in the template context without enforcing it; ensure_csrf_cookie forces the CSRF cookie to be sent (needed for a JavaScript client that reads the cookie before its first POST); and csrf_exempt turns the check off. csrf_exempt is almost never right for a browser-facing view; legitimate uses are webhooks verified by a signature of their own. The behaviour of the middleware is covered on Security.

Source: Django: CSRF - decorators

login_required(redirect_field_name="next", login_url=None) redirects anonymous users to settings.LOGIN_URL, appending the current path as ?next=. user_passes_test(test_func, login_url=None, redirect_field_name="next") does the same unless test_func(user) is true, and permission_required(perm, login_url=None, raise_exception=False) checks a permission (with raise_exception=True it raises PermissionDenied, so the user sees a 403 instead of the login page). Since Django 5.1 these decorators also wrap async views, and login_not_required() exempts a view when LoginRequiredMiddleware makes login the default for the whole project. Authorization design (object-level checks, groups) is on Permissions & Authorization.

Source: Django: The login_required decorator

Decorators apply from the bottom up and run from the top down: in book_report above, require_safe receives the request first, then vary_on_headers, then cache_control, then the view; the response travels back the other way. Two rules come out of this:

The CSRF middleware runs even before the view and its decorators, so a decorator can never see a request the middleware rejected.

A decorator is a function that takes a view and returns a view. Use functools.wraps so the wrapper keeps the view’s name and docstring (URL names, the admin docs and error reports use them). To support both kinds of view, return an async def wrapper for coroutine functions; inspect.iscoroutinefunction() is the test (in Python 3.14 asyncio.iscoroutinefunction() is deprecated):

Source: Django: Asynchronous support - decorators

Applied to async_book above (@require_GET outside, @timed inside), the test client receives the extra header:

If the same behaviour must run for every request, write middleware instead (see Middleware). To apply a function decorator to a method of a class-based view, wrap it with django.utils.decorators.method_decorator (which supports async methods since Django 5.2); see Class-Based Views.

Every decorator in the table above, including the authentication ones, can wrap an async def view. The CSRF, caching, conditional, gzip, HTTP-method, vary, debug and clickjacking decorators gained this in Django 5.0, the authentication decorators in Django 5.1, and method_decorator in 5.2; Custom decorators need the explicit branch shown above.

django.middleware.http.ConditionalGetMiddleware adds an ETag (a hash of the body) when the response has none, and replaces the response with 304 when the request’s If-None-Match or If-Modified-Since matches. It needs no changes to views, but the view still runs and the page is still built; only the network transfer is saved. It is global and only meaningful for GET. The conditional_page decorator gives the same behaviour to a single view. The middleware is explained further on Middleware.

Source: Django: ConditionalGetMiddleware

When the validator is much cheaper than the page, condition(etag_func=None, last_modified_func=None) bails out before the view runs. Each function receives the request and the same arguments as the view (so pk is available) and returns:

The decorator then compares them with If-None-Match, If-Match, If-Modified-Since and If-Unmodified-Since, calls the view only if a fresh copy is needed, and for safe methods (GET and HEAD) sets ETag and Last-Modified on the response unless the view already set them. etag and last_modified are the single-validator versions. A function that returns None does not make the request 404; the view still runs and decides, which is why the view below also uses get_object_or_404().

The same two functions serve a GET (conditional fetch) and a PUT (conditional update), exactly as the docs recommend:

Source: Django: Conditional view processing - the condition decorator

Each validator costs one indexed one-column query, which is the point: a 304 takes a single SELECT instead of rendering a page. Exercising every branch:

Source: Django: Conditional view processing - other HTTP methods

The last line is the whole point of If-Match: the second client still holds the old ETag, the first update changed updated, so the replay is refused instead of silently overwriting the new price. The same exchange over HTTP, from the curl session against runserver:

(A curl -X PUT to this URL is answered 403 by CSRF protection, because the view is a browser-style Django view; machine clients that update resources normally use an API layer with token authentication, see Django REST Framework. The test client skips CSRF by default, which is why the test above can send the PUT.)

When condition() answers 304 or 412, the decorators below it are skipped. RFC 9110 requires Vary, Cache-Control and the like to be present on a 304, so decorators that set those headers must sit above condition(). The test below runs the same view both ways and prints the Vary header of the 304:

Source: Django: Conditional view processing - order of decorators

Two further rules from the docs. First, do not chain @etag(…​) and @last_modified(…​) to test both validators: the first decorator knows nothing about the second and may answer "not modified" when the second would disagree; use one condition() call. Second, for non-safe methods condition does not set validators on the response, as the view above does by hand (RFC 9110 distinguishes the PUT and POST cases).

Choose between the two tools by cost: if pages are cheap to build, ConditionalGetMiddleware saves bandwidth with no code; if a page is expensive and a validator is cheap (a timestamp column, a version counter), use condition() and avoid the work. The ETag function should return the same value for the same state every time, so derive it from data that changes with the content (a version column, updated, a hash), never from id(…​) or the current time. Django 3.1 also stopped ConditionalGetMiddleware from adding an ETag to responses with an empty body.

django.views.static.serve(request, path, document_root, show_indexes=False) serves any directory. It exists for development (the docs state it is not hardened for production, where a real front-end web server or object storage should serve the files); the usual use is user uploads under MEDIA_ROOT, which django.contrib.staticfiles deliberately does not handle. The helper django.conf.urls.static.static(prefix, document_root=…​) builds the URL pattern for you and returns an empty list unless DEBUG is true, so it is safe to leave in a production URLconf:

Source: Django: Built-in views - serving files in development

The equivalent explicit form is re_path(r"^media/(?P<path>.*)$", serve, {"document_root": settings.MEDIA_ROOT}) inside an if settings.DEBUG: block. A test with a temporary MEDIA_ROOT shows both the happy path and the path-traversal defence:

Source: Django: static.serve

(The traversal attempt raises SuspiciousFileOperation, a SuspiciousOperation, so it is answered with the 400 error view.) How uploads get into MEDIA_ROOT and how storage is configured is on File Uploads & Storage; the static-assets side (collectstatic, STORAGES) is on Static Files & Front-End Assets.

Django provides four views in django.views.defaults; none of them is used while DEBUG = True (you get the technical debug pages instead), so test error pages with DEBUG = False.

Source: Django: Built-in views - error views

To change the behaviour, point the module-level handler404, handler500, handler403 and handler400 variables in the root URLconf at your own views (setting them anywhere else has no effect). The CSRF failure page is replaced through the CSRF_FAILURE_VIEW setting, not through a handler.

Source: Django: Writing views - customizing error views

Wrapping the defaults like this is only a skeleton; a real handler adds logging, a search box or a correlation id. The 404 template used here reads the variable the default view supplies:

Source: Django: Built-in views - the 404 view

Three views that raise the exceptions, and a test with DEBUG = False (a view that raises an unexpected exception normally re-raises it through the test client, so the client is told not to):

Source: Django: Built-in views - error views

Source: Django: Writing views - testing custom error views

(The suite prints each status separately; the four lines are the same real output.) In production, an unhandled exception should also be reported: see Logging & Error Reporting. Keep 500.html static: the default view renders it with an empty context precisely so it cannot fail in turn.