From f76cb41251818f9e30c05b672645667776bcc92e Mon Sep 17 00:00:00 2001 From: Gary Wilson Jr Date: Sun, 15 Feb 2009 05:46:00 +0000 Subject: [PATCH] A few minor wording, whitespace, punctuation, and link changes for the middleware documentation. git-svn-id: http://code.djangoproject.com/svn/django/trunk@9833 bcc190cf-cafb-0310-a4f2-bffc1f526a37 --- docs/ref/middleware.txt | 56 +++++++++++++++-------------- docs/topics/http/middleware.txt | 62 ++++++++++++++++----------------- 2 files changed, 59 insertions(+), 59 deletions(-) diff --git a/docs/ref/middleware.txt b/docs/ref/middleware.txt index e47accc0aa..5125f6e064 100644 --- a/docs/ref/middleware.txt +++ b/docs/ref/middleware.txt @@ -8,8 +8,8 @@ Built-in middleware reference :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 -:ref:`middleware usage guide `. +information on how how to use them and how to write your own middleware, see +the :ref:`middleware usage guide `. Available middleware ==================== @@ -18,8 +18,8 @@ Cache middleware ---------------- .. module:: django.middleware.cache - :synopsis: Middleware for the site-wide cache - + :synopsis: Middleware for the site-wide cache. + .. class:: django.middleware.cache.UpdateCacheMiddleware .. class:: django.middleware.cache.FetchFromCacheMiddleware @@ -33,7 +33,7 @@ defines. See the :ref:`cache documentation `. .. module:: django.middleware.common :synopsis: Middleware adding "common" conveniences for perfectionists. - + .. class:: django.middleware.common.CommonMiddleware Adds a few conveniences for perfectionists: @@ -45,14 +45,14 @@ Adds a few conveniences for perfectionists: :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. + 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/``. + 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/``. .. versionchanged:: 1.0 The behavior of :setting:`APPEND_SLASH` has changed slightly in this @@ -69,8 +69,8 @@ Adds a few conveniences for perfectionists: normalize URLs. * 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 + :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 @@ -90,7 +90,7 @@ GZIP middleware .. module:: django.middleware.gzip :synopsis: Middleware to serve gziped content for performance. - + .. class:: django.middleware.gzip.GZipMiddleware Compresses content for browsers that understand gzip compression (all modern @@ -139,11 +139,12 @@ Locale middleware .. module:: django.middleware.locale :synopsis: Middleware to enable language selection based on the request. - + .. class:: django.middleware.locale.LocaleMiddleware -Enables language selection based on data from the request. It customizes content -for each user. See the :ref:`internationalization documentation `. +Enables language selection based on data from the request. It customizes +content for each user. See the :ref:`internationalization documentation +`. Session middleware ------------------ @@ -160,18 +161,20 @@ Authentication middleware ------------------------- .. module:: django.contrib.auth.middleware - :synopsis: Authentication middleware - + :synopsis: Authentication middleware. + .. class:: django.contrib.auth.middleware.AuthenticationMiddleware -Adds the ``user`` attribute, representing the currently-logged-in user, to every -incoming ``HttpRequest`` object. See :ref:`Authentication in Web requests `. +Adds the ``user`` attribute, representing the currently-logged-in user, to +every incoming ``HttpRequest`` object. See :ref:`Authentication in Web requests +`. CSRF protection middleware -------------------------- .. module:: django.contrib.csrf.middleware - :synopsis: Middleware adding protection against Cross Site Request Forgeries. + :synopsis: Middleware adding protection against Cross Site Request + Forgeries. .. class:: django.contrib.csrf.middleware.CsrfMiddleware @@ -189,9 +192,9 @@ Transaction middleware .. class:: 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. +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. @@ -199,4 +202,3 @@ Middleware modules running inside it (coming later in the stack) will be under the same transaction control as the view functions. See the :ref:`transaction management documentation `. - diff --git a/docs/topics/http/middleware.txt b/docs/topics/http/middleware.txt index d5b36ea7e3..54d4c42194 100644 --- a/docs/topics/http/middleware.txt +++ b/docs/topics/http/middleware.txt @@ -13,9 +13,9 @@ 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 :ref:`built-in -middleware guide `. +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 :ref:`built-in +middleware reference `. Activating middleware ===================== @@ -36,9 +36,9 @@ created by :djadmin:`django-admin.py startproject `:: 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: +(: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 @@ -81,21 +81,22 @@ Response middleware is always called on every response. .. 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``). +``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. +``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: @@ -124,8 +125,8 @@ brand-new :class:`~django.http. HttpResponse`. 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. +:class:`~django.http. HttpResponse` object, the response will be returned to +the browser. Otherwise, default exception handling kicks in. ``__init__`` ------------ @@ -137,7 +138,7 @@ 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. @@ -146,8 +147,8 @@ 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. +``django.core.exceptions.MiddlewareNotUsed``. Django will then remove that +piece of middleware from the middleware process. Guidelines ---------- @@ -155,14 +156,11 @@ 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. + cares about is that the :setting:`MIDDLEWARE_CLASSES` setting includes + the path to it. - * Feel free to look at :mod:`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``. + * Feel free to look at :ref:`Django's available middleware + ` for examples. * If you write a middleware component that you think would be useful to other people, contribute to the community! :ref:`Let us know