- A new value ``http_cache`` can be used as a 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})``.

1 files changed, 51 insertions, 0 deletions

diff --git a/docs/whatsnew-1.1.rst b/docs/whatsnew-1.1.rst
index d83582dee..783f2caaa 100644
--- a/docs/whatsnew-1.1.rst
+++ b/docs/whatsnew-1.1.rst
@@ -94,6 +94,57 @@ Default HTTP Exception View
 Minor Feature Additions
 -----------------------
 
+- 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.