Merge branch 'wrapviews'

1 files changed, 44 insertions, 0 deletions

diff --git a/CHANGES.txt b/CHANGES.txt
index 57ab76e46..666b89b96 100644
--- a/CHANGES.txt
+++ b/CHANGES.txt
@@ -8,6 +8,50 @@ Features
   ``rendering_val``.  This can be used to introspect the value returned by a
   view in a BeforeRender subscriber.
 
+- New method: ``pyramid.request.Request.add_view_mapper``.  A view wrapper is
+  used to wrap the found view callable before it is called by Pyramid's
+  router.  This is a feature usually only used by framework extensions, to
+  provide, for example, view timing support.
+
+  A view wrapper factory must be a callable which accepts three arguments:
+  ``view_callable``, ``request``, and ``exc``.  It must return a view
+  callable.  The view callable returned by the factory must implement the
+  ``context, request`` view callable calling convention.  For example::
+
+       import time
+
+       def wrapper_factory(view_callable, request, exc):
+           def wrapper(context, request):
+               start = time.time()
+               result = view_callable(context, request)
+               end = time.time()
+               request.view_timing = end - start
+               return result
+           return wrapper
+
+   The ``view_callable`` argument to the factory will be the view callable
+   found by Pyramid via view lookup.  The ``request`` argument to the factory
+   will be the current request.  The ``exc`` argument to the factory will be
+   an Exception object if the found view is an exception view; it will be
+   ``None`` otherwise.
+
+   View wrappers only last for the duration of a single request.  You can add
+   such a factory for every request by using the
+   ``pyramid.events.NewRequest`` subscriber::
+
+       from pyramid.events import subscriber, NewRequest
+
+       @subscriber(NewRequest)
+       def newrequest(event):
+           event.request.add_view_wrapper(wrapper_factory)
+
+   If more than one view wrapper is registered during a single request,
+   a 'later' view wrapper factory will be called with the result of its
+   directly former view wrapper factory as its ``view_callable``
+   argument; this chain will be returned to Pyramid as a single view
+   callable.
+
+
 1.1 (2011-07-22)
 ================