<!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"> <head> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <title>Middleware — Django 1.5.9 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.5.9', 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="top" title="Django 1.5.9 documentation" href="../index.html" /> <link rel="up" title="API Reference" href="index.html" /> <link rel="next" title="Models" href="models/index.html" /> <link rel="prev" title="Form and field validation" href="forms/validation.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 = "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> <div class="document"> <div id="custom-doc" class="yui-t6"> <div id="hd"> <h1><a href="../index.html">Django 1.5.9 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="forms/validation.html" title="Form and field validation">previous</a> | <a href="index.html" title="API Reference" accesskey="U">up</a> | <a href="models/index.html" title="Models">next</a> »</div> </div> <div id="bd"> <div id="yui-main"> <div class="yui-b"> <div class="yui-g" id="ref-middleware"> <div class="section" id="s-module-django.middleware"> <span id="s-middleware"></span><span id="module-django.middleware"></span><span id="middleware"></span><h1>Middleware<a class="headerlink" href="#module-django.middleware" title="Permalink to this headline">¶</a></h1> <p>This document explains all middleware components that come with Django. For information on how to use them and how to write your own middleware, see the <a class="reference internal" href="../topics/http/middleware.html"><em>middleware usage guide</em></a>.</p> <div class="section" id="s-available-middleware"> <span id="available-middleware"></span><h2>Available middleware<a class="headerlink" href="#available-middleware" title="Permalink to this headline">¶</a></h2> <div class="section" id="s-module-django.middleware.cache"> <span id="s-cache-middleware"></span><span id="module-django.middleware.cache"></span><span id="cache-middleware"></span><h3>Cache middleware<a class="headerlink" href="#module-django.middleware.cache" title="Permalink to this headline">¶</a></h3> <dl class="class"> <dt id="django.middleware.cache.UpdateCacheMiddleware"> <em class="property">class </em><tt class="descname">UpdateCacheMiddleware</tt><a class="headerlink" href="#django.middleware.cache.UpdateCacheMiddleware" title="Permalink to this definition">¶</a></dt> <dd></dd></dl> <dl class="class"> <dt id="django.middleware.cache.FetchFromCacheMiddleware"> <em class="property">class </em><tt class="descname">FetchFromCacheMiddleware</tt><a class="headerlink" href="#django.middleware.cache.FetchFromCacheMiddleware" title="Permalink to this definition">¶</a></dt> <dd></dd></dl> <p>Enable the site-wide cache. If these are enabled, each Django-powered page will be cached for as long as the <a class="reference internal" href="settings.html#std:setting-CACHE_MIDDLEWARE_SECONDS"><tt class="xref std std-setting docutils literal"><span class="pre">CACHE_MIDDLEWARE_SECONDS</span></tt></a> setting defines. See the <a class="reference internal" href="../topics/cache.html"><em>cache documentation</em></a>.</p> </div> <div class="section" id="s-module-django.middleware.common"> <span id="s-common-middleware"></span><span id="module-django.middleware.common"></span><span id="common-middleware"></span><h3>“Common” middleware<a class="headerlink" href="#module-django.middleware.common" title="Permalink to this headline">¶</a></h3> <dl class="class"> <dt id="django.middleware.common.CommonMiddleware"> <em class="property">class </em><tt class="descname">CommonMiddleware</tt><a class="headerlink" href="#django.middleware.common.CommonMiddleware" title="Permalink to this definition">¶</a></dt> <dd></dd></dl> <p>Adds a few conveniences for perfectionists:</p> <ul> <li><p class="first">Forbids access to user agents in the <a class="reference internal" href="settings.html#std:setting-DISALLOWED_USER_AGENTS"><tt class="xref std std-setting docutils literal"><span class="pre">DISALLOWED_USER_AGENTS</span></tt></a> setting, which should be a list of compiled regular expression objects.</p> </li> <li><p class="first">Performs URL rewriting based on the <a class="reference internal" href="settings.html#std:setting-APPEND_SLASH"><tt class="xref std std-setting docutils literal"><span class="pre">APPEND_SLASH</span></tt></a> and <a class="reference internal" href="settings.html#std:setting-PREPEND_WWW"><tt class="xref std std-setting docutils literal"><span class="pre">PREPEND_WWW</span></tt></a> settings.</p> <p>If <a class="reference internal" href="settings.html#std:setting-APPEND_SLASH"><tt class="xref std std-setting docutils literal"><span class="pre">APPEND_SLASH</span></tt></a> is <tt class="docutils literal"><span class="pre">True</span></tt> and the initial URL doesn’t end with a slash, and it is not found in the URLconf, then a new URL is formed by appending a slash at the end. If this new URL is found in the URLconf, then Django redirects the request to this new URL. Otherwise, the initial URL is processed as usual.</p> <p>For example, <tt class="docutils literal"><span class="pre">foo.com/bar</span></tt> will be redirected to <tt class="docutils literal"><span class="pre">foo.com/bar/</span></tt> if you don’t have a valid URL pattern for <tt class="docutils literal"><span class="pre">foo.com/bar</span></tt> but <em>do</em> have a valid pattern for <tt class="docutils literal"><span class="pre">foo.com/bar/</span></tt>.</p> <p>If <a class="reference internal" href="settings.html#std:setting-PREPEND_WWW"><tt class="xref std std-setting docutils literal"><span class="pre">PREPEND_WWW</span></tt></a> is <tt class="docutils literal"><span class="pre">True</span></tt>, URLs that lack a leading “www.” will be redirected to the same URL with a leading “www.”</p> <p>Both of these options are meant to normalize URLs. The philosophy is that each URL should exist in one, and only one, place. Technically a URL <tt class="docutils literal"><span class="pre">foo.com/bar</span></tt> is distinct from <tt class="docutils literal"><span class="pre">foo.com/bar/</span></tt> – a search-engine indexer would treat them as separate URLs – so it’s best practice to normalize URLs.</p> </li> <li><p class="first">Sends broken link notification emails to <a class="reference internal" href="settings.html#std:setting-MANAGERS"><tt class="xref std std-setting docutils literal"><span class="pre">MANAGERS</span></tt></a> if <a class="reference internal" href="settings.html#std:setting-SEND_BROKEN_LINK_EMAILS"><tt class="xref std std-setting docutils literal"><span class="pre">SEND_BROKEN_LINK_EMAILS</span></tt></a> is set to <tt class="docutils literal"><span class="pre">True</span></tt>.</p> </li> <li><p class="first">Handles ETags based on the <a class="reference internal" href="settings.html#std:setting-USE_ETAGS"><tt class="xref std std-setting docutils literal"><span class="pre">USE_ETAGS</span></tt></a> setting. If <a class="reference internal" href="settings.html#std:setting-USE_ETAGS"><tt class="xref std std-setting docutils literal"><span class="pre">USE_ETAGS</span></tt></a> is set to <tt class="docutils literal"><span class="pre">True</span></tt>, Django will calculate an ETag for each request by MD5-hashing the page content, and it’ll take care of sending <tt class="docutils literal"><span class="pre">Not</span> <span class="pre">Modified</span></tt> responses, if appropriate.</p> </li> </ul> </div> <div class="section" id="s-module-django.middleware.doc"> <span id="s-view-metadata-middleware"></span><span id="module-django.middleware.doc"></span><span id="view-metadata-middleware"></span><h3>View metadata middleware<a class="headerlink" href="#module-django.middleware.doc" title="Permalink to this headline">¶</a></h3> <dl class="class"> <dt id="django.middleware.doc.XViewMiddleware"> <em class="property">class </em><tt class="descname">XViewMiddleware</tt><a class="headerlink" href="#django.middleware.doc.XViewMiddleware" title="Permalink to this definition">¶</a></dt> <dd></dd></dl> <p>Sends custom <tt class="docutils literal"><span class="pre">X-View</span></tt> HTTP headers to HEAD requests that come from IP addresses defined in the <a class="reference internal" href="settings.html#std:setting-INTERNAL_IPS"><tt class="xref std std-setting docutils literal"><span class="pre">INTERNAL_IPS</span></tt></a> setting. This is used by Django’s <a class="reference internal" href="contrib/admin/admindocs.html"><em>automatic documentation system</em></a>. Depends on <a class="reference internal" href="#django.contrib.auth.middleware.AuthenticationMiddleware" title="django.contrib.auth.middleware.AuthenticationMiddleware"><tt class="xref py py-class docutils literal"><span class="pre">AuthenticationMiddleware</span></tt></a>.</p> </div> <div class="section" id="s-module-django.middleware.gzip"> <span id="s-gzip-middleware"></span><span id="module-django.middleware.gzip"></span><span id="gzip-middleware"></span><h3>GZip middleware<a class="headerlink" href="#module-django.middleware.gzip" title="Permalink to this headline">¶</a></h3> <dl class="class"> <dt id="django.middleware.gzip.GZipMiddleware"> <em class="property">class </em><tt class="descname">GZipMiddleware</tt><a class="headerlink" href="#django.middleware.gzip.GZipMiddleware" title="Permalink to this definition">¶</a></dt> <dd></dd></dl> <div class="admonition warning"> <p class="first admonition-title">Warning</p> <p class="last">Security researchers recently revealed that when compression techniques (including <tt class="docutils literal"><span class="pre">GZipMiddleware</span></tt>) are used on a website, the site becomes exposed to a number of possible attacks. These approaches can be used to compromise, amongst other things, Django’s CSRF protection. Before using <tt class="docutils literal"><span class="pre">GZipMiddleware</span></tt> on your site, you should consider very carefully whether you are subject to these attacks. If you’re in <em>any</em> doubt about whether you’re affected, you should avoid using <tt class="docutils literal"><span class="pre">GZipMiddleware</span></tt>. For more details, see the <a class="reference external" href="http://breachattack.com/resources/BREACH%20-%20SSL,%20gone%20in%2030%20seconds.pdf">the BREACH paper (PDF)</a> and <a class="reference external" href="http://breachattack.com">breachattack.com</a>.</p> </div> <p>Compresses content for browsers that understand GZip compression (all modern browsers).</p> <p>This middleware should be placed before any other middleware that need to read or write the response body so that compression happens afterward.</p> <p>It will NOT compress content if any of the following are true:</p> <ul class="simple"> <li>The content body is less than 200 bytes long.</li> <li>The response has already set the <tt class="docutils literal"><span class="pre">Content-Encoding</span></tt> header.</li> <li>The request (the browser) hasn’t sent an <tt class="docutils literal"><span class="pre">Accept-Encoding</span></tt> header containing <tt class="docutils literal"><span class="pre">gzip</span></tt>.</li> <li>The request is from Internet Explorer and the <tt class="docutils literal"><span class="pre">Content-Type</span></tt> header contains <tt class="docutils literal"><span class="pre">javascript</span></tt> or starts with anything other than <tt class="docutils literal"><span class="pre">text/</span></tt>. We do this to avoid a bug in early versions of IE that caused decompression not to be performed on certain content types.</li> </ul> <p>You can apply GZip compression to individual views using the <a class="reference internal" href="../topics/http/decorators.html#django.views.decorators.gzip.gzip_page" title="django.views.decorators.gzip.gzip_page"><tt class="xref py py-func docutils literal"><span class="pre">gzip_page()</span></tt></a> decorator.</p> </div> <div class="section" id="s-module-django.middleware.http"> <span id="s-conditional-get-middleware"></span><span id="module-django.middleware.http"></span><span id="conditional-get-middleware"></span><h3>Conditional GET middleware<a class="headerlink" href="#module-django.middleware.http" title="Permalink to this headline">¶</a></h3> <dl class="class"> <dt id="django.middleware.http.ConditionalGetMiddleware"> <em class="property">class </em><tt class="descname">ConditionalGetMiddleware</tt><a class="headerlink" href="#django.middleware.http.ConditionalGetMiddleware" title="Permalink to this definition">¶</a></dt> <dd></dd></dl> <p>Handles conditional GET operations. If the response has a <tt class="docutils literal"><span class="pre">ETag</span></tt> or <tt class="docutils literal"><span class="pre">Last-Modified</span></tt> header, and the request has <tt class="docutils literal"><span class="pre">If-None-Match</span></tt> or <tt class="docutils literal"><span class="pre">If-Modified-Since</span></tt>, the response is replaced by an <a class="reference internal" href="request-response.html#django.http.HttpResponseNotModified" title="django.http.HttpResponseNotModified"><tt class="xref py py-class docutils literal"><span class="pre">HttpResponseNotModified</span></tt></a>.</p> <p>Also sets the <tt class="docutils literal"><span class="pre">Date</span></tt> and <tt class="docutils literal"><span class="pre">Content-Length</span></tt> response-headers.</p> </div> <div class="section" id="s-reverse-proxy-middleware"> <span id="reverse-proxy-middleware"></span><h3>Reverse proxy middleware<a class="headerlink" href="#reverse-proxy-middleware" title="Permalink to this headline">¶</a></h3> <dl class="class"> <dt id="django.middleware.http.SetRemoteAddrFromForwardedFor"> <em class="property">class </em><tt class="descname">SetRemoteAddrFromForwardedFor</tt><a class="headerlink" href="#django.middleware.http.SetRemoteAddrFromForwardedFor" title="Permalink to this definition">¶</a></dt> <dd></dd></dl> <p>This middleware was removed in Django 1.1. See <a class="reference internal" href="../releases/1.1.html#removed-setremoteaddrfromforwardedfor-middleware"><em>the release notes</em></a> for details.</p> </div> <div class="section" id="s-module-django.middleware.locale"> <span id="s-locale-middleware"></span><span id="module-django.middleware.locale"></span><span id="locale-middleware"></span><h3>Locale middleware<a class="headerlink" href="#module-django.middleware.locale" title="Permalink to this headline">¶</a></h3> <dl class="class"> <dt id="django.middleware.locale.LocaleMiddleware"> <em class="property">class </em><tt class="descname">LocaleMiddleware</tt><a class="headerlink" href="#django.middleware.locale.LocaleMiddleware" title="Permalink to this definition">¶</a></dt> <dd></dd></dl> <p>Enables language selection based on data from the request. It customizes content for each user. See the <a class="reference internal" href="../topics/i18n/translation.html"><em>internationalization documentation</em></a>.</p> </div> <div class="section" id="s-module-django.contrib.messages.middleware"> <span id="s-message-middleware"></span><span id="module-django.contrib.messages.middleware"></span><span id="message-middleware"></span><h3>Message middleware<a class="headerlink" href="#module-django.contrib.messages.middleware" title="Permalink to this headline">¶</a></h3> <dl class="class"> <dt id="django.contrib.messages.middleware.MessageMiddleware"> <em class="property">class </em><tt class="descname">MessageMiddleware</tt><a class="headerlink" href="#django.contrib.messages.middleware.MessageMiddleware" title="Permalink to this definition">¶</a></dt> <dd></dd></dl> <p>Enables cookie- and session-based message support. See the <a class="reference internal" href="contrib/messages.html"><em>messages documentation</em></a>.</p> </div> <div class="section" id="s-module-django.contrib.sessions.middleware"> <span id="s-session-middleware"></span><span id="module-django.contrib.sessions.middleware"></span><span id="session-middleware"></span><h3>Session middleware<a class="headerlink" href="#module-django.contrib.sessions.middleware" title="Permalink to this headline">¶</a></h3> <dl class="class"> <dt id="django.contrib.sessions.middleware.SessionMiddleware"> <em class="property">class </em><tt class="descname">SessionMiddleware</tt><a class="headerlink" href="#django.contrib.sessions.middleware.SessionMiddleware" title="Permalink to this definition">¶</a></dt> <dd></dd></dl> <p>Enables session support. See the <a class="reference internal" href="../topics/http/sessions.html"><em>session documentation</em></a>.</p> </div> <div class="section" id="s-module-django.contrib.auth.middleware"> <span id="s-authentication-middleware"></span><span id="module-django.contrib.auth.middleware"></span><span id="authentication-middleware"></span><h3>Authentication middleware<a class="headerlink" href="#module-django.contrib.auth.middleware" title="Permalink to this headline">¶</a></h3> <dl class="class"> <dt id="django.contrib.auth.middleware.AuthenticationMiddleware"> <em class="property">class </em><tt class="descname">AuthenticationMiddleware</tt><a class="headerlink" href="#django.contrib.auth.middleware.AuthenticationMiddleware" title="Permalink to this definition">¶</a></dt> <dd></dd></dl> <p>Adds the <tt class="docutils literal"><span class="pre">user</span></tt> attribute, representing the currently-logged-in user, to every incoming <tt class="docutils literal"><span class="pre">HttpRequest</span></tt> object. See <a class="reference internal" href="../topics/auth/default.html#auth-web-requests"><em>Authentication in Web requests</em></a>.</p> </div> <div class="section" id="s-module-django.middleware.csrf"> <span id="s-csrf-protection-middleware"></span><span id="module-django.middleware.csrf"></span><span id="csrf-protection-middleware"></span><h3>CSRF protection middleware<a class="headerlink" href="#module-django.middleware.csrf" title="Permalink to this headline">¶</a></h3> <dl class="class"> <dt id="django.middleware.csrf.CsrfViewMiddleware"> <em class="property">class </em><tt class="descname">CsrfViewMiddleware</tt><a class="headerlink" href="#django.middleware.csrf.CsrfViewMiddleware" title="Permalink to this definition">¶</a></dt> <dd></dd></dl> <p>Adds protection against Cross Site Request Forgeries by adding hidden form fields to POST forms and checking requests for the correct value. See the <a class="reference internal" href="contrib/csrf.html"><em>Cross Site Request Forgery protection documentation</em></a>.</p> </div> <div class="section" id="s-module-django.middleware.transaction"> <span id="s-transaction-middleware"></span><span id="module-django.middleware.transaction"></span><span id="transaction-middleware"></span><h3>Transaction middleware<a class="headerlink" href="#module-django.middleware.transaction" title="Permalink to this headline">¶</a></h3> <dl class="class"> <dt id="django.middleware.transaction.TransactionMiddleware"> <em class="property">class </em><tt class="descname">TransactionMiddleware</tt><a class="headerlink" href="#django.middleware.transaction.TransactionMiddleware" title="Permalink to this definition">¶</a></dt> <dd></dd></dl> <p>Binds commit and rollback of the default database to the request/response phase. If a view function runs successfully, a commit is done. If it fails with an exception, a rollback is done.</p> <p>The order of this middleware in the stack is important: middleware modules running outside of it run with commit-on-save - the default Django behavior. Middleware modules running inside it (coming later in the stack) will be under the same transaction control as the view functions.</p> <p>See the <a class="reference internal" href="../topics/db/transactions.html"><em>transaction management documentation</em></a>.</p> </div> <div class="section" id="s-module-django.middleware.clickjacking"> <span id="s-x-frame-options-middleware"></span><span id="module-django.middleware.clickjacking"></span><span id="x-frame-options-middleware"></span><h3>X-Frame-Options middleware<a class="headerlink" href="#module-django.middleware.clickjacking" title="Permalink to this headline">¶</a></h3> <dl class="class"> <dt id="django.middleware.clickjacking.XFrameOptionsMiddleware"> <em class="property">class </em><tt class="descname">XFrameOptionsMiddleware</tt><a class="headerlink" href="#django.middleware.clickjacking.XFrameOptionsMiddleware" title="Permalink to this definition">¶</a></dt> <dd></dd></dl> <div class="versionadded"> <span class="title">New in Django 1.4:</span> <tt class="docutils literal"><span class="pre">XFrameOptionsMiddleware</span></tt> was added.</div> <p>Simple <a class="reference internal" href="clickjacking.html"><em>clickjacking protection via the X-Frame-Options header</em></a>.</p> </div> </div> </div> </div> </div> </div> <div class="yui-b" id="sidebar"> <div class="sphinxsidebar"> <div class="sphinxsidebarwrapper"> <h3><a href="../contents.html">Table Of Contents</a></h3> <ul> <li><a class="reference internal" href="#">Middleware</a><ul> <li><a class="reference internal" href="#available-middleware">Available middleware</a><ul> <li><a class="reference internal" href="#module-django.middleware.cache">Cache middleware</a></li> <li><a class="reference internal" href="#module-django.middleware.common">“Common” middleware</a></li> <li><a class="reference internal" href="#module-django.middleware.doc">View metadata middleware</a></li> <li><a class="reference internal" href="#module-django.middleware.gzip">GZip middleware</a></li> <li><a class="reference internal" href="#module-django.middleware.http">Conditional GET middleware</a></li> <li><a class="reference internal" href="#reverse-proxy-middleware">Reverse proxy middleware</a></li> <li><a class="reference internal" href="#module-django.middleware.locale">Locale middleware</a></li> <li><a class="reference internal" href="#module-django.contrib.messages.middleware">Message middleware</a></li> <li><a class="reference internal" href="#module-django.contrib.sessions.middleware">Session middleware</a></li> <li><a class="reference internal" href="#module-django.contrib.auth.middleware">Authentication middleware</a></li> <li><a class="reference internal" href="#module-django.middleware.csrf">CSRF protection middleware</a></li> <li><a class="reference internal" href="#module-django.middleware.transaction">Transaction middleware</a></li> <li><a class="reference internal" href="#module-django.middleware.clickjacking">X-Frame-Options middleware</a></li> </ul> </li> </ul> </li> </ul> <h3>Browse</h3> <ul> <li>Prev: <a href="forms/validation.html">Form and field validation</a></li> <li>Next: <a href="models/index.html">Models</a></li> </ul> <h3>You are here:</h3> <ul> <li> <a href="../index.html">Django 1.5.9 documentation</a> <ul><li><a href="index.html">API Reference</a> <ul><li>Middleware</li></ul> </li></ul> </li> </ul> <h3>This Page</h3> <ul class="this-page-menu"> <li><a href="../_sources/ref/middleware.txt" rel="nofollow">Show Source</a></li> </ul> <div id="searchbox" style="display: none"> <h3>Quick search</h3> <form class="search" action="../search.html" method="get"> <input type="text" name="q" /> <input type="submit" value="Go" /> <input type="hidden" name="check_keywords" value="yes" /> <input type="hidden" name="area" value="default" /> </form> <p class="searchtip" style="font-size: 90%"> Enter search terms or a module, class or function name. </p> </div> <script type="text/javascript">$('#searchbox').show(0);</script> </div> </div> <h3>Last update:</h3> <p class="topless">Jan 15, 2015</p> </div> </div> <div id="ft"> <div class="nav"> « <a href="forms/validation.html" title="Form and field validation">previous</a> | <a href="index.html" title="API Reference" accesskey="U">up</a> | <a href="models/index.html" title="Models">next</a> »</div> </div> </div> <div class="clearer"></div> </div> </body> </html>