promote http_cache to major feature

1 files changed, 63 insertions, 57 deletions

diff --git a/docs/whatsnew-1.1.rst b/docs/whatsnew-1.1.rst
index 845170831..388c40f46 100644
--- a/docs/whatsnew-1.1.rst
+++ b/docs/whatsnew-1.1.rst
@@ -29,6 +29,9 @@ The major feature additions in Pyramid 1.1 are:
 
 - Default HTTP exception view.
 
+- ``http_cache`` view configuration parameter causes Pyramid to set HTTP
+  caching headers.
+
 ``request.response``
 ~~~~~~~~~~~~~~~~~~~~
 
@@ -91,6 +94,66 @@ Default HTTP Exception View
   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
 -----------------------
 
@@ -116,63 +179,6 @@ Minor Feature Additions
   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.