diff -r 261778de26ff -r 620f9b141567 thirdparty/google_appengine/lib/django/docs/middleware.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/thirdparty/google_appengine/lib/django/docs/middleware.txt Tue Aug 26 21:49:54 2008 +0000 @@ -0,0 +1,229 @@ +========== +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.