add an example decorator showing a response being used unconditionally

2 files changed, 31 insertions, 0 deletions

diff --git a/docs/narr/viewconfig.rst b/docs/narr/viewconfig.rst
index d5203c6ba..fc5ae6dc6 100644
--- a/docs/narr/viewconfig.rst
+++ b/docs/narr/viewconfig.rst
@@ -234,6 +234,21 @@ Non-Predicate Arguments
     def myview(request):
       ...
 
+  All view callables in the decorator chain must return a response object
+  implementing :class:`pyramid.interfaces.IResponse` or raise an exception:
+
+  .. code-block:: python
+
+     def log_timer(wrapped):
+         def wrapper(context, request):
+             start = time.time()
+             response = wrapped(context, request)
+             duration = time.time() - start
+             response.headers['X-View-Time'] = '%.3f' % (duration,)
+             log.info('view took %.3f seconds', duration)
+             return response
+         return wrapper
+
 ``mapper``
   A Python object or :term:`dotted Python name` which refers to a :term:`view
   mapper`, or ``None``.  By default it is ``None``, which indicates that the
diff --git a/pyramid/config/views.py b/pyramid/config/views.py
index a522880c4..34fc49c00 100644
--- a/pyramid/config/views.py
+++ b/pyramid/config/views.py
@@ -848,6 +848,22 @@ class ViewsConfiguratorMixin(object):
           think about preserving function attributes such as ``__name__`` and
           ``__module__`` within decorator logic).
 
+          All view callables in the decorator chain must return a response
+          object implementing :class:`pyramid.interfaces.IResponse` or raise
+          an exception:
+
+          .. code-block:: python
+
+             def log_timer(wrapped):
+                 def wrapper(context, request):
+                     start = time.time()
+                     response = wrapped(context, request)
+                     duration = time.time() - start
+                     response.headers['X-View-Time'] = '%.3f' % (duration,)
+                     log.info('view took %.3f seconds', duration)
+                     return response
+                 return wrapper
+
           .. versionchanged:: 1.4a4
              Passing an iterable.