diff options
Diffstat (limited to 'docs/narr')
| -rw-r--r-- | docs/narr/renderers.rst | 74 | ||||
| -rw-r--r-- | docs/narr/templates.rst | 14 |
2 files changed, 54 insertions, 34 deletions
diff --git a/docs/narr/renderers.rst b/docs/narr/renderers.rst index 0b7cdb834..c3533648b 100644 --- a/docs/narr/renderers.rst +++ b/docs/narr/renderers.rst @@ -92,8 +92,8 @@ will be employed. return HTTPFound(location='http://example.com') # any renderer avoided Views which use a renderer can vary non-body response attributes (such as -headers and the HTTP status code) by attaching properties to the request. -See :ref:`response_request_attrs`. +headers and the HTTP status code) by attaching a property to the +``request.response`` attribute See :ref:`request_response_attr`. Additional renderers can be added by developers to the system as necessary (see :ref:`adding_and_overriding_renderers`). @@ -147,7 +147,8 @@ representing the ``str()`` serialization of the return value: {'content': 'Hello!'} Views which use the string renderer can vary non-body response attributes by -attaching properties to the request. See :ref:`response_request_attrs`. +using the API of the ``request.response`` attribute. See +:ref:`request_response_attr`. .. index:: pair: renderer; JSON @@ -199,7 +200,8 @@ You can configure a view to use the JSON renderer by naming ``json`` as the Views which use the JSON renderer can vary non-body response attributes by -attaching properties to the request. See :ref:`response_request_attrs`. +using the api of the ``request.response`` attribute. See +:ref:`request_response_attr`. .. index:: pair: renderer; chameleon @@ -269,8 +271,9 @@ Here's an example view configuration which uses a Chameleon text renderer: context='myproject.resources.Hello', renderer='myproject:templates/foo.txt') -Views which use a Chameleon renderer can vary response attributes by -attaching properties to the request. See :ref:`response_request_attrs`. +Views which use a Chameleon renderer can vary response attributes by using +the API of the ``request.response`` attribute. See +:ref:`request_response_attr`. .. index:: pair: renderer; mako @@ -333,7 +336,7 @@ additional :ref:`mako_template_renderer_settings`. single: response headers (from a renderer) single: renderer response headers -.. _response_request_attrs: +.. _request_response_attr: Varying Attributes of Rendered Responses ---------------------------------------- @@ -342,9 +345,43 @@ Before a response constructed by a :term:`renderer` is returned to :app:`Pyramid`, several attributes of the request are examined which have the potential to influence response behavior. -View callables that don't directly return a response should set these -attributes on the ``request`` object via ``setattr`` during their execution, -to influence associated response attributes. +View callables that don't directly return a response should use the API of +the :class:`pyramid.response.Response` attribute available as +``request.response`` during their execution, to influence associated response +behavior. + +For example, if you need to change the response status from within a view +callable that uses a renderer, assign the ``status`` attribute to the +``response`` attribute of the request before returning a result: + +.. code-block:: python + :linenos: + + from pyramid.view import view_config + + @view_config(name='gone', renderer='templates/gone.pt') + def myview(request): + request.response.status = '404 Not Found' + return {'URL':request.URL} + +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`. + +.. _response_prefixed_attrs: + +Deprecated Mechanism to Vary Attributes of Rendered Responses +------------------------------------------------------------- + +.. warning:: This section describes behavior deprecated in Pyramid 1.1. + +In previous releases of Pyramid (1.0 and before), the ``request.response`` +attribute did not exist. Instead, Pyramid required users to set special +``response_`` -prefixed attributes of the request to influence response +behavior. As of Pyramid 1.1, those request attributes are deprecated and +their use will cause a deprecation warning to be issued when used. Until +their existence is removed completely, we document them below, for benefit of +people with older code bases. ``response_content_type`` Defines the content-type of the resulting response, @@ -367,23 +404,6 @@ to influence associated response attributes. returning various values in the ``response_headerlist``, this is purely a convenience. -For example, if you need to change the response status from within a view -callable that uses a renderer, assign the ``response_status`` attribute to -the request before returning a result: - -.. code-block:: python - :linenos: - - from pyramid.view import view_config - - @view_config(name='gone', renderer='templates/gone.pt') - def myview(request): - request.response_status = '404 Not Found' - return {'URL':request.URL} - -For more information on attributes of the request, see the API -documentation in :ref:`request_module`. - .. index:: single: renderer (adding) diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst index 426ec229b..150b173e3 100644 --- a/docs/narr/templates.rst +++ b/docs/narr/templates.rst @@ -367,13 +367,13 @@ templates as renderers. See :ref:`available_template_system_bindings`. render a view without needing to fork your code to do so. See :ref:`extending_chapter` for more information. -By default, views rendered via a template renderer return a -:term:`Response` object which has a *status code* of ``200 OK``, and a -*content-type* of ``text/html``. To vary attributes of the response -of a view that uses a renderer, such as the content-type, headers, or -status attributes, you must set attributes on the *request* object -within the view before returning the dictionary. See -:ref:`response_request_attrs` for more information. +By default, views rendered via a template renderer return a :term:`Response` +object which has a *status code* of ``200 OK``, and a *content-type* of +``text/html``. To vary attributes of the response of a view that uses a +renderer, such as the content-type, headers, or status attributes, you must +use the API of the :class:`pyramid.response.Response` object exposed as +``request.response`` within the view before returning the dictionary. See +:ref:`request_response_attr` for more information. The same set of system values are provided to templates rendered via a renderer view configuration as those provided to templates rendered |