/docs/ref/middleware.txt
Plain Text | 206 lines | 141 code | 65 blank | 0 comment | 0 complexity | 73becc0de1c71c97e4b0321df92d3cd4 MD5 | raw file
Possible License(s): BSD-3-Clause
1========== 2Middleware 3========== 4 5.. module:: django.middleware 6 :synopsis: Django's built-in middleware classes. 7 8This document explains all middleware components that come with Django. For 9information on how to use them and how to write your own middleware, see 10the :doc:`middleware usage guide </topics/http/middleware>`. 11 12Available middleware 13==================== 14 15Cache middleware 16---------------- 17 18.. module:: django.middleware.cache 19 :synopsis: Middleware for the site-wide cache. 20 21.. class:: UpdateCacheMiddleware 22 23.. class:: FetchFromCacheMiddleware 24 25Enable the site-wide cache. If these are enabled, each Django-powered page will 26be cached for as long as the :setting:`CACHE_MIDDLEWARE_SECONDS` setting 27defines. See the :doc:`cache documentation </topics/cache>`. 28 29"Common" middleware 30------------------- 31 32.. module:: django.middleware.common 33 :synopsis: Middleware adding "common" conveniences for perfectionists. 34 35.. class:: CommonMiddleware 36 37Adds a few conveniences for perfectionists: 38 39 * Forbids access to user agents in the :setting:`DISALLOWED_USER_AGENTS` 40 setting, which should be a list of strings. 41 42 * Performs URL rewriting based on the :setting:`APPEND_SLASH` and 43 :setting:`PREPEND_WWW` settings. 44 45 If :setting:`APPEND_SLASH` is ``True`` and the initial URL doesn't end 46 with a slash, and it is not found in the URLconf, then a new URL is 47 formed by appending a slash at the end. If this new URL is found in the 48 URLconf, then Django redirects the request to this new URL. Otherwise, 49 the initial URL is processed as usual. 50 51 For example, ``foo.com/bar`` will be redirected to ``foo.com/bar/`` if 52 you don't have a valid URL pattern for ``foo.com/bar`` but *do* have a 53 valid pattern for ``foo.com/bar/``. 54 55 If :setting:`PREPEND_WWW` is ``True``, URLs that lack a leading "www." 56 will be redirected to the same URL with a leading "www." 57 58 Both of these options are meant to normalize URLs. The philosophy is that 59 each URL should exist in one, and only one, place. Technically a URL 60 ``foo.com/bar`` is distinct from ``foo.com/bar/`` -- a search-engine 61 indexer would treat them as separate URLs -- so it's best practice to 62 normalize URLs. 63 64 * Sends broken link notification emails to :setting:`MANAGERS` if 65 :setting:`SEND_BROKEN_LINK_EMAILS` is set to ``True``. 66 67 * Handles ETags based on the :setting:`USE_ETAGS` setting. If 68 :setting:`USE_ETAGS` is set to ``True``, Django will calculate an ETag 69 for each request by MD5-hashing the page content, and it'll take care of 70 sending ``Not Modified`` responses, if appropriate. 71 72View metadata middleware 73------------------------ 74 75.. module:: django.middleware.doc 76 :synopsis: Middleware to help your app self-document. 77 78.. class:: XViewMiddleware 79 80Sends custom ``X-View`` HTTP headers to HEAD requests that come from IP 81addresses defined in the :setting:`INTERNAL_IPS` setting. This is used by 82Django's :doc:`automatic documentation system </ref/contrib/admin/admindocs>`. 83 84GZIP middleware 85--------------- 86 87.. module:: django.middleware.gzip 88 :synopsis: Middleware to serve gziped content for performance. 89 90.. class:: GZipMiddleware 91 92Compresses content for browsers that understand gzip compression (all modern 93browsers). 94 95It is suggested to place this first in the middleware list, so that the 96compression of the response content is the last thing that happens. Will not 97compress content bodies less than 200 bytes long, when the response code is 98something other than 200, JavaScript files (for IE compatibility), or 99responses that have the ``Content-Encoding`` header already specified. 100 101GZip compression can be applied to individual views using the 102:func:`~django.views.decorators.http.gzip_page()` decorator. 103 104Conditional GET middleware 105-------------------------- 106 107.. module:: django.middleware.http 108 :synopsis: Middleware handling advanced HTTP features. 109 110.. class:: ConditionalGetMiddleware 111 112Handles conditional GET operations. If the response has a ``ETag`` or 113``Last-Modified`` header, and the request has ``If-None-Match`` or 114``If-Modified-Since``, the response is replaced by an 115:class:`~django.http.HttpNotModified`. 116 117Also sets the ``Date`` and ``Content-Length`` response-headers. 118 119Reverse proxy middleware 120------------------------ 121 122.. class:: SetRemoteAddrFromForwardedFor 123 124This middleware was removed in Django 1.1. See :ref:`the release notes 125<removed-setremoteaddrfromforwardedfor-middleware>` for details. 126 127Locale middleware 128----------------- 129 130.. module:: django.middleware.locale 131 :synopsis: Middleware to enable language selection based on the request. 132 133.. class:: LocaleMiddleware 134 135Enables language selection based on data from the request. It customizes 136content for each user. See the :doc:`internationalization documentation 137</topics/i18n/index>`. 138 139Message middleware 140------------------ 141 142.. module:: django.contrib.messages.middleware 143 :synopsis: Message middleware. 144 145.. class:: MessageMiddleware 146 147.. versionadded:: 1.2 148 ``MessageMiddleware`` was added. 149 150Enables cookie- and session-based message support. See the 151:doc:`messages documentation </ref/contrib/messages>`. 152 153Session middleware 154------------------ 155 156.. module:: django.contrib.sessions.middleware 157 :synopsis: Session middleware. 158 159.. class:: SessionMiddleware 160 161Enables session support. See the :doc:`session documentation 162</topics/http/sessions>`. 163 164Authentication middleware 165------------------------- 166 167.. module:: django.contrib.auth.middleware 168 :synopsis: Authentication middleware. 169 170.. class:: AuthenticationMiddleware 171 172Adds the ``user`` attribute, representing the currently-logged-in user, to 173every incoming ``HttpRequest`` object. See :doc:`Authentication in Web requests 174</topics/auth>`. 175 176CSRF protection middleware 177-------------------------- 178 179.. module:: django.middleware.csrf 180 :synopsis: Middleware adding protection against Cross Site Request 181 Forgeries. 182 183.. class:: CsrfMiddleware 184 185Adds protection against Cross Site Request Forgeries by adding hidden form 186fields to POST forms and checking requests for the correct value. See the 187:doc:`Cross Site Request Forgery protection documentation </ref/contrib/csrf>`. 188 189Transaction middleware 190---------------------- 191 192.. module:: django.middleware.transaction 193 :synopsis: Middleware binding a database transaction to each Web request. 194 195.. class:: TransactionMiddleware 196 197Binds commit and rollback to the request/response phase. If a view function 198runs successfully, a commit is done. If it fails with an exception, a rollback 199is done. 200 201The order of this middleware in the stack is important: middleware modules 202running outside of it run with commit-on-save - the default Django behavior. 203Middleware modules running inside it (coming later in the stack) will be under 204the same transaction control as the view functions. 205 206See the :doc:`transaction management documentation </topics/db/transactions>`.