| ========== |
| Middleware |
| ========== |
| |
| .. module:: django.middleware |
| :synopsis: Django's built-in middleware classes. |
| |
| This document explains all middleware components that come with Django. For |
| information on how how to use them and how to write your own middleware, see |
| the :doc:`middleware usage guide </topics/http/middleware>`. |
| |
| Available middleware |
| ==================== |
| |
| Cache middleware |
| ---------------- |
| |
| .. module:: django.middleware.cache |
| :synopsis: Middleware for the site-wide cache. |
| |
| .. class:: UpdateCacheMiddleware |
| |
| .. class:: FetchFromCacheMiddleware |
| |
| Enable the site-wide cache. If these are enabled, each Django-powered page will |
| be cached for as long as the :setting:`CACHE_MIDDLEWARE_SECONDS` setting |
| defines. See the :doc:`cache documentation </topics/cache>`. |
| |
| "Common" middleware |
| ------------------- |
| |
| .. module:: django.middleware.common |
| :synopsis: Middleware adding "common" conveniences for perfectionists. |
| |
| .. class:: CommonMiddleware |
| |
| Adds a few conveniences for perfectionists: |
| |
| * Forbids access to user agents in the :setting:`DISALLOWED_USER_AGENTS` |
| setting, which should be a list of strings. |
| |
| * Performs URL rewriting based on the :setting:`APPEND_SLASH` and |
| :setting:`PREPEND_WWW` settings. |
| |
| If :setting:`APPEND_SLASH` is ``True`` 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. |
| |
| For example, ``foo.com/bar`` will be redirected to ``foo.com/bar/`` if |
| you don't have a valid URL pattern for ``foo.com/bar`` but *do* have a |
| valid pattern for ``foo.com/bar/``. |
| |
| If :setting:`PREPEND_WWW` is ``True``, URLs that lack a leading "www." |
| will be redirected to the same URL with a leading "www." |
| |
| 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 |
| ``foo.com/bar`` is distinct from ``foo.com/bar/`` -- a search-engine |
| indexer would treat them as separate URLs -- so it's best practice to |
| normalize URLs. |
| |
| * Sends broken link notification emails to :setting:`MANAGERS` if |
| :setting:`SEND_BROKEN_LINK_EMAILS` is set to ``True``. |
| |
| * Handles ETags based on the :setting:`USE_ETAGS` setting. If |
| :setting:`USE_ETAGS` is set to ``True``, Django will calculate an ETag |
| for each request by MD5-hashing the page content, and it'll take care of |
| sending ``Not Modified`` responses, if appropriate. |
| |
| View metadata middleware |
| ------------------------ |
| |
| .. module:: django.middleware.doc |
| :synopsis: Middleware to help your app self-document. |
| |
| .. class:: XViewMiddleware |
| |
| Sends custom ``X-View`` HTTP headers to HEAD requests that come from IP |
| addresses defined in the :setting:`INTERNAL_IPS` setting. This is used by |
| Django's :doc:`automatic documentation system </ref/contrib/admin/admindocs>`. |
| |
| GZIP middleware |
| --------------- |
| |
| .. module:: django.middleware.gzip |
| :synopsis: Middleware to serve gziped content for performance. |
| |
| .. class:: GZipMiddleware |
| |
| Compresses content for browsers that understand gzip compression (all modern |
| browsers). |
| |
| It is suggested to place this first in the middleware list, so that the |
| compression of the response content is the last thing that happens. Will not |
| compress content bodies less than 200 bytes long, when the response code is |
| something other than 200, JavaScript files (for IE compatibility), or |
| responses that have the ``Content-Encoding`` header already specified. |
| |
| GZip compression can be applied to individual views using the |
| :func:`~django.views.decorators.http.gzip_page()` decorator. |
| |
| Conditional GET middleware |
| -------------------------- |
| |
| .. module:: django.middleware.http |
| :synopsis: Middleware handling advanced HTTP features. |
| |
| .. class:: ConditionalGetMiddleware |
| |
| Handles conditional GET operations. If the response has a ``ETag`` or |
| ``Last-Modified`` header, and the request has ``If-None-Match`` or |
| ``If-Modified-Since``, the response is replaced by an |
| :class:`~django.http.HttpNotModified`. |
| |
| Also sets the ``Date`` and ``Content-Length`` response-headers. |
| |
| Reverse proxy middleware |
| ------------------------ |
| |
| .. class:: SetRemoteAddrFromForwardedFor |
| |
| .. versionchanged:: 1.1 |
| |
| This middleware was removed in Django 1.1. See :ref:`the release notes |
| <removed-setremoteaddrfromforwardedfor-middleware>` for details. |
| |
| Locale middleware |
| ----------------- |
| |
| .. module:: django.middleware.locale |
| :synopsis: Middleware to enable language selection based on the request. |
| |
| .. class:: LocaleMiddleware |
| |
| Enables language selection based on data from the request. It customizes |
| content for each user. See the :doc:`internationalization documentation |
| </topics/i18n/index>`. |
| |
| Message middleware |
| ------------------ |
| |
| .. module:: django.contrib.messages.middleware |
| :synopsis: Message middleware. |
| |
| .. class:: MessageMiddleware |
| |
| .. versionadded:: 1.2 |
| ``MessageMiddleware`` was added. |
| |
| Enables cookie- and session-based message support. See the |
| :doc:`messages documentation </ref/contrib/messages>`. |
| |
| Session middleware |
| ------------------ |
| |
| .. module:: django.contrib.sessions.middleware |
| :synopsis: Session middleware. |
| |
| .. class:: SessionMiddleware |
| |
| Enables session support. See the :doc:`session documentation |
| </topics/http/sessions>`. |
| |
| Authentication middleware |
| ------------------------- |
| |
| .. module:: django.contrib.auth.middleware |
| :synopsis: Authentication middleware. |
| |
| .. class:: AuthenticationMiddleware |
| |
| Adds the ``user`` attribute, representing the currently-logged-in user, to |
| every incoming ``HttpRequest`` object. See :doc:`Authentication in Web requests |
| </topics/auth>`. |
| |
| CSRF protection middleware |
| -------------------------- |
| |
| .. module:: django.middleware.csrf |
| :synopsis: Middleware adding protection against Cross Site Request |
| Forgeries. |
| |
| .. class:: CsrfMiddleware |
| |
| Adds protection against Cross Site Request Forgeries by adding hidden form |
| fields to POST forms and checking requests for the correct value. See the |
| :doc:`Cross Site Request Forgery protection documentation </ref/contrib/csrf>`. |
| |
| Transaction middleware |
| ---------------------- |
| |
| .. module:: django.middleware.transaction |
| :synopsis: Middleware binding a database transaction to each Web request. |
| |
| .. class:: TransactionMiddleware |
| |
| Binds commit and rollback 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. |
| |
| 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. |
| |
| See the :doc:`transaction management documentation </topics/db/transactions>`. |
