+
−==========
+
−Middleware
+
−==========
+
−
+
−Middleware is a framework of hooks into Django's request/response processing.
+
−It's a light, low-level "plugin" system for globally altering Django's input
+
−and/or output.
+
−
+
−Each middleware component is responsible for doing some specific function. For
+
−example, Django includes a middleware component, ``XViewMiddleware``, that adds
+
−an ``"X-View"`` HTTP header to every response to a ``HEAD`` request.
+
−
+
−This document explains all middleware components that come with Django, how to
+
−use them, and how to write your own middleware.
+
−
+
−Activating middleware
+
−=====================
+
−
+
−To activate a middleware component, add it to the ``MIDDLEWARE_CLASSES`` list
+
−in your Django settings. In ``MIDDLEWARE_CLASSES``, each middleware component
+
−is represented by a string: the full Python path to the middleware's class
+
−name. For example, here's the default ``MIDDLEWARE_CLASSES`` created by
+
−``django-admin.py startproject``::
+
−
+
−    MIDDLEWARE_CLASSES = (
+
−        'django.middleware.common.CommonMiddleware',
+
−        'django.contrib.sessions.middleware.SessionMiddleware',
+
−        'django.contrib.auth.middleware.AuthenticationMiddleware',
+
−        'django.middleware.doc.XViewMiddleware',
+
−    )
+
−
+
−Django applies middleware in the order it's defined in ``MIDDLEWARE_CLASSES``,
+
−except in the case of response and exception middleware, which is applied in
+
−reverse order.
+
−
+
−A Django installation doesn't require any middleware -- e.g.,
+
−``MIDDLEWARE_CLASSES`` can be empty, if you'd like -- but it's strongly
+
−suggested that you use ``CommonMiddleware``.
+
−
+
−Available middleware
+
−====================
+
−
+
−django.middleware.cache.CacheMiddleware
+
−---------------------------------------
+
−
+
−Enables site-wide cache. If this is enabled, each Django-powered page will be
+
−cached for as long as the ``CACHE_MIDDLEWARE_SECONDS`` setting defines. See
+
−the `cache documentation`_.
+
−
+
−.. _`cache documentation`: ../cache/#the-per-site-cache
+
−
+
−django.middleware.common.CommonMiddleware
+
−-----------------------------------------
+
−
+
−Adds a few conveniences for perfectionists:
+
−
+
−* Forbids access to user agents in the ``DISALLOWED_USER_AGENTS`` setting,
+
−  which should be a list of strings.
+
−
+
−* Performs URL rewriting based on the ``APPEND_SLASH`` and ``PREPEND_WWW``
+
−  settings. If ``APPEND_SLASH`` is ``True``, URLs that lack a trailing
+
−  slash will be redirected to the same URL with a trailing slash, unless the
+
−  last component in the path contains a period. So ``foo.com/bar`` is
+
−  redirected to ``foo.com/bar/``, but ``foo.com/bar/file.txt`` is passed
+
−  through unchanged.
+
−
+
−  If ``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.
+
−
+
−* Handles ETags based on the ``USE_ETAGS`` setting. If ``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.
+
−
+
−django.middleware.doc.XViewMiddleware
+
−-------------------------------------
+
−
+
−Sends custom ``X-View`` HTTP headers to HEAD requests that come from IP
+
−addresses defined in the ``INTERNAL_IPS`` setting. This is used by Django's
+
−automatic documentation system.
+
−
+
−django.middleware.gzip.GZipMiddleware
+
−-------------------------------------
+
−
+
−Compresses content for browsers that understand gzip compression (all modern
+
−browsers).
+
−
+
−django.middleware.http.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 HttpNotModified.
+
−
+
−Also removes the content from any response to a HEAD request and sets the
+
−``Date`` and ``Content-Length`` response-headers.
+
−
+
−django.middleware.http.SetRemoteAddrFromForwardedFor
+
−----------------------------------------------------
+
−
+
−Sets ``request.META['REMOTE_ADDR']`` based on
+
−``request.META['HTTP_X_FORWARDED_FOR']``, if the latter is set. This is useful
+
−if you're sitting behind a reverse proxy that causes each request's
+
−``REMOTE_ADDR`` to be set to ``127.0.0.1``.
+
−
+
−**Important note:** This does NOT validate ``HTTP_X_FORWARDED_FOR``. If you're
+
−not behind a reverse proxy that sets ``HTTP_X_FORWARDED_FOR`` automatically, do
+
−not use this middleware. Anybody can spoof the value of
+
−``HTTP_X_FORWARDED_FOR``, and because this sets ``REMOTE_ADDR`` based on
+
−``HTTP_X_FORWARDED_FOR``, that means anybody can "fake" their IP address. Only
+
−use this when you can absolutely trust the value of ``HTTP_X_FORWARDED_FOR``.
+
−
+
−django.contrib.sessions.middleware.SessionMiddleware
+
−----------------------------------------------------
+
−
+
−Enables session support. See the `session documentation`_.
+
−
+
−.. _`session documentation`: ../sessions/
+
−
+
−django.contrib.auth.middleware.AuthenticationMiddleware
+
−-------------------------------------------------------
+
−
+
−Adds the ``user`` attribute, representing the currently-logged-in user, to
+
−every incoming ``HttpRequest`` object. See `Authentication in Web requests`_.
+
−
+
−.. _Authentication in Web requests: ../authentication/#authentication-in-web-requests
+
−
+
−django.middleware.transaction.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 `transaction management documentation`_.
+
−
+
−.. _`transaction management documentation`: ../transactions/
+
−
+
−Writing your own middleware
+
−===========================
+
−
+
−Writing your own middleware is easy. Each middleware component is a single
+
−Python class that defines one or more of the following methods:
+
−
+
−process_request
+
−---------------
+
−
+
−Interface: ``process_request(self, request)``
+
−
+
−``request`` is an ``HttpRequest`` object. This method is called on each
+
−request, before Django decides which view to execute.
+
−
+
−``process_request()`` should return either ``None`` or an ``HttpResponse``
+
−object. If it returns ``None``, Django will continue processing this request,
+
−executing any other middleware and, then, the appropriate view. If it returns
+
−an ``HttpResponse`` object, Django won't bother calling ANY other middleware or
+
−the appropriate view; it'll return that ``HttpResponse``.
+
−
+
−process_view
+
−------------
+
−
+
−Interface: ``process_view(self, request, view_func, view_args, view_kwargs)``
+
−
+
−``request`` is an ``HttpRequest`` object. ``view_func`` is the Python function
+
−that Django is about to use. (It's the actual function object, not the name of
+
−the function as a string.) ``view_args`` is a list of positional arguments that
+
−will be passed to the view, and ``view_kwargs`` is a dictionary of keyword
+
−arguments that will be passed to the view. Neither ``view_args`` nor
+
−``view_kwargs`` include the first view argument (``request``).
+
−
+
−``process_view()`` is called just before Django calls the view. It should
+
−return either ``None`` or an ``HttpResponse`` object. If it returns ``None``,
+
−Django will continue processing this request, executing any other
+
−``process_view()`` middleware and, then, the appropriate view. If it returns an
+
−``HttpResponse`` object, Django won't bother calling ANY other middleware or
+
−the appropriate view; it'll return that ``HttpResponse``.
+
−
+
−process_response
+
−----------------
+
−
+
−Interface: ``process_response(self, request, response)``
+
−
+
−``request`` is an ``HttpRequest`` object. ``response`` is the ``HttpResponse``
+
−object returned by a Django view.
+
−
+
−``process_response()`` should return an ``HttpResponse`` object. It could alter
+
−the given ``response``, or it could create and return a brand-new
+
−``HttpResponse``.
+
−
+
−process_exception
+
−-----------------
+
−
+
−Interface: ``process_exception(self, request, exception)``
+
−
+
−``request`` is an ``HttpRequest`` object. ``exception`` is an ``Exception``
+
−object raised by the view function.
+
−
+
−Django calls ``process_exception()`` when a view raises an exception.
+
−``process_exception()`` should return either ``None`` or an ``HttpResponse``
+
−object. If it returns an ``HttpResponse`` object, the response will be returned
+
−to the browser. Otherwise, default exception handling kicks in.
+
−
+
−Guidelines
+
−----------
+
−
+
−    * Middleware classes don't have to subclass anything.
+
−
+
−    * The middleware class can live anywhere on your Python path. All Django
+
−      cares about is that the ``MIDDLEWARE_CLASSES`` setting includes the path
+
−      to it.
+
−
+
−    * Feel free to look at Django's available middleware for examples. The
+
−      core Django middleware classes are in ``django/middleware/`` in the
+
−      Django distribution. The session middleware is in ``django/contrib/sessions``.
+
−
+
−    * If you write a middleware component that you think would be useful to
+
−      other people, contribute to the community! Let us know, and we'll
+
−      consider adding it to Django.