Writing views¶
A view function, orview for short, is a Python function that takes a webrequest and returns a web response. This response can be the HTML contents of aweb page, or a redirect, or a 404 error, or an XML document, or an image …or anything, really. The view itself contains whatever arbitrary logic isnecessary to return that response. This code can live anywhere you want, aslong as it’s on your Python path. There’s no other requirement–no “magic,” soto speak. For the sake of putting the codesomewhere, the convention is toput views in a file calledviews.py, placed in your project or applicationdirectory.
A simple view¶
Here’s a view that returns the current date and time, as an HTML document:
fromdjango.httpimportHttpResponseimportdatetimedefcurrent_datetime(request):now=datetime.datetime.now()html='<html lang="en"><body>It is now%s.</body></html>'%nowreturnHttpResponse(html)
Let’s step through this code one line at a time:
First, we import the class
HttpResponsefrom thedjango.httpmodule, along with Python’sdatetimelibrary.Next, we define a function called
current_datetime. This is the viewfunction. Each view function takes anHttpRequestobject as its first parameter, which is typically namedrequest.Note that the name of the view function doesn’t matter; it doesn’t have tobe named in a certain way in order for Django to recognize it. We’recalling it
current_datetimehere, because that name clearly indicateswhat it does.The view returns an
HttpResponseobject thatcontains the generated response. Each view function is responsible forreturning anHttpResponseobject. (There areexceptions, but we’ll get to those later.)
Django’s Time Zone
Django includes aTIME_ZONE setting that defaults toAmerica/Chicago. This probably isn’t where you live, so you might wantto change it in your settings file.
Mapping URLs to views¶
So, to recap, this view function returns an HTML page that includes the currentdate and time. To display this view at a particular URL, you’ll need to createaURLconf; seeURL dispatcher for instructions.
Returning errors¶
Django provides help for returning HTTP error codes. There are subclasses ofHttpResponse for a number of common HTTP status codesother than 200 (which means“OK”). You can find the full list of availablesubclasses in therequest/responsedocumentation. Return an instance of one of those subclasses instead of anormalHttpResponse in order to signify an error. Forexample:
fromdjango.httpimportHttpResponse,HttpResponseNotFounddefmy_view(request):# ...iffoo:returnHttpResponseNotFound("<h1>Page not found</h1>")else:returnHttpResponse("<h1>Page was found</h1>")
There isn’t a specialized subclass for every possible HTTP response code,since many of them aren’t going to be that common. However, as documented intheHttpResponse documentation, you can also pass theHTTP status code into the constructor forHttpResponseto create a return class for any status code you like. For example:
fromdjango.httpimportHttpResponsedefmy_view(request):# ...# Return a "created" (201) response code.returnHttpResponse(status=201)
Because 404 errors are by far the most common HTTP error, there’s an easier wayto handle those errors.
TheHttp404 exception¶
- classdjango.http.Http404¶
When you return an error such asHttpResponseNotFound,you’re responsible for defining the HTML of the resulting error page:
returnHttpResponseNotFound("<h1>Page not found</h1>")
For convenience, and because it’s a good idea to have a consistent 404 errorpage across your site, Django provides anHttp404 exception. If you raiseHttp404 at any point in a view function, Django will catch it and returnthe standard error page for your application, along with an HTTP error code404.
Example usage:
fromdjango.httpimportHttp404fromdjango.shortcutsimportrenderfrompolls.modelsimportPolldefdetail(request,poll_id):try:p=Poll.objects.get(pk=poll_id)exceptPoll.DoesNotExist:raiseHttp404("Poll does not exist")returnrender(request,"polls/detail.html",{"poll":p})
In order to show customized HTML when Django returns a 404, you can create anHTML template named404.html and place it in the top level of yourtemplate tree. This template will then be served whenDEBUG is settoFalse.
WhenDEBUG isTrue, you can provide a message toHttp404 andit will appear in the standard 404 debug template. Use these messages fordebugging purposes; they generally aren’t suitable for use in a production 404template.
Customizing error views¶
The default error views in Django should suffice for most web applications,but can easily be overridden if you need any custom behavior. Specify thehandlers as seen below in your URLconf (setting them anywhere else will have noeffect).
Thepage_not_found() view is overridden byhandler404:
handler404="mysite.views.my_custom_page_not_found_view"
Theserver_error() view is overridden byhandler500:
handler500="mysite.views.my_custom_error_view"
Thepermission_denied() view is overridden byhandler403:
handler403="mysite.views.my_custom_permission_denied_view"
Thebad_request() view is overridden byhandler400:
handler400="mysite.views.my_custom_bad_request_view"
See also
Use theCSRF_FAILURE_VIEW setting to override the CSRF errorview.
Testing custom error views¶
To test the response of a custom error handler, raise the appropriate exceptionin a test view. For example:
fromdjango.core.exceptionsimportPermissionDeniedfromdjango.httpimportHttpResponsefromdjango.testimportSimpleTestCase,override_settingsfromdjango.urlsimportpathdefresponse_error_handler(request,exception=None):returnHttpResponse("Error handler content",status=403)defpermission_denied_view(request):raisePermissionDeniedurlpatterns=[path("403/",permission_denied_view),]handler403=response_error_handler# ROOT_URLCONF must specify the module that contains handler403 = ...@override_settings(ROOT_URLCONF=__name__)classCustomErrorHandlerTests(SimpleTestCase):deftest_handler_renders_template_response(self):response=self.client.get("/403/")# Make assertions on the response here. For example:self.assertContains(response,"Error handler content",status_code=403)
Async views¶
As well as being synchronous functions, views can also be asynchronous(“async”) functions, normally defined using Python’sasyncdef syntax.Django will automatically detect these and run them in an async context.However, you will need to use an async server based on ASGI to get theirperformance benefits.
Here’s an example of an async view:
importdatetimefromdjango.httpimportHttpResponseasyncdefcurrent_datetime(request):now=datetime.datetime.now()html='<html lang="en"><body>It is now%s.</body></html>'%nowreturnHttpResponse(html)
You can read more about Django’s async support, and how to best use asyncviews, inAsynchronous support.
