<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" lang=""> <head> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <title>Writing views — Django 1.8.19 documentation</title> <link rel="stylesheet" href="../../_static/default.css" type="text/css" /> <link rel="stylesheet" href="../../_static/pygments.css" type="text/css" /> <script type="text/javascript"> var DOCUMENTATION_OPTIONS = { URL_ROOT: '../../', VERSION: '1.8.19', COLLAPSE_INDEX: false, FILE_SUFFIX: '.html', HAS_SOURCE: true }; </script> <script type="text/javascript" src="../../_static/jquery.js"></script> <script type="text/javascript" src="../../_static/underscore.js"></script> <script type="text/javascript" src="../../_static/doctools.js"></script> <link rel="index" title="Index" href="../../genindex.html" /> <link rel="search" title="Search" href="../../search.html" /> <link rel="top" title="Django 1.8.19 documentation" href="../../contents.html" /> <link rel="up" title="Handling HTTP requests" href="index.html" /> <link rel="next" title="View decorators" href="decorators.html" /> <link rel="prev" title="URL dispatcher" href="urls.html" /> <script type="text/javascript" src="../../templatebuiltins.js"></script> <script type="text/javascript"> (function($) { if (!django_template_builtins) { // templatebuiltins.js missing, do nothing. return; } $(document).ready(function() { // Hyperlink Django template tags and filters var base = "../../ref/templates/builtins.html"; if (base == "#") { // Special case for builtins.html itself base = ""; } // Tags are keywords, class '.k' $("div.highlight\\-html\\+django span.k").each(function(i, elem) { var tagname = $(elem).text(); if ($.inArray(tagname, django_template_builtins.ttags) != -1) { var fragment = tagname.replace(/_/, '-'); $(elem).html("<a href='" + base + "#" + fragment + "'>" + tagname + "</a>"); } }); // Filters are functions, class '.nf' $("div.highlight\\-html\\+django span.nf").each(function(i, elem) { var filtername = $(elem).text(); if ($.inArray(filtername, django_template_builtins.tfilters) != -1) { var fragment = filtername.replace(/_/, '-'); $(elem).html("<a href='" + base + "#" + fragment + "'>" + filtername + "</a>"); } }); }); })(jQuery); </script> </head> <body role="document"> <div class="document"> <div id="custom-doc" class="yui-t6"> <div id="hd"> <h1><a href="../../index.html">Django 1.8.19 documentation</a></h1> <div id="global-nav"> <a title="Home page" href="../../index.html">Home</a> | <a title="Table of contents" href="../../contents.html">Table of contents</a> | <a title="Global index" href="../../genindex.html">Index</a> | <a title="Module index" href="../../py-modindex.html">Modules</a> </div> <div class="nav"> « <a href="urls.html" title="URL dispatcher">previous</a> | <a href="../index.html" title="Using Django" accesskey="U">up</a> | <a href="decorators.html" title="View decorators">next</a> »</div> </div> <div id="bd"> <div id="yui-main"> <div class="yui-b"> <div class="yui-g" id="topics-http-views"> <div class="section" id="s-writing-views"> <span id="writing-views"></span><h1>Writing views<a class="headerlink" href="#writing-views" title="Permalink to this headline">¶</a></h1> <p>A view function, or <em>view</em> for short, is simply a Python function that takes a Web request and returns a Web response. This response can be the HTML contents of a Web 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 is necessary to return that response. This code can live anywhere you want, as long as it’s on your Python path. There’s no other requirement–no “magic,” so to speak. For the sake of putting the code <em>somewhere</em>, the convention is to put views in a file called <code class="docutils literal"><span class="pre">views.py</span></code>, placed in your project or application directory.</p> <div class="section" id="s-a-simple-view"> <span id="a-simple-view"></span><h2>A simple view<a class="headerlink" href="#a-simple-view" title="Permalink to this headline">¶</a></h2> <p>Here’s a view that returns the current date and time, as an HTML document:</p> <div class="highlight-default"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">django.http</span> <span class="k">import</span> <span class="n">HttpResponse</span> <span class="kn">import</span> <span class="nn">datetime</span> <span class="k">def</span> <span class="nf">current_datetime</span><span class="p">(</span><span class="n">request</span><span class="p">):</span> <span class="n">now</span> <span class="o">=</span> <span class="n">datetime</span><span class="o">.</span><span class="n">datetime</span><span class="o">.</span><span class="n">now</span><span class="p">()</span> <span class="n">html</span> <span class="o">=</span> <span class="s2">"<html><body>It is now </span><span class="si">%s</span><span class="s2">.</body></html>"</span> <span class="o">%</span> <span class="n">now</span> <span class="k">return</span> <span class="n">HttpResponse</span><span class="p">(</span><span class="n">html</span><span class="p">)</span> </pre></div> </div> <p>Let’s step through this code one line at a time:</p> <ul> <li><p class="first">First, we import the class <a class="reference internal" href="../../ref/request-response.html#django.http.HttpResponse" title="django.http.HttpResponse"><code class="xref py py-class docutils literal"><span class="pre">HttpResponse</span></code></a> from the <a class="reference internal" href="../../ref/request-response.html#module-django.http" title="django.http: Classes dealing with HTTP requests and responses."><code class="xref py py-mod docutils literal"><span class="pre">django.http</span></code></a> module, along with Python’s <code class="docutils literal"><span class="pre">datetime</span></code> library.</p> </li> <li><p class="first">Next, we define a function called <code class="docutils literal"><span class="pre">current_datetime</span></code>. This is the view function. Each view function takes an <a class="reference internal" href="../../ref/request-response.html#django.http.HttpRequest" title="django.http.HttpRequest"><code class="xref py py-class docutils literal"><span class="pre">HttpRequest</span></code></a> object as its first parameter, which is typically named <code class="docutils literal"><span class="pre">request</span></code>.</p> <p>Note that the name of the view function doesn’t matter; it doesn’t have to be named in a certain way in order for Django to recognize it. We’re calling it <code class="docutils literal"><span class="pre">current_datetime</span></code> here, because that name clearly indicates what it does.</p> </li> <li><p class="first">The view returns an <a class="reference internal" href="../../ref/request-response.html#django.http.HttpResponse" title="django.http.HttpResponse"><code class="xref py py-class docutils literal"><span class="pre">HttpResponse</span></code></a> object that contains the generated response. Each view function is responsible for returning an <a class="reference internal" href="../../ref/request-response.html#django.http.HttpResponse" title="django.http.HttpResponse"><code class="xref py py-class docutils literal"><span class="pre">HttpResponse</span></code></a> object. (There are exceptions, but we’ll get to those later.)</p> </li> </ul> <div class="admonition-django-s-time-zone admonition"> <p class="first admonition-title">Django’s Time Zone</p> <p class="last">Django includes a <a class="reference internal" href="../../ref/settings.html#std:setting-TIME_ZONE"><code class="xref std std-setting docutils literal"><span class="pre">TIME_ZONE</span></code></a> setting that defaults to <code class="docutils literal"><span class="pre">America/Chicago</span></code>. This probably isn’t where you live, so you might want to change it in your settings file.</p> </div> </div> <div class="section" id="s-mapping-urls-to-views"> <span id="mapping-urls-to-views"></span><h2>Mapping URLs to views<a class="headerlink" href="#mapping-urls-to-views" title="Permalink to this headline">¶</a></h2> <p>So, to recap, this view function returns an HTML page that includes the current date and time. To display this view at a particular URL, you’ll need to create a <em>URLconf</em>; see <a class="reference internal" href="urls.html"><span class="doc">URL dispatcher</span></a> for instructions.</p> </div> <div class="section" id="s-returning-errors"> <span id="returning-errors"></span><h2>Returning errors<a class="headerlink" href="#returning-errors" title="Permalink to this headline">¶</a></h2> <p>Returning HTTP error codes in Django is easy. There are subclasses of <a class="reference internal" href="../../ref/request-response.html#django.http.HttpResponse" title="django.http.HttpResponse"><code class="xref py py-class docutils literal"><span class="pre">HttpResponse</span></code></a> for a number of common HTTP status codes other than 200 (which means <em>“OK”</em>). You can find the full list of available subclasses in the <a class="reference internal" href="../../ref/request-response.html#ref-httpresponse-subclasses"><span class="std std-ref">request/response</span></a> documentation. Just return an instance of one of those subclasses instead of a normal <a class="reference internal" href="../../ref/request-response.html#django.http.HttpResponse" title="django.http.HttpResponse"><code class="xref py py-class docutils literal"><span class="pre">HttpResponse</span></code></a> in order to signify an error. For example:</p> <div class="highlight-default"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">django.http</span> <span class="k">import</span> <span class="n">HttpResponse</span><span class="p">,</span> <span class="n">HttpResponseNotFound</span> <span class="k">def</span> <span class="nf">my_view</span><span class="p">(</span><span class="n">request</span><span class="p">):</span> <span class="c1"># ...</span> <span class="k">if</span> <span class="n">foo</span><span class="p">:</span> <span class="k">return</span> <span class="n">HttpResponseNotFound</span><span class="p">(</span><span class="s1">'<h1>Page not found</h1>'</span><span class="p">)</span> <span class="k">else</span><span class="p">:</span> <span class="k">return</span> <span class="n">HttpResponse</span><span class="p">(</span><span class="s1">'<h1>Page was found</h1>'</span><span class="p">)</span> </pre></div> </div> <p>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 in the <a class="reference internal" href="../../ref/request-response.html#django.http.HttpResponse" title="django.http.HttpResponse"><code class="xref py py-class docutils literal"><span class="pre">HttpResponse</span></code></a> documentation, you can also pass the HTTP status code into the constructor for <a class="reference internal" href="../../ref/request-response.html#django.http.HttpResponse" title="django.http.HttpResponse"><code class="xref py py-class docutils literal"><span class="pre">HttpResponse</span></code></a> to create a return class for any status code you like. For example:</p> <div class="highlight-default"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">django.http</span> <span class="k">import</span> <span class="n">HttpResponse</span> <span class="k">def</span> <span class="nf">my_view</span><span class="p">(</span><span class="n">request</span><span class="p">):</span> <span class="c1"># ...</span> <span class="c1"># Return a "created" (201) response code.</span> <span class="k">return</span> <span class="n">HttpResponse</span><span class="p">(</span><span class="n">status</span><span class="o">=</span><span class="mi">201</span><span class="p">)</span> </pre></div> </div> <p>Because 404 errors are by far the most common HTTP error, there’s an easier way to handle those errors.</p> <div class="section" id="s-the-http404-exception"> <span id="the-http404-exception"></span><h3>The Http404 exception<a class="headerlink" href="#the-http404-exception" title="Permalink to this headline">¶</a></h3> <dl class="class"> <dt id="django.http.Http404"> <em class="property">class </em><code class="descclassname">django.http.</code><code class="descname">Http404</code><a class="headerlink" href="#django.http.Http404" title="Permalink to this definition">¶</a></dt> <dd></dd></dl> <p>When you return an error such as <a class="reference internal" href="../../ref/request-response.html#django.http.HttpResponseNotFound" title="django.http.HttpResponseNotFound"><code class="xref py py-class docutils literal"><span class="pre">HttpResponseNotFound</span></code></a>, you’re responsible for defining the HTML of the resulting error page:</p> <div class="highlight-default"><div class="highlight"><pre><span></span><span class="k">return</span> <span class="n">HttpResponseNotFound</span><span class="p">(</span><span class="s1">'<h1>Page not found</h1>'</span><span class="p">)</span> </pre></div> </div> <p>For convenience, and because it’s a good idea to have a consistent 404 error page across your site, Django provides an <code class="docutils literal"><span class="pre">Http404</span></code> exception. If you raise <code class="docutils literal"><span class="pre">Http404</span></code> at any point in a view function, Django will catch it and return the standard error page for your application, along with an HTTP error code 404.</p> <p>Example usage:</p> <div class="highlight-default"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">django.http</span> <span class="k">import</span> <span class="n">Http404</span> <span class="kn">from</span> <span class="nn">django.shortcuts</span> <span class="k">import</span> <span class="n">render_to_response</span> <span class="kn">from</span> <span class="nn">polls.models</span> <span class="k">import</span> <span class="n">Poll</span> <span class="k">def</span> <span class="nf">detail</span><span class="p">(</span><span class="n">request</span><span class="p">,</span> <span class="n">poll_id</span><span class="p">):</span> <span class="k">try</span><span class="p">:</span> <span class="n">p</span> <span class="o">=</span> <span class="n">Poll</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="n">pk</span><span class="o">=</span><span class="n">poll_id</span><span class="p">)</span> <span class="k">except</span> <span class="n">Poll</span><span class="o">.</span><span class="n">DoesNotExist</span><span class="p">:</span> <span class="k">raise</span> <span class="n">Http404</span><span class="p">(</span><span class="s2">"Poll does not exist"</span><span class="p">)</span> <span class="k">return</span> <span class="n">render_to_response</span><span class="p">(</span><span class="s1">'polls/detail.html'</span><span class="p">,</span> <span class="p">{</span><span class="s1">'poll'</span><span class="p">:</span> <span class="n">p</span><span class="p">})</span> </pre></div> </div> <p>In order to use the <code class="docutils literal"><span class="pre">Http404</span></code> exception to its fullest, you should create a template that is displayed when a 404 error is raised. This template should be called <code class="docutils literal"><span class="pre">404.html</span></code> and located in the top level of your template tree.</p> <p>If you provide a message when raising an <code class="docutils literal"><span class="pre">Http404</span></code> exception, it will appear in the standard 404 template displayed when <a class="reference internal" href="../../ref/settings.html#std:setting-DEBUG"><code class="xref std std-setting docutils literal"><span class="pre">DEBUG</span></code></a> is <code class="docutils literal"><span class="pre">True</span></code>. Use these messages for debugging purposes; they generally aren’t suitable for use in a production 404 template.</p> </div> </div> <div class="section" id="s-customizing-error-views"> <span id="s-id1"></span><span id="customizing-error-views"></span><span id="id1"></span><h2>Customizing error views<a class="headerlink" href="#customizing-error-views" title="Permalink to this headline">¶</a></h2> <p>The default error views in Django should suffice for most Web applications, but can easily be overridden if you need any custom behavior. Simply specify the handlers as seen below in your URLconf (setting them anywhere else will have no effect).</p> <p>The <a class="reference internal" href="../../ref/views.html#django.views.defaults.page_not_found" title="django.views.defaults.page_not_found"><code class="xref py py-func docutils literal"><span class="pre">page_not_found()</span></code></a> view is overridden by <a class="reference internal" href="../../ref/urls.html#django.conf.urls.handler404" title="django.conf.urls.handler404"><code class="xref py py-data docutils literal"><span class="pre">handler404</span></code></a>:</p> <div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">handler404</span> <span class="o">=</span> <span class="s1">'mysite.views.my_custom_page_not_found_view'</span> </pre></div> </div> <p>The <a class="reference internal" href="../../ref/views.html#django.views.defaults.server_error" title="django.views.defaults.server_error"><code class="xref py py-func docutils literal"><span class="pre">server_error()</span></code></a> view is overridden by <a class="reference internal" href="../../ref/urls.html#django.conf.urls.handler500" title="django.conf.urls.handler500"><code class="xref py py-data docutils literal"><span class="pre">handler500</span></code></a>:</p> <div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">handler500</span> <span class="o">=</span> <span class="s1">'mysite.views.my_custom_error_view'</span> </pre></div> </div> <p>The <a class="reference internal" href="../../ref/views.html#django.views.defaults.permission_denied" title="django.views.defaults.permission_denied"><code class="xref py py-func docutils literal"><span class="pre">permission_denied()</span></code></a> view is overridden by <a class="reference internal" href="../../ref/urls.html#django.conf.urls.handler403" title="django.conf.urls.handler403"><code class="xref py py-data docutils literal"><span class="pre">handler403</span></code></a>:</p> <div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">handler403</span> <span class="o">=</span> <span class="s1">'mysite.views.my_custom_permission_denied_view'</span> </pre></div> </div> <p>The <a class="reference internal" href="../../ref/views.html#django.views.defaults.bad_request" title="django.views.defaults.bad_request"><code class="xref py py-func docutils literal"><span class="pre">bad_request()</span></code></a> view is overridden by <a class="reference internal" href="../../ref/urls.html#django.conf.urls.handler400" title="django.conf.urls.handler400"><code class="xref py py-data docutils literal"><span class="pre">handler400</span></code></a>:</p> <div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">handler400</span> <span class="o">=</span> <span class="s1">'mysite.views.my_custom_bad_request_view'</span> </pre></div> </div> </div> </div> </div> </div> </div> <div class="yui-b" id="sidebar"> <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> <div class="sphinxsidebarwrapper"> <h3><a href="../../contents.html">Table Of Contents</a></h3> <ul> <li><a class="reference internal" href="#">Writing views</a><ul> <li><a class="reference internal" href="#a-simple-view">A simple view</a></li> <li><a class="reference internal" href="#mapping-urls-to-views">Mapping URLs to views</a></li> <li><a class="reference internal" href="#returning-errors">Returning errors</a><ul> <li><a class="reference internal" href="#the-http404-exception">The Http404 exception</a></li> </ul> </li> <li><a class="reference internal" href="#customizing-error-views">Customizing error views</a></li> </ul> </li> </ul> <h3>Browse</h3> <ul> <li>Prev: <a href="urls.html">URL dispatcher</a></li> <li>Next: <a href="decorators.html">View decorators</a></li> </ul> <h3>You are here:</h3> <ul> <li> <a href="../../index.html">Django 1.8.19 documentation</a> <ul><li><a href="../index.html">Using Django</a> <ul><li><a href="index.html">Handling HTTP requests</a> <ul><li>Writing views</li></ul> </li></ul></li></ul> </li> </ul> <div role="note" aria-label="source link"> <h3>This Page</h3> <ul class="this-page-menu"> <li><a href="../../_sources/topics/http/views.txt" rel="nofollow">Show Source</a></li> </ul> </div> <div id="searchbox" style="display: none" role="search"> <h3>Quick search</h3> <form class="search" action="../../search.html" method="get"> <div><input type="text" name="q" /></div> <div><input type="submit" value="Go" /></div> <input type="hidden" name="check_keywords" value="yes" /> <input type="hidden" name="area" value="default" /> </form> </div> <script type="text/javascript">$('#searchbox').show(0);</script> </div> </div> <h3>Last update:</h3> <p class="topless">Jan 06, 2019</p> </div> </div> <div id="ft"> <div class="nav"> « <a href="urls.html" title="URL dispatcher">previous</a> | <a href="../index.html" title="Using Django" accesskey="U">up</a> | <a href="decorators.html" title="View decorators">next</a> »</div> </div> </div> <div class="clearer"></div> </div> </body> </html>