Fixed #26601 -- Improved middleware per DEP 0005.

Thanks Tim Graham for polishing the patch, updating the tests, and
writing documentation. Thanks Carl Meyer for shepherding the DEP.

13 files changed, 87 insertions, 36 deletions

diff --git a/docs/ref/applications.txt b/docs/ref/applications.txt
index be761505fe..53d9bcd9b5 100644
--- a/docs/ref/applications.txt
+++ b/docs/ref/applications.txt
@@ -37,8 +37,8 @@ projects.
 Applications include some combination of models, views, templates, template
 tags, static files, URLs, middleware, etc. They're generally wired into
 projects with the :setting:`INSTALLED_APPS` setting and optionally with other
-mechanisms such as URLconfs, the :setting:`MIDDLEWARE_CLASSES` setting, or
-template inheritance.
+mechanisms such as URLconfs, the :setting:`MIDDLEWARE` setting, or template
+inheritance.
 
 It is important to understand that a Django application is just a set of code
 that interacts with various parts of the framework. There's no such thing as
diff --git a/docs/ref/checks.txt b/docs/ref/checks.txt
index e4af02c1a2..5057ef18b6 100644
--- a/docs/ref/checks.txt
+++ b/docs/ref/checks.txt
@@ -491,19 +491,19 @@ The following checks are run if you use the :option:`check --deploy` option:
 
 * **security.W001**: You do not have
   :class:`django.middleware.security.SecurityMiddleware` in your
-  :setting:`MIDDLEWARE_CLASSES` so the :setting:`SECURE_HSTS_SECONDS`,
+  :setting:`MIDDLEWARE`/:setting:`MIDDLEWARE_CLASSES` so the :setting:`SECURE_HSTS_SECONDS`,
   :setting:`SECURE_CONTENT_TYPE_NOSNIFF`, :setting:`SECURE_BROWSER_XSS_FILTER`,
   and :setting:`SECURE_SSL_REDIRECT` settings will have no effect.
 * **security.W002**: You do not have
   :class:`django.middleware.clickjacking.XFrameOptionsMiddleware` in your
-  :setting:`MIDDLEWARE_CLASSES`, so your pages will not be served with an
+  :setting:`MIDDLEWARE`/:setting:`MIDDLEWARE_CLASSES`, so your pages will not be served with an
   ``'x-frame-options'`` header. Unless there is a good reason for your
   site to be served in a frame, you should consider enabling this
   header to help prevent clickjacking attacks.
 * **security.W003**: You don't appear to be using Django's built-in cross-site
   request forgery protection via the middleware
   (:class:`django.middleware.csrf.CsrfViewMiddleware` is not in your
-  :setting:`MIDDLEWARE_CLASSES`). Enabling the middleware is the safest
+  :setting:`MIDDLEWARE`/:setting:`MIDDLEWARE_CLASSES`). Enabling the middleware is the safest
   approach to ensure you don't leave any holes.
 * **security.W004**: You have not set a value for the
   :setting:`SECURE_HSTS_SECONDS` setting. If your entire site is served only
@@ -540,7 +540,7 @@ The following checks are run if you use the :option:`check --deploy` option:
   sessions.
 * **security.W011**: You have
   :class:`django.contrib.sessions.middleware.SessionMiddleware` in your
-  :setting:`MIDDLEWARE_CLASSES`, but you have not set
+  :setting:`MIDDLEWARE`/:setting:`MIDDLEWARE_CLASSES`, but you have not set
   :setting:`SESSION_COOKIE_SECURE` to ``True``. Using a secure-only session
   cookie makes it more difficult for network traffic sniffers to hijack user
   sessions.
@@ -554,7 +554,7 @@ The following checks are run if you use the :option:`check --deploy` option:
   sessions.
 * **security.W014**: You have
   :class:`django.contrib.sessions.middleware.SessionMiddleware` in your
-  :setting:`MIDDLEWARE_CLASSES`, but you have not set
+  :setting:`MIDDLEWARE`/:setting:`MIDDLEWARE_CLASSES`, but you have not set
   :setting:`SESSION_COOKIE_HTTPONLY` to ``True``. Using an ``HttpOnly`` session
   cookie makes it more difficult for cross-site scripting attacks to hijack user
   sessions.
@@ -571,7 +571,7 @@ The following checks are run if you use the :option:`check --deploy` option:
   deployment.
 * **security.W019**: You have
   :class:`django.middleware.clickjacking.XFrameOptionsMiddleware` in your
-  :setting:`MIDDLEWARE_CLASSES`, but :setting:`X_FRAME_OPTIONS` is not set to
+  :setting:`MIDDLEWARE`/:setting:`MIDDLEWARE_CLASSES`, but :setting:`X_FRAME_OPTIONS` is not set to
   ``'DENY'``. The default is ``'SAMEORIGIN'``, but unless there is a good reason
   for your site to serve other parts of itself in a frame, you should change
   it to ``'DENY'``.
diff --git a/docs/ref/clickjacking.txt b/docs/ref/clickjacking.txt
index abac81dcd8..2f72e18d2f 100644
--- a/docs/ref/clickjacking.txt
+++ b/docs/ref/clickjacking.txt
@@ -56,9 +56,9 @@ Setting ``X-Frame-Options`` for all responses
 
 To set the same ``X-Frame-Options`` value for all responses in your site, put
 ``'django.middleware.clickjacking.XFrameOptionsMiddleware'`` to
-:setting:`MIDDLEWARE_CLASSES`::
+:setting:`MIDDLEWARE`::
 
-    MIDDLEWARE_CLASSES = [
+    MIDDLEWARE = [
         ...
         'django.middleware.clickjacking.XFrameOptionsMiddleware',
         ...
diff --git a/docs/ref/contrib/admin/index.txt b/docs/ref/contrib/admin/index.txt
index eed7d4451c..66b116ad35 100644
--- a/docs/ref/contrib/admin/index.txt
+++ b/docs/ref/contrib/admin/index.txt
@@ -41,8 +41,8 @@ For reference, here are the requirements:
    defined in your :setting:`TEMPLATES` as well as
    :class:`django.contrib.auth.middleware.AuthenticationMiddleware` and
    :class:`django.contrib.messages.middleware.MessageMiddleware` to
-   :setting:`MIDDLEWARE_CLASSES`. (These are all active by default, so
-   you only need to do this if you've manually tweaked the settings.)
+   :setting:`MIDDLEWARE`. These are all active by default, so you only need to
+   do this if you've manually tweaked the settings.
 
 4. Determine which of your application's models should be editable in the
    admin interface.
diff --git a/docs/ref/contrib/flatpages.txt b/docs/ref/contrib/flatpages.txt
index 3326a93ea8..580f864c34 100644
--- a/docs/ref/contrib/flatpages.txt
+++ b/docs/ref/contrib/flatpages.txt
@@ -53,7 +53,7 @@ Then either:
 or:
 
 3. Add ``'django.contrib.flatpages.middleware.FlatpageFallbackMiddleware'``
-   to your :setting:`MIDDLEWARE_CLASSES` setting.
+   to your :setting:`MIDDLEWARE` setting.
 
 4. Run the command :djadmin:`manage.py migrate <migrate>`.
 
@@ -144,8 +144,7 @@ can do all of the work.
    methods. Only requests which are successfully routed to a view via
    normal URL resolution apply view middleware.
 
-Note that the order of :setting:`MIDDLEWARE_CLASSES` matters. Generally, you
-can put
+Note that the order of :setting:`MIDDLEWARE` matters. Generally, you can put
 :class:`~django.contrib.flatpages.middleware.FlatpageFallbackMiddleware` at the
 end of the list. This means it will run first when processing the response, and
 ensures that any other response-processing middlewares see the real flatpage
diff --git a/docs/ref/contrib/messages.txt b/docs/ref/contrib/messages.txt
index d425899cd9..414cf21116 100644
--- a/docs/ref/contrib/messages.txt
+++ b/docs/ref/contrib/messages.txt
@@ -27,14 +27,14 @@ already contains all the settings required to enable message functionality:
 
 * ``'django.contrib.messages'`` is in :setting:`INSTALLED_APPS`.
 
-* :setting:`MIDDLEWARE_CLASSES` contains
+* :setting:`MIDDLEWARE` contains
   ``'django.contrib.sessions.middleware.SessionMiddleware'`` and
   ``'django.contrib.messages.middleware.MessageMiddleware'``.
 
   The default :ref:`storage backend <message-storage-backends>` relies on
   :doc:`sessions </topics/http/sessions>`. That's why ``SessionMiddleware``
   must be enabled and appear before ``MessageMiddleware`` in
-  :setting:`MIDDLEWARE_CLASSES`.
+  :setting:`MIDDLEWARE`.
 
 * The ``'context_processors'`` option of the ``DjangoTemplates`` backend
   defined in your :setting:`TEMPLATES` setting contains
@@ -42,8 +42,8 @@ already contains all the settings required to enable message functionality:
 
 If you don't want to use messages, you can remove
 ``'django.contrib.messages'`` from your :setting:`INSTALLED_APPS`, the
-``MessageMiddleware`` line from :setting:`MIDDLEWARE_CLASSES`, and the
-``messages`` context processor from :setting:`TEMPLATES`.
+``MessageMiddleware`` line from :setting:`MIDDLEWARE`, and the ``messages``
+context processor from :setting:`TEMPLATES`.
 
 Configuring the message engine
 ==============================
diff --git a/docs/ref/contrib/redirects.txt b/docs/ref/contrib/redirects.txt
index 2aadf8a45c..8af48ba8b2 100644
--- a/docs/ref/contrib/redirects.txt
+++ b/docs/ref/contrib/redirects.txt
@@ -18,7 +18,7 @@ To install the redirects app, follow these steps:
    :ref:`is installed <enabling-the-sites-framework>`.
 2. Add ``'django.contrib.redirects'`` to your :setting:`INSTALLED_APPS` setting.
 3. Add ``'django.contrib.redirects.middleware.RedirectFallbackMiddleware'``
-   to your :setting:`MIDDLEWARE_CLASSES` setting.
+   to your :setting:`MIDDLEWARE` setting.
 4. Run the command :djadmin:`manage.py migrate <migrate>`.
 
 How it works
@@ -49,9 +49,9 @@ given ``old_path`` with a site ID that corresponds to the
 The middleware only gets activated for 404s -- not for 500s or responses of any
 other status code.
 
-Note that the order of :setting:`MIDDLEWARE_CLASSES` matters. Generally, you
-can put :class:`~django.contrib.redirects.middleware.RedirectFallbackMiddleware`
-at the end of the list, because it's a last resort.
+Note that the order of :setting:`MIDDLEWARE` matters. Generally, you can put
+:class:`~django.contrib.redirects.middleware.RedirectFallbackMiddleware` at the
+end of the list, because it's a last resort.
 
 For more on middleware, read the :doc:`middleware docs
 </topics/http/middleware>`.
diff --git a/docs/ref/contrib/sites.txt b/docs/ref/contrib/sites.txt
index 2f312d04e0..ec2c1bf2b2 100644
--- a/docs/ref/contrib/sites.txt
+++ b/docs/ref/contrib/sites.txt
@@ -405,8 +405,8 @@ If you often use this pattern::
 
 there is simple way to avoid repetitions. Add
 :class:`django.contrib.sites.middleware.CurrentSiteMiddleware` to
-:setting:`MIDDLEWARE_CLASSES`. The middleware sets the ``site`` attribute on
-every request object, so you can use ``request.site`` to get the current site.
+:setting:`MIDDLEWARE`. The middleware sets the ``site`` attribute on every
+request object, so you can use ``request.site`` to get the current site.
 
 How Django uses the sites framework
 ===================================
diff --git a/docs/ref/csrf.txt b/docs/ref/csrf.txt
index f59b45646d..277fd85720 100644
--- a/docs/ref/csrf.txt
+++ b/docs/ref/csrf.txt
@@ -27,10 +27,10 @@ How to use it
 
 To take advantage of CSRF protection in your views, follow these steps:
 
-1. The CSRF middleware is activated by default in the
-   :setting:`MIDDLEWARE_CLASSES` setting. If you override that setting, remember
-   that ``'django.middleware.csrf.CsrfViewMiddleware'`` should come before any
-   view middleware that assume that CSRF attacks have been dealt with.
+1. The CSRF middleware is activated by default in the :setting:`MIDDLEWARE`
+   setting. If you override that setting, remember that
+   ``'django.middleware.csrf.CsrfViewMiddleware'`` should come before any view
+   middleware that assume that CSRF attacks have been dealt with.
 
    If you disabled it, which is not recommended, you can use
    :func:`~django.views.decorators.csrf.csrf_protect` on particular views
diff --git a/docs/ref/middleware.txt b/docs/ref/middleware.txt
index 49062d3474..1e582d5724 100644
--- a/docs/ref/middleware.txt
+++ b/docs/ref/middleware.txt
@@ -77,6 +77,36 @@ issued by the middleware.
 * Sends broken link notification emails to :setting:`MANAGERS` (see
   :doc:`/howto/error-reporting`).
 
+Exception middleware
+--------------------
+
+.. module:: django.middleware.exception
+   :synopsis: Middleware to return responses for exceptions.
+
+.. class:: ExceptionMiddleware
+
+.. versionadded:: 1.10
+
+Catches exceptions raised during the request/response cycle and returns the
+appropriate response.
+
+* :class:`~django.http.Http404` is processed by
+  :data:`~django.conf.urls.handler404` (or a more friendly debug page if
+  :setting:`DEBUG=True <DEBUG>`).
+* :class:`~django.core.exceptions.PermissionDenied` is processed
+  by :data:`~django.conf.urls.handler403`.
+* ``MultiPartParserError`` is processed by :data:`~django.conf.urls.handler400`.
+* :class:`~django.core.exceptions.SuspiciousOperation` is processed by
+  :data:`~django.conf.urls.handler400`  (or a more friendly debug page if
+  :setting:`DEBUG=True <DEBUG>`).
+* Any other exception is processed by :data:`~django.conf.urls.handler500`
+  (or a more friendly debug page if :setting:`DEBUG=True <DEBUG>`).
+
+Django uses this middleware regardless of whether or not you include it in
+:setting:`MIDDLEWARE`, however, you may want to subclass if your own middleware
+needs to transform any of these exceptions into the appropriate responses.
+:class:`~django.middleware.locale.LocaleMiddleware` does this, for example.
+
 GZip middleware
 ---------------
 
diff --git a/docs/ref/request-response.txt b/docs/ref/request-response.txt
index 64bd5960cd..96f5300f8b 100644
--- a/docs/ref/request-response.txt
+++ b/docs/ref/request-response.txt
@@ -176,9 +176,9 @@ All attributes should be considered read-only, unless stated otherwise.
 
     An instance of :class:`~django.urls.ResolverMatch` representing the
     resolved URL. This attribute is only set after URL resolving took place,
-    which means it's available in all views but not in middleware methods
-    which are executed before URL resolving takes place (like
-    ``process_request()``, you can use ``process_view()`` instead).
+    which means it's available in all views but not in middleware which are
+    executed before URL resolving takes place (you can use it in
+    :meth:`process_view` though).
 
 Attributes set by application code
 ----------------------------------
@@ -210,7 +210,7 @@ Attributes set by middleware
 
 Some of the middleware included in Django's contrib apps set attributes on the
 request. If you don't see the attribute on a request, be sure the appropriate
-middleware class is listed in :setting:`MIDDLEWARE_CLASSES`.
+middleware class is listed in :setting:`MIDDLEWARE`.
 
 .. attribute:: HttpRequest.session
 
@@ -257,7 +257,9 @@ Methods
         behind multiple proxies. One solution is to use middleware to rewrite
         the proxy headers, as in the following example::
 
-            class MultipleProxyMiddleware(object):
+            from django.django.utils.deprecation import MiddlewareMixin
+
+            class MultipleProxyMiddleware(MiddlewareMixin):
                 FORWARDED_FOR_FIELDS = [
                     'HTTP_X_FORWARDED_FOR',
                     'HTTP_X_FORWARDED_HOST',
diff --git a/docs/ref/settings.txt b/docs/ref/settings.txt
index 838dde808a..a7801f715c 100644
--- a/docs/ref/settings.txt
+++ b/docs/ref/settings.txt
@@ -77,7 +77,7 @@ can be used as a subdomain wildcard: ``'.example.com'`` will match
 ``example.com``. A value of ``'*'`` will match anything; in this case you are
 responsible to provide your own validation of the ``Host`` header (perhaps in a
 middleware; if so this middleware must be listed first in
-:setting:`MIDDLEWARE_CLASSES`).
+:setting:`MIDDLEWARE`).
 
 Django also allows the `fully qualified domain name (FQDN)`_ of any entries.
 Some browsers include a trailing dot in the ``Host`` header which Django
@@ -1844,6 +1844,17 @@ Example: ``"http://media.example.com/"``
     :setting:`MEDIA_URL` and :setting:`STATIC_URL` must have different
     values. See :setting:`MEDIA_ROOT` for more details.
 
+.. setting:: MIDDLEWARE
+
+``MIDDLEWARE``
+--------------
+
+.. versionadded:: 1.10
+
+Default:: ``None``
+
+A list of middleware to use. See :doc:`/topics/http/middleware`.
+
 .. setting:: MIDDLEWARE_CLASSES
 
 ``MIDDLEWARE_CLASSES``
@@ -1856,7 +1867,11 @@ Default::
         'django.middleware.csrf.CsrfViewMiddleware',
     ]
 
-A list of middleware classes to use. See :doc:`/topics/http/middleware`.
+A list of middleware classes to use. This was the default setting used in
+Django 1.9 and earlier. Django 1.10 introduced a new style of middleware. If
+you have an older project using this setting you should :ref:`update any
+middleware you've written yourself <upgrading-middleware>` to the new style
+and then use the :setting:`MIDDLEWARE` setting.
 
 .. setting:: MIGRATION_MODULES
 
@@ -3312,6 +3327,7 @@ HTTP
 * :setting:`DISALLOWED_USER_AGENTS`
 * :setting:`FORCE_SCRIPT_NAME`
 * :setting:`INTERNAL_IPS`
+* :setting:`MIDDLEWARE`
 * :setting:`MIDDLEWARE_CLASSES`
 * Security
 
diff --git a/docs/ref/utils.txt b/docs/ref/utils.txt
index f95ff1017f..1b527277af 100644
--- a/docs/ref/utils.txt
+++ b/docs/ref/utils.txt
@@ -173,6 +173,10 @@ The functions defined in this module share the following properties:
     middleware functionality on a per-view basis. The middleware is created
     with no params passed.
 
+    It assumes middleware that's compatible with the old style of Django 1.9
+    and earlier (having methods like ``process_request()``,
+    ``process_exception()``, and ``process_response()``).
+
 .. function:: decorator_from_middleware_with_args(middleware_class)
 
     Like ``decorator_from_middleware``, but returns a function