From b723792bfc43dc3d4446837c48d78c9258697e6d Mon Sep 17 00:00:00 2001
From: Chris McDonough <chrism@plope.com>
Date: Sat, 23 Jul 2011 19:57:34 -0400
Subject: - 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.
---
 docs/api/request.rst | 2 ++
 1 file changed, 2 insertions(+)

(limited to 'docs')

diff --git a/docs/api/request.rst b/docs/api/request.rst
index 404825d1b..58532bbd1 100644
--- a/docs/api/request.rst
+++ b/docs/api/request.rst
@@ -154,6 +154,8 @@
 
    .. automethod:: add_finished_callback
 
+   .. automethod:: add_view_wrapper
+
    .. automethod:: route_url
 
    .. automethod:: route_path
-- 
cgit v1.2.3