merge httpexception-utils branch

1 files changed, 63 insertions, 12 deletions

diff --git a/docs/narr/renderers.rst b/docs/narr/renderers.rst
index b284fe73f..18cc8e539 100644
--- a/docs/narr/renderers.rst
+++ b/docs/narr/renderers.rst
@@ -72,30 +72,56 @@ When this configuration is added to an application, the
 which renders view return values to a :term:`JSON` response serialization.
 
 Other built-in renderers include renderers which use the :term:`Chameleon`
-templating language to render a dictionary to a response.
+templating language to render a dictionary to a response.  Additional
+renderers can be added by developers to the system as necessary (see
+:ref:`adding_and_overriding_renderers`).
+
+Views which use a renderer and return a non-Response value can vary non-body
+response attributes (such as headers and the HTTP status code) by attaching a
+property to the ``request.response`` attribute See
+:ref:`request_response_attr`.
 
 If the :term:`view callable` associated with a :term:`view configuration`
-returns a Response object directly (an object with the attributes ``status``,
-``headerlist`` and ``app_iter``), any renderer associated with the view
+returns a Response object directly, any renderer associated with the view
 configuration is ignored, and the response is passed back to :app:`Pyramid`
 unchanged.  For example, if your view callable returns an instance of the
-:class:`pyramid.httpexceptions.HTTPFound` class as a response, no renderer
+:class:`pyramid.response.Response` class as a response, no renderer
 will be employed.
 
 .. code-block:: python
    :linenos:
 
-   from pyramid.httpexceptions import HTTPFound
+   from pyramid.response import Response
+   from pyramid.view import view_config
+
+   @view_config(renderer='json')
+   def view(request):
+       return Response('OK') # json renderer avoided
+
+Likewise for an :term:`HTTP exception` response:
+
+.. code-block:: python
+   :linenos:
+
+   from pyramid.httpexceptions import HTTPNotFound
+   from pyramid.view import view_config
 
+   @view_config(renderer='json')
    def view(request):
-       return HTTPFound(location='http://example.com') # any renderer avoided
+       return HTTPFound(location='http://example.com') # json renderer avoided
 
-Views which use a renderer can vary non-body response attributes (such as
-headers and the HTTP status code) by attaching a property to the
-``request.response`` attribute See :ref:`request_response_attr`.
+You can of course also return the ``request.response`` attribute instead to
+avoid rendering:
 
-Additional renderers can be added by developers to the system as necessary
-(see :ref:`adding_and_overriding_renderers`).
+.. code-block:: python
+   :linenos:
+
+   from pyramid.view import view_config
+
+   @view_config(renderer='json')
+   def view(request):
+       request.response.body = 'OK'
+       return request.response # json renderer avoided
 
 .. index::
    single: renderers (built-in)
@@ -363,9 +389,34 @@ callable that uses a renderer, assign the ``status`` attribute to the
        request.response.status = '404 Not Found'
        return {'URL':request.URL}
 
+Note that mutations of ``request.response`` in views which return a Response
+object directly will have no effect unless the response object returned *is*
+``request.response``.  For example, the following example calls
+``request.response.set_cookie``, but this call will have no effect, because a
+different Response object is returned.
+
+.. code-block:: python
+   :linenos:
+
+   from pyramid.response import Response
+
+   def view(request):
+       request.response.set_cookie('abc', '123') # this has no effect
+       return Response('OK') # because we're returning a different response
+
+If you mutate ``request.response`` and you'd like the mutations to have an
+effect, you must return ``request.response``:
+
+.. code-block:: python
+   :linenos:
+
+   def view(request):
+       request.response.set_cookie('abc', '123')
+       return request.response
+
 For more information on attributes of the request, see the API documentation
 in :ref:`request_module`.  For more information on the API of
-``request.response``, see :class:`pyramid.response.Response`.
+``request.response``, see :attr:`pyramid.request.Request.response`.
 
 .. _response_prefixed_attrs: