promote http_cache to major feature

Chris McDonough

2011-07-14 c425a46b73a96c484de50dd9eea1595389f37b3d

promote http_cache to major feature

 docs/whatsnew-1.1.rst

@@ -29,6 +29,9 @@

- Default HTTP exception view.

- ``http_cache`` view configuration parameter causes Pyramid to set HTTP
  caching headers.

``request.response``
~~~~~~~~~~~~~~~~~~~~

@@ -91,6 +94,66 @@
  exception to that of Pyramid 1.0 (the exception will propagate to
  middleware and to the WSGI server).

``http_cache``
~~~~~~~~~~~~~~

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})``.

The environment setting ``PYRAMID_PREVENT_HTTP_CACHE`` and configuration
file value ``prevent_http_cache`` are synomymous and allow you to prevent
HTTP cache headers from being set by Pyramid's ``http_cache`` machinery
globally in a process.  see :ref:`influencing_http_caching` and
:ref:`preventing_http_caching`.

Minor Feature Additions
-----------------------

@@ -115,63 +178,6 @@
- New request property: ``json_body``. This property will return the
  JSON-decoded variant of the request body.  If the request body is not
  well-formed JSON, this property will raise an exception.

- 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})``.

  The environment setting ``PYRAMID_PREVENT_HTTP_CACHE`` and configuration
  file value ``prevent_http_cache`` are synomymous and allow you to prevent
  HTTP cache headers from being set by Pyramid's ``http_cache`` machinery
  globally in a process.  see :ref:`influencing_http_caching` and
  :ref:`preventing_http_caching`.

- A `JSONP <http://en.wikipedia.org/wiki/JSONP>`_ renderer.  See
  :ref:`jsonp_renderer` for more details.