From a7b1a933a263ee99426fda642c379d942f8f852b Mon Sep 17 00:00:00 2001
From: Chris McDonough <chrism@plope.com>
Date: Mon, 18 Apr 2011 17:07:38 -0400
Subject: - 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).
---
 docs/api/request.rst | 42 +++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 41 insertions(+), 1 deletion(-)

(limited to 'docs/api')

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`.
+
-- 
cgit v1.2.3