1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
|
==========
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 how middleware works, how you activate middleware, and
how to write your own middleware. Django ships with some built-in middleware
you can use right out of the box; they're documented in the :doc:`built-in
middleware reference </ref/middleware>`.
Activating middleware
=====================
To activate a middleware component, add it to the :setting:`MIDDLEWARE_CLASSES`
list in your Django settings. In :setting:`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 :setting:`MIDDLEWARE_CLASSES`
created by :djadmin:`django-admin.py startproject <startproject>`::
MIDDLEWARE_CLASSES = (
'django.middleware.common.CommonMiddleware',
'django.contrib.sessions.middleware.SessionMiddleware',
'django.middleware.csrf.CsrfViewMiddleware',
'django.contrib.auth.middleware.AuthenticationMiddleware',
'django.contrib.messages.middleware.MessageMiddleware',
)
During the request phases (:meth:`process_request` and :meth:`process_view`
middleware), Django applies middleware in the order it's defined in
:setting:`MIDDLEWARE_CLASSES`, top-down. During the response phases
(:meth:`process_response` and :meth:`process_exception` middleware), the
classes are applied in reverse order, from the bottom up. You can think of it
like an onion: each middleware class is a "layer" that wraps the view:
.. image:: _images/middleware.png
:width: 502
:height: 417
:alt: Middleware application order.
A Django installation doesn't require any middleware -- e.g.,
:setting:`MIDDLEWARE_CLASSES` can be empty, if you'd like -- but it's strongly
suggested that you at least use
:class:`~django.middleware.common.CommonMiddleware`.
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:
.. _request-middleware:
``process_request``
-------------------
.. method:: process_request(self, request)
``request`` is an :class:`~django.http.HttpRequest` object. This method is
called on each request, before Django decides which view to execute.
``process_request()`` should return either ``None`` or an
:class:`~django.http.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 :class:`~django.http.HttpResponse` object,
Django won't bother calling ANY other request, view or exception middleware, or
the appropriate view; it'll return that :class:`~django.http.HttpResponse`.
Response middleware is always called on every response.
.. _view-middleware:
``process_view``
----------------
.. method:: process_view(self, request, view_func, view_args, view_kwargs)
``request`` is an :class:`~django.http.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 :class:`~django.http. 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 :class:`~django.http. HttpResponse` object, Django won't bother
calling ANY other request, view or exception middleware, or the appropriate
view; it'll return that :class:`~django.http. HttpResponse`. Response
middleware is always called on every response.
.. _response-middleware:
``process_response``
--------------------
.. method:: process_response(self, request, response)
``request`` is an :class:`~django.http.HttpRequest` object. ``response`` is the
:class:`~django.http. HttpResponse` object returned by a Django view.
``process_response()`` must return an :class:`~django.http. HttpResponse`
object. It could alter the given ``response``, or it could create and return a
brand-new :class:`~django.http. HttpResponse`.
Unlike the ``process_request()`` and ``process_view()`` methods, the
``process_response()`` method is always called, even if the ``process_request()``
and ``process_view()`` methods of the same middleware class were skipped because
an earlier middleware method returned an :class:`~django.http. HttpResponse`
(this means that your ``process_response()`` method cannot rely on setup done in
``process_request()``, for example). In addition, during the response phase the
classes are applied in reverse order, from the bottom up. This means classes
defined at the end of :setting:`MIDDLEWARE_CLASSES` will be run first.
.. _exception-middleware:
``process_exception``
---------------------
.. method:: process_exception(self, request, exception)
``request`` is an :class:`~django.http.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
:class:`~django.http. HttpResponse` object. If it returns an
:class:`~django.http. HttpResponse` object, the response will be returned to
the browser. Otherwise, default exception handling kicks in.
Again, middleware are run in reverse order during the response phase, which
includes ``process_exception``. If an exception middleware return a response,
the middleware classes above that middleware will not be called at all.
``__init__``
------------
Most middleware classes won't need an initializer since middleware classes are
essentially placeholders for the ``process_*`` methods. If you do need some
global state you may use ``__init__`` to set up. However, keep in mind a couple
of caveats:
* Django initializes your middleware without any arguments, so you can't
define ``__init__`` as requiring any arguments.
* Unlike the ``process_*`` methods which get called once per request,
``__init__`` gets called only *once*, when the web server starts up.
Marking middleware as unused
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
It's sometimes useful to determine at run-time whether a piece of middleware
should be used. In these cases, your middleware's ``__init__`` method may raise
``django.core.exceptions.MiddlewareNotUsed``. Django will then remove that
piece of middleware from the middleware process.
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 :setting:`MIDDLEWARE_CLASSES` setting includes
the path to it.
* Feel free to look at :doc:`Django's available middleware
</ref/middleware>` for examples.
* If you write a middleware component that you think would be useful to
other people, contribute to the community! :doc:`Let us know
</internals/contributing>`, and we'll consider adding it to Django.
|
