diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/api/request.rst | 7 | ||||
| -rw-r--r-- | docs/narr/hooks.rst | 86 | ||||
| -rw-r--r-- | docs/narr/viewconfig.rst | 54 | ||||
| -rw-r--r-- | docs/tutorials/wiki/background.rst | 2 | ||||
| -rw-r--r-- | docs/tutorials/wiki2/background.rst | 2 | ||||
| -rw-r--r-- | docs/whatsnew-1.1.rst | 56 |
6 files changed, 161 insertions, 46 deletions
diff --git a/docs/api/request.rst b/docs/api/request.rst index 27ce395ac..5dfb2ae9a 100644 --- a/docs/api/request.rst +++ b/docs/api/request.rst @@ -180,6 +180,13 @@ object (exposed to view code as ``request.response``) to influence rendered response behavior. + .. attribute:: json + + If the request's ``content_type`` is ``application/json``, this + attribute will contain the JSON-decoded variant of the request body. + If the request's ``content_type`` is not ``application/json``, this + attribute will be ``None``. + .. note:: For information about the API of a :term:`multidict` structure (such as diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst index 56c566a4c..94701c9f9 100644 --- a/docs/narr/hooks.rst +++ b/docs/narr/hooks.rst @@ -176,12 +176,54 @@ already constructed a :term:`configurator` it can also be registered via the config.set_request_factory(MyRequest) .. index:: + single: before render event + single: adding renderer globals + +.. _beforerender_event: + +Using The Before Render Event +----------------------------- + +Subscribers to the :class:`pyramid.events.BeforeRender` event may introspect +and modify the set of :term:`renderer globals` before they are passed to a +:term:`renderer`. This event object iself has a dictionary-like interface +that can be used for this purpose. For example: + +.. code-block:: python + :linenos: + + from pyramid.events import subscriber + from pyramid.events import BeforeRender + + @subscriber(BeforeRender) + def add_global(event): + event['mykey'] = 'foo' + +An object of this type is sent as an event just before a :term:`renderer` is +invoked (but *after* the application-level renderer globals factory added via +:class:`~pyramid.config.Configurator.set_renderer_globals_factory`, if any, +has injected its own keys into the renderer globals dictionary). + +If a subscriber attempts to add a key that already exist in the renderer +globals dictionary, a :exc:`KeyError` is raised. This limitation is enforced +because event subscribers do not possess any relative ordering. The set of +keys added to the renderer globals dictionary by all +:class:`pyramid.events.BeforeRender` subscribers and renderer globals +factories must be unique. + +See the API documentation for the :class:`~pyramid.events.BeforeRender` event +interface at :class:`pyramid.interfaces.IBeforeRender`. + +Another (deprecated) mechanism which allows event subscribers more control +when adding renderer global values exists in :ref:`adding_renderer_globals`. + +.. index:: single: renderer globals .. _adding_renderer_globals: -Adding Renderer Globals ------------------------ +Adding Renderer Globals (Deprecated) +------------------------------------ .. warning:: this feature is deprecated as of Pyramid 1.1. A non-deprecated mechanism which allows event subscribers to add renderer global values @@ -231,46 +273,6 @@ already constructed a :term:`configurator` it can also be registered via the config = Configurator() config.set_renderer_globals_factory(renderer_globals_factory) -.. index:: - single: before render event - -.. _beforerender_event: - -Using The Before Render Event ------------------------------ - -Subscribers to the :class:`pyramid.events.BeforeRender` event may introspect -and modify the set of :term:`renderer globals` before they are passed to a -:term:`renderer`. This event object iself has a dictionary-like interface -that can be used for this purpose. For example: - -.. code-block:: python - :linenos: - - from pyramid.events import subscriber - from pyramid.events import BeforeRender - - @subscriber(BeforeRender) - def add_global(event): - event['mykey'] = 'foo' - -An object of this type is sent as an event just before a :term:`renderer` is -invoked (but *after* the application-level renderer globals factory added via -:class:`~pyramid.config.Configurator.set_renderer_globals_factory`, if any, -has injected its own keys into the renderer globals dictionary). - -If a subscriber attempts to add a key that already exist in the renderer -globals dictionary, a :exc:`KeyError` is raised. This limitation is enforced -because event subscribers do not possess any relative ordering. The set of -keys added to the renderer globals dictionary by all -:class:`pyramid.events.BeforeRender` subscribers and renderer globals -factories must be unique. - -See the API documentation for the :class:`~pyramid.events.BeforeRender` event -interface at :class:`pyramid.interfaces.IBeforeRender`. - -Another mechanism which allows event subscribers more control when adding -renderer global values exists in :ref:`adding_renderer_globals`. .. index:: single: response callback diff --git a/docs/narr/viewconfig.rst b/docs/narr/viewconfig.rst index 5640800a2..ec42446ff 100644 --- a/docs/narr/viewconfig.rst +++ b/docs/narr/viewconfig.rst @@ -160,6 +160,55 @@ Non-Predicate Arguments view callable itself returns a :term:`response` (see :ref:`the_response`), the specified renderer implementation is never called. +``http_cache`` + When you supply an ``http_cache`` value to a view configuration, the + ``Expires`` and ``Cache-Control`` headers of a response generated by the + associated view callable are modified. The value for ``http_cache`` may be + one of the following: + + - A nonzero integer. If it's a nonzero integer, it's treated as a number + of seconds. This number of seconds will be used to compute the + ``Expires`` header and the ``Cache-Control: max-age`` parameter of + responses to requests which call this view. For example: + ``http_cache=3600`` instructs the requesting browser to 'cache this + response for an hour, please'. + + - A ``datetime.timedelta`` instance. If it's a ``datetime.timedelta`` + instance, it will be converted into a number of seconds, and that number + of seconds will be used to compute the ``Expires`` header and the + ``Cache-Control: max-age`` parameter of responses to requests which call + this view. For example: ``http_cache=datetime.timedelta(days=1)`` + instructs the requesting browser to 'cache this response for a day, + please'. + + - Zero (``0``). If the value is zero, the ``Cache-Control`` and + ``Expires`` headers present in all responses from this view will be + composed such that client browser cache (and any intermediate caches) are + instructed to never cache the response. + + - A two-tuple. If it's a two tuple (e.g. ``http_cache=(1, + {'public':True})``), the first value in the tuple may be a nonzero + integer or a ``datetime.timedelta`` instance; in either case this value + will be used as the number of seconds to cache the response. The second + value in the tuple must be a dictionary. The values present in the + dictionary will be used as input to the ``Cache-Control`` response + header. For example: ``http_cache=(3600, {'public':True})`` means 'cache + for an hour, and add ``public`` to the Cache-Control header of the + response'. All keys and values supported by the + ``webob.cachecontrol.CacheControl`` interface may be added to the + dictionary. Supplying ``{'public':True}`` is equivalent to calling + ``response.cache_control.public = True``. + + Providing a non-tuple value as ``http_cache`` is equivalent to calling + ``response.cache_expires(value)`` within your view's body. + + Providing a two-tuple value as ``http_cache`` is equivalent to calling + ``response.cache_expires(value[0], **value[1])`` within your view's body. + + If you wish to avoid influencing, the ``Expires`` header, and instead wish + to only influence ``Cache-Control`` headers, pass a tuple as ``http_cache`` + with the first element of ``None``, e.g.: ``(None, {'public':True})``. + ``wrapper`` The :term:`view name` of a different :term:`view configuration` which will receive the response body of this view as the ``request.wrapped_body`` @@ -400,8 +449,9 @@ configuration stanza: .. code-block:: python :linenos: - config.add_view('mypackage.views.my_view', name='my_view', request_method='POST', - context=MyResource, permission='read') + config.add_view('mypackage.views.my_view', name='my_view', + request_method='POST', context=MyResource, + permission='read') All arguments to ``view_config`` may be omitted. For example: diff --git a/docs/tutorials/wiki/background.rst b/docs/tutorials/wiki/background.rst index e49407b70..eda2fe825 100644 --- a/docs/tutorials/wiki/background.rst +++ b/docs/tutorials/wiki/background.rst @@ -11,7 +11,7 @@ Python web framework experience. To code along with this tutorial, the developer will need a UNIX machine with development tools (Mac OS X with XCode, any Linux or BSD -variant, etc) *or* he will need a Windows system of any kind. +variant, etc) *or* a Windows system of any kind. This tutorial targets :app:`Pyramid` version 1.0. diff --git a/docs/tutorials/wiki2/background.rst b/docs/tutorials/wiki2/background.rst index 880b5b219..79b39914b 100644 --- a/docs/tutorials/wiki2/background.rst +++ b/docs/tutorials/wiki2/background.rst @@ -10,7 +10,7 @@ people without any prior Python web framework experience. To code along with this tutorial, the developer will need a UNIX machine with development tools (Mac OS X with XCode, any Linux or BSD -variant, etc) *or* he will need a Windows system of any kind. +variant, etc) *or* a Windows system of any kind. This tutorial is targeted at :app:`Pyramid` version 1.0. diff --git a/docs/whatsnew-1.1.rst b/docs/whatsnew-1.1.rst index d83582dee..fdf3b1c74 100644 --- a/docs/whatsnew-1.1.rst +++ b/docs/whatsnew-1.1.rst @@ -94,6 +94,62 @@ Default HTTP Exception View Minor Feature Additions ----------------------- +- New request attribute: ``json``. If the request's ``content_type`` is + ``application/json``, this attribute will contain the JSON-decoded + variant of the request body. If the request's ``content_type`` is not + ``application/json``, this attribute will be ``None``. + +- A new value ``http_cache`` can be used as a :term:`view configuration` + parameter. + + When you supply an ``http_cache`` value to a view configuration, the + ``Expires`` and ``Cache-Control`` headers of a response generated by the + associated view callable are modified. The value for ``http_cache`` may be + one of the following: + + - A nonzero integer. If it's a nonzero integer, it's treated as a number + of seconds. This number of seconds will be used to compute the + ``Expires`` header and the ``Cache-Control: max-age`` parameter of + responses to requests which call this view. For example: + ``http_cache=3600`` instructs the requesting browser to 'cache this + response for an hour, please'. + + - A ``datetime.timedelta`` instance. If it's a ``datetime.timedelta`` + instance, it will be converted into a number of seconds, and that number + of seconds will be used to compute the ``Expires`` header and the + ``Cache-Control: max-age`` parameter of responses to requests which call + this view. For example: ``http_cache=datetime.timedelta(days=1)`` + instructs the requesting browser to 'cache this response for a day, + please'. + + - Zero (``0``). If the value is zero, the ``Cache-Control`` and + ``Expires`` headers present in all responses from this view will be + composed such that client browser cache (and any intermediate caches) are + instructed to never cache the response. + + - A two-tuple. If it's a two tuple (e.g. ``http_cache=(1, + {'public':True})``), the first value in the tuple may be a nonzero + integer or a ``datetime.timedelta`` instance; in either case this value + will be used as the number of seconds to cache the response. The second + value in the tuple must be a dictionary. The values present in the + dictionary will be used as input to the ``Cache-Control`` response + header. For example: ``http_cache=(3600, {'public':True})`` means 'cache + for an hour, and add ``public`` to the Cache-Control header of the + response'. All keys and values supported by the + ``webob.cachecontrol.CacheControl`` interface may be added to the + dictionary. Supplying ``{'public':True}`` is equivalent to calling + ``response.cache_control.public = True``. + + Providing a non-tuple value as ``http_cache`` is equivalent to calling + ``response.cache_expires(value)`` within your view's body. + + Providing a two-tuple value as ``http_cache`` is equivalent to calling + ``response.cache_expires(value[0], **value[1])`` within your view's body. + + If you wish to avoid influencing, the ``Expires`` header, and instead wish + to only influence ``Cache-Control`` headers, pass a tuple as ``http_cache`` + with the first element of ``None``, e.g.: ``(None, {'public':True})``. + - A `JSONP <http://en.wikipedia.org/wiki/JSONP>`_ renderer. See :ref:`jsonp_renderer` for more details. |