Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

A few minor wording, whitespace, punctuation, and link changes for th…

…e middleware documentation.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@9833 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
commit f76cb41251818f9e30c05b672645667776bcc92e 1 parent bfbd627
Gary Wilson Jr. authored February 15, 2009
56  docs/ref/middleware.txt
@@ -8,8 +8,8 @@ Built-in middleware reference
8 8
    :synopsis: Django's built-in middleware classes.
9 9
 
10 10
 This document explains all middleware components that come with Django. For
11  
-information on how how to use them and how to write your own middleware, see the
12  
-:ref:`middleware usage guide <topics-http-middleware>`.
  11
+information on how how to use them and how to write your own middleware, see
  12
+the :ref:`middleware usage guide <topics-http-middleware>`.
13 13
 
14 14
 Available middleware
15 15
 ====================
@@ -18,8 +18,8 @@ Cache middleware
18 18
 ----------------
19 19
 
20 20
 .. module:: django.middleware.cache
21  
-   :synopsis: Middleware for the site-wide cache
22  
-   
  21
+   :synopsis: Middleware for the site-wide cache.
  22
+
23 23
 .. class:: django.middleware.cache.UpdateCacheMiddleware
24 24
 
25 25
 .. class:: django.middleware.cache.FetchFromCacheMiddleware
@@ -33,7 +33,7 @@ defines. See the :ref:`cache documentation <topics-cache>`.
33 33
 
34 34
 .. module:: django.middleware.common
35 35
    :synopsis: Middleware adding "common" conveniences for perfectionists.
36  
-   
  36
+
37 37
 .. class:: django.middleware.common.CommonMiddleware
38 38
 
39 39
 Adds a few conveniences for perfectionists:
@@ -45,14 +45,14 @@ Adds a few conveniences for perfectionists:
45 45
       :setting:`PREPEND_WWW` settings.
46 46
 
47 47
       If :setting:`APPEND_SLASH` is ``True`` and the initial URL doesn't end
48  
-      with a slash, and it is not found in the URLconf, then a new URL is formed
49  
-      by appending a slash at the end. If this new URL is found in the URLconf,
50  
-      then Django redirects the request to this new URL. Otherwise, the initial
51  
-      URL is processed as usual.
  48
+      with a slash, and it is not found in the URLconf, then a new URL is
  49
+      formed by appending a slash at the end. If this new URL is found in the
  50
+      URLconf, then Django redirects the request to this new URL. Otherwise,
  51
+      the initial URL is processed as usual.
52 52
 
53  
-      For example, ``foo.com/bar`` will be redirected to ``foo.com/bar/`` if you
54  
-      don't have a valid URL pattern for ``foo.com/bar`` but *do* have a valid
55  
-      pattern for ``foo.com/bar/``.
  53
+      For example, ``foo.com/bar`` will be redirected to ``foo.com/bar/`` if
  54
+      you don't have a valid URL pattern for ``foo.com/bar`` but *do* have a
  55
+      valid pattern for ``foo.com/bar/``.
56 56
 
57 57
       .. versionchanged:: 1.0
58 58
          The behavior of :setting:`APPEND_SLASH` has changed slightly in this
@@ -69,8 +69,8 @@ Adds a few conveniences for perfectionists:
69 69
       normalize URLs.
70 70
 
71 71
     * Handles ETags based on the :setting:`USE_ETAGS` setting. If
72  
-      :setting:`USE_ETAGS` is set to ``True``, Django will calculate an ETag for
73  
-      each request by MD5-hashing the page content, and it'll take care of
  72
+      :setting:`USE_ETAGS` is set to ``True``, Django will calculate an ETag
  73
+      for each request by MD5-hashing the page content, and it'll take care of
74 74
       sending ``Not Modified`` responses, if appropriate.
75 75
 
76 76
 View metadata middleware
@@ -90,7 +90,7 @@ GZIP middleware
90 90
 
91 91
 .. module:: django.middleware.gzip
92 92
    :synopsis: Middleware to serve gziped content for performance.
93  
-   
  93
+
94 94
 .. class:: django.middleware.gzip.GZipMiddleware
95 95
 
96 96
 Compresses content for browsers that understand gzip compression (all modern
@@ -139,11 +139,12 @@ Locale middleware
139 139
 
140 140
 .. module:: django.middleware.locale
141 141
    :synopsis: Middleware to enable language selection based on the request.
142  
-   
  142
+
143 143
 .. class:: django.middleware.locale.LocaleMiddleware
144 144
 
145  
-Enables language selection based on data from the request. It customizes content
146  
-for each user. See the :ref:`internationalization documentation <topics-i18n>`.
  145
+Enables language selection based on data from the request. It customizes
  146
+content for each user. See the :ref:`internationalization documentation
  147
+<topics-i18n>`.
147 148
 
148 149
 Session middleware
149 150
 ------------------
@@ -160,18 +161,20 @@ Authentication middleware
160 161
 -------------------------
161 162
 
162 163
 .. module:: django.contrib.auth.middleware
163  
-  :synopsis: Authentication middleware
164  
-  
  164
+  :synopsis: Authentication middleware.
  165
+
165 166
 .. class:: django.contrib.auth.middleware.AuthenticationMiddleware
166 167
 
167  
-Adds the ``user`` attribute, representing the currently-logged-in user, to every
168  
-incoming ``HttpRequest`` object. See :ref:`Authentication in Web requests <topics-auth>`.
  168
+Adds the ``user`` attribute, representing the currently-logged-in user, to
  169
+every incoming ``HttpRequest`` object. See :ref:`Authentication in Web requests
  170
+<topics-auth>`.
169 171
 
170 172
 CSRF protection middleware
171 173
 --------------------------
172 174
 
173 175
 .. module:: django.contrib.csrf.middleware
174  
-   :synopsis: Middleware adding protection against Cross Site Request Forgeries.
  176
+   :synopsis: Middleware adding protection against Cross Site Request
  177
+              Forgeries.
175 178
 
176 179
 .. class:: django.contrib.csrf.middleware.CsrfMiddleware
177 180
 
@@ -189,9 +192,9 @@ Transaction middleware
189 192
 
190 193
 .. class:: django.middleware.transaction.TransactionMiddleware
191 194
 
192  
-Binds commit and rollback to the request/response phase. If a view function runs
193  
-successfully, a commit is done. If it fails with an exception, a rollback is
194  
-done.
  195
+Binds commit and rollback to the request/response phase. If a view function
  196
+runs successfully, a commit is done. If it fails with an exception, a rollback
  197
+is done.
195 198
 
196 199
 The order of this middleware in the stack is important: middleware modules
197 200
 running outside of it run with commit-on-save - the default Django behavior.
@@ -199,4 +202,3 @@ Middleware modules running inside it (coming later in the stack) will be under
199 202
 the same transaction control as the view functions.
200 203
 
201 204
 See the :ref:`transaction management documentation <topics-db-transactions>`.
202  
-
66  docs/topics/http/middleware.txt
@@ -13,9 +13,9 @@ example, Django includes a middleware component, ``XViewMiddleware``, that adds
13 13
 an ``"X-View"`` HTTP header to every response to a ``HEAD`` request.
14 14
 
15 15
 This document explains how middleware works, how you activate middleware, and
16  
-how to write your own middleware. Django ships with some built-in middleware you
17  
-can use right out of the box; they're documented in the :ref:`built-in
18  
-middleware guide <ref-middleware>`.
  16
+how to write your own middleware. Django ships with some built-in middleware
  17
+you can use right out of the box; they're documented in the :ref:`built-in
  18
+middleware reference <ref-middleware>`.
19 19
 
20 20
 Activating middleware
21 21
 =====================
@@ -36,9 +36,9 @@ created by :djadmin:`django-admin.py startproject <startproject>`::
36 36
 During the request phases (:meth:`process_request` and :meth:`process_view`
37 37
 middleware), Django applies middleware in the order it's defined in
38 38
 :setting:`MIDDLEWARE_CLASSES`, top-down. During the response phases
39  
-(:meth:`process_response` and :meth:`process_exception` middleware), the classes
40  
-are applied in reverse order, from the bottom up. You can think of it like an
41  
-onion: each middleware class is a "layer" that wraps the view:
  39
+(:meth:`process_response` and :meth:`process_exception` middleware), the
  40
+classes are applied in reverse order, from the bottom up. You can think of it
  41
+like an onion: each middleware class is a "layer" that wraps the view:
42 42
 
43 43
 .. image:: _images/middleware.png
44 44
    :width: 502
@@ -81,21 +81,22 @@ Response middleware is always called on every response.
81 81
 
82 82
 .. method:: process_view(self, request, view_func, view_args, view_kwargs)
83 83
 
84  
-``request`` is an :class:`~django.http.HttpRequest` object. ``view_func`` is the
85  
-Python function that Django is about to use. (It's the actual function object,
86  
-not the name of the function as a string.) ``view_args`` is a list of positional
87  
-arguments that will be passed to the view, and ``view_kwargs`` is a dictionary
88  
-of keyword arguments that will be passed to the view. Neither ``view_args`` nor
89  
-``view_kwargs`` include the first view argument (``request``).
90  
-
91  
-``process_view()`` is called just before Django calls the view. It should return
92  
-either ``None`` or an :class:`~django.http. HttpResponse` object. If it returns
93  
-``None``, Django will continue processing this request, executing any other
94  
-``process_view()`` middleware and, then, the appropriate view. If it returns an
95  
-:class:`~django.http. HttpResponse` object, Django won't bother calling ANY
96  
-other request, view or exception middleware, or the appropriate view; it'll
97  
-return that :class:`~django.http. HttpResponse`. Response middleware is always
98  
-called on every response.
  84
+``request`` is an :class:`~django.http.HttpRequest` object. ``view_func`` is
  85
+the Python function that Django is about to use. (It's the actual function
  86
+object, not the name of the function as a string.) ``view_args`` is a list of
  87
+positional arguments that will be passed to the view, and ``view_kwargs`` is a
  88
+dictionary of keyword arguments that will be passed to the view. Neither
  89
+``view_args`` nor ``view_kwargs`` include the first view argument
  90
+(``request``).
  91
+
  92
+``process_view()`` is called just before Django calls the view. It should
  93
+return either ``None`` or an :class:`~django.http. HttpResponse` object. If it
  94
+returns ``None``, Django will continue processing this request, executing any
  95
+other ``process_view()`` middleware and, then, the appropriate view. If it
  96
+returns an :class:`~django.http. HttpResponse` object, Django won't bother
  97
+calling ANY other request, view or exception middleware, or the appropriate
  98
+view; it'll return that :class:`~django.http. HttpResponse`. Response
  99
+middleware is always called on every response.
99 100
 
100 101
 .. _response-middleware:
101 102
 
@@ -124,8 +125,8 @@ brand-new :class:`~django.http. HttpResponse`.
124 125
 Django calls ``process_exception()`` when a view raises an exception.
125 126
 ``process_exception()`` should return either ``None`` or an
126 127
 :class:`~django.http. HttpResponse` object. If it returns an
127  
-:class:`~django.http. HttpResponse` object, the response will be returned to the
128  
-browser. Otherwise, default exception handling kicks in.
  128
+:class:`~django.http. HttpResponse` object, the response will be returned to
  129
+the browser. Otherwise, default exception handling kicks in.
129 130
 
130 131
 ``__init__``
131 132
 ------------
@@ -137,7 +138,7 @@ of caveats:
137 138
 
138 139
     * Django initializes your middleware without any arguments, so you can't
139 140
       define ``__init__`` as requiring any arguments.
140  
-      
  141
+
141 142
     * Unlike the ``process_*`` methods which get called once per request,
142 143
       ``__init__`` gets called only *once*, when the web server starts up.
143 144
 
@@ -146,8 +147,8 @@ Marking middleware as unused
146 147
 
147 148
 It's sometimes useful to determine at run-time whether a piece of middleware
148 149
 should be used. In these cases, your middleware's ``__init__`` method may raise
149  
-``django.core.exceptions.MiddlewareNotUsed``. Django will then remove that piece
150  
-of middleware from the middleware process.
  150
+``django.core.exceptions.MiddlewareNotUsed``. Django will then remove that
  151
+piece of middleware from the middleware process.
151 152
 
152 153
 Guidelines
153 154
 ----------
@@ -155,14 +156,11 @@ Guidelines
155 156
     * Middleware classes don't have to subclass anything.
156 157
 
157 158
     * The middleware class can live anywhere on your Python path. All Django
158  
-      cares about is that the :setting:`MIDDLEWARE_CLASSES` setting includes the
159  
-      path
160  
-      to it.
161  
-
162  
-    * Feel free to look at :mod:`Django's available middleware for examples
163  
-      <django.middleware>`. The core Django middleware classes are in
164  
-      ``django/middleware/`` in the Django distribution. The session middleware
165  
-      is in ``django/contrib/sessions``.
  159
+      cares about is that the :setting:`MIDDLEWARE_CLASSES` setting includes
  160
+      the path to it.
  161
+
  162
+    * Feel free to look at :ref:`Django's available middleware
  163
+      <ref-middleware>` for examples.
166 164
 
167 165
     * If you write a middleware component that you think would be useful to
168 166
       other people, contribute to the community! :ref:`Let us know

0 notes on commit f76cb41

Please sign in to comment.
Something went wrong with that request. Please try again.