<!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.6.7 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.6.7',
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.6.7 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.6.7 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="reference internal" href="../_modules/django/middleware/common.html#CommonMiddleware"><span class="viewcode-link">[source]</span></a><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">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>
<dl class="class">
<dt id="django.middleware.common.BrokenLinkEmailsMiddleware">
<em class="property">class </em><tt class="descname">BrokenLinkEmailsMiddleware</tt><a class="reference internal" href="../_modules/django/middleware/common.html#BrokenLinkEmailsMiddleware"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#django.middleware.common.BrokenLinkEmailsMiddleware" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<ul class="simple">
<li>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> (see
<a class="reference internal" href="../howto/error-reporting.html"><em>Error reporting</em></a>).</li>
</ul>
</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="reference internal" href="../_modules/django/middleware/http.html#ConditionalGetMiddleware"><span class="viewcode-link">[source]</span></a><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-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="reference internal" href="../_modules/django/contrib/messages/middleware.html#MessageMiddleware"><span class="viewcode-link">[source]</span></a><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>
<dl class="class">
<dt id="django.contrib.auth.middleware.RemoteUserMiddleware">
<em class="property">class </em><tt class="descname">RemoteUserMiddleware</tt><a class="headerlink" href="#django.contrib.auth.middleware.RemoteUserMiddleware" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p>Middleware for utilizing Web server provided authentication. See
<a class="reference internal" href="../howto/auth-remote-user.html"><em>Authentication using REMOTE_USER</em></a> for usage details.</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="reference internal" href="../_modules/django/middleware/transaction.html#TransactionMiddleware"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#django.middleware.transaction.TransactionMiddleware" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<div class="versionchanged">
<span class="title">Changed in Django 1.6:</span> <tt class="docutils literal"><span class="pre">TransactionMiddleware</span></tt> is deprecated. The documentation of transactions
contains <a class="reference internal" href="../topics/db/transactions.html#transactions-upgrading-from-1-5"><em>upgrade instructions</em></a>.</div>
<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="reference internal" href="../_modules/django/middleware/clickjacking.html#XFrameOptionsMiddleware"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#django.middleware.clickjacking.XFrameOptionsMiddleware" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<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.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="#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.6.7 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">Sep 26, 2014</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>
