- Deprecated all assignments to ``request.response_*`` attributes such as

  ``request.response_content_type = 'foo'``.  Assignments and mutations of
  the following request attributes that were considered by the framework for
  response influence are now deprecated: ``response_content_type``,
  ``response_headerlist``, ``response_status``, ``response_charset``, and
  ``response_cache_for``.  Instead of assigning these to the request object
  for detection by the rendering machinery, users should use the appropriate
  API of the Response object created by accessing ``request.response``
  (e.g. ``request.response_content_type = 'abc'`` ->
  ``request.response.content_type = 'abc'``).

- Custom request objects are now required to have a ``response`` attribute
  (or reified property) if they are meant to be used with renderers.  This
  ``response`` attribute should be an instance of the class
  ``pyramid.response.Response``.

- The JSON and string renderer factories now use
  ``request.response.content_type`` rather than
  ``request.response_content_type``.  They determine whether they should set
  the content type of the response by comparing the response's content type
  against the default (usually ``text/html``); if the content type is not the
  default, the renderer changes the content type (to ``application/json`` or
  ``text/plain`` for JSON and string renderers respectively).

- Made it possible to assign to and delete
  ``pyramid.testing.DummyRequest.registry`` (bugfix).

1 files changed, 41 insertions, 1 deletions

diff --git a/docs/api/request.rst b/docs/api/request.rst
index d17441c0a..80b41badb 100644
--- a/docs/api/request.rst
+++ b/docs/api/request.rst
@@ -85,6 +85,38 @@
      of ``request.exception`` will be ``None`` within response and
      finished callbacks.
 
+   .. attribute:: response
+
+     This attribute is actually a "reified" property which returns an
+     instance of the :class:`pyramid.response.Response` class.  The response
+     object returned does not exist until this attribute is accessed.  Once
+     it is accessed, subsequent accesses to this request object will return
+     the same :class:`~pyramid.response.Response` object.
+
+     The ``request.response`` API is used by renderers.  A render obtains the
+     response object it will return from a view that uses that renderer by
+     accessing ``request.response``.  Therefore, it's possible to use the
+     ``request.response`` API to set up a response object with "the right"
+     attributes (e.g. by calling ``request.response.set_cookie(...)`` or
+     ``request.response.content_type = 'text/plain'``, etc) within a view
+     that uses a renderer.  For example, within a view that uses a
+     :term:`renderer`:
+
+         response = request.response
+         response.set_cookie('mycookie', 'mine, all mine!')
+         return {'text':'Value that will be used by the renderer'}
+
+     Mutations to this response object will be preserved in the response sent
+     to the client after rendering.
+
+     Non-renderer code can also make use of request.response instead of
+     creating a response "by hand".  For example, in view code::
+
+        response = request.response
+        response.body = 'Hello!'
+        response.content_type = 'text/plain'
+        return response
+
    .. attribute:: session
 
      If a :term:`session factory` has been configured, this attribute
@@ -127,10 +159,18 @@
 
    .. attribute::  response_*
 
+      .. warning:: As of Pyramid 1.1, assignment to ``response_*`` attrs are
+         deprecated.  Assigning to one will cause a deprecation warning to be
+         emitted.  Instead of assigning ``response_*`` attributes to the
+         request, use the API of the :class:`pyramid.response.Response`
+         object exposed as ``request.response`` to influence response
+         behavior.
+
       You can set attributes on a :class:`pyramid.request.Request` which will
       influence the behavor of *rendered* responses (views which use a
       :term:`renderer` and which don't directly return a response).  These
       attributes begin with ``response_``, such as ``response_headerlist``. If
       you need to influence response values from a view that uses a renderer
       (such as the status code, a header, the content type, etc) see,
-      :ref:`response_request_attrs`.
+      :ref:`response_prefixed_attrs`.
+