From 1dc57d53c54338df467e6c1e8201589eab73022f Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Sat, 6 Aug 2011 18:21:11 -0400 Subject: docs --- pyramid/config.py | 33 +++++++++++++++++++++------------ 1 file changed, 21 insertions(+), 12 deletions(-) diff --git a/pyramid/config.py b/pyramid/config.py index c1adb51c9..918e3bce4 100644 --- a/pyramid/config.py +++ b/pyramid/config.py @@ -909,14 +909,14 @@ class Configurator(object): @action_method def add_tween(self, tween_factory): """ - Add a 'tween factory'. A :term`tween` (think: 'between') is a bit of - code that sits between the Pyramid router's main request handling + Add a 'tween factory'. A :term:`tween` (think: 'between') is a bit + of code that sits between the Pyramid router's main request handling function and the upstream WSGI component that uses :app:`Pyramid` as its 'app'. This is a feature that may be used by Pyramid framework extensions, to provide, for example, Pyramid-specific view timing support bookkeeping code that examines exceptions before they are returned to the upstream WSGI application. Tweens behave a bit like - :mod:`WSGI` 'middleware' but they have the benefit of running in a + :term:`WSGI` 'middleware' but they have the benefit of running in a context in which they have access to the Pyramid :term:`application registry` as well as the Pyramid rendering machinery. @@ -929,8 +929,9 @@ class Configurator(object): registry` represented by this Configurator. A tween factory must return a tween when it is called. - A tween accepts a :term:`request` object and returns a two-tuple - consisting of a :term:`request` object and a :term:`response` object. + A tween is a callable which accepts a :term:`request` object and + returns a two-tuple consisting of a :term:`request` object and a + :term:`response` object. Here's an example creating a tween factory and registering it: @@ -970,25 +971,33 @@ class Configurator(object): request handler as its ``handler`` argument, the second tween factory added will be called with the result of the first tween factory as its ``handler`` argument, and so on, ad infinitum. The Pyramid router - will use the outermost tween produced by this chain (the very last - tween added) as its request handler function. + will use the outermost tween produced by this chain (the tween + generated by the very last tween factory added) as its request + handler function. By default, the ordering of the chain is controlled entirely by the relative ordering of calls to ``add_tween``. However, the deploying user can override tween inclusion and ordering in his Pyramid configuration using the ``pyramid.tweens`` settings value. When - used, this settings value should be a list of Python dotted names - which imply the ordering (and inclusion) of tween factories in the - tween chain. + used, this settings value will be a list of Python dotted names which + imply the ordering (and inclusion) of tween factories in the tween + chain. + + Note that Pyramid's own exception view handling logic is implemented + as a tween factory: ``pyramid.router.excview_tween_factory``. If + Pyramid exception view handling is desired, and explicit tween + factories are specified via ``pyramid.tweens``, this function must be + added to the ``pyramid.tweens`` setting. If it is not present, + Pyramid will not perform exception view handling. Pyramid will prevent the same tween factory from being added to the tween chain more than once using configuration conflict detection. If you wish to add the same tween factory more than once in a configuration, you should either: a) use a tween factory that is an - *instance* rather than a function or class, or b) use a function or + instance rather than a function or class, b) use a function or class as a tween factory with the same logic as the other tween factory it conflicts with but with a different ``__name__`` - attribute. + attribute or c) call config.commit() between calls to ``add_tween``. A user can get a representation of both the implicit tween ordering (the ordering specified by calls to ``add_tween``) and the explicit -- cgit v1.2.3