From a8eb53fb79981e1b6fb93af3c80a6bdbae7f9d8f Mon Sep 17 00:00:00 2001
From: Chris Rossi <chris@archimedeanco.com>
Date: Mon, 14 Jul 2014 11:13:28 -0400
Subject: Narrative scifi.

---
 docs/narr/assets.rst | 65 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 65 insertions(+)

diff --git a/docs/narr/assets.rst b/docs/narr/assets.rst
index b0a8d18b0..a2976de22 100644
--- a/docs/narr/assets.rst
+++ b/docs/narr/assets.rst
@@ -286,6 +286,71 @@ the application is being run in development or in production (use a different
 suggestion for a pattern; any setting name other than ``media_location``
 could be used.
 
+.. _cache_busting:
+
+Cache Busting
+-------------
+
+In order to maximize performance of a web application, you generally want to 
+limit the number of times a particular client requests the same static asset.
+Ideally a client would cache a particular static asset "forever", requiring 
+it to be sent to the client a single time.  The HTTP protocol allows you to 
+send headers with an HTTP response that can instruct a client to cache a 
+particular asset for an amount of time.  As long as the client has a copy of 
+the asset in its cache and that cache hasn't expired, the client will use the
+cached copy rather than request a new copy from the server.  The drawback to 
+sending cache headers to the client for a static asset is that at some point
+the static asset may change, and then you'll want the client to load a new copy
+of the asset.  Under normal circumstances you'd just need to wait for the 
+client's cached copy to expire before they get the new version of the static 
+resource.
+
+A commonly used workaround to this problem is a technique known as "cache 
+busting".  Cache busting schemes generally involve generating a URL for a 
+static asset that changes when the static asset changes.  This way headers can
+be sent along with the static asset instructing the client to cache the asset
+for a very long time.  When a static asset is changed, the URL used to refer to
+it in a web page also changes, so the client sees it as a new resource and 
+requests a copy, regardless of any caching policy set for the resource's old 
+URL.
+
+:app:`Pyramid` can be configured to produce cache busting URLs for static 
+assets by passing the optional argument, `cache_bust` to 
+:meth:`~pyramid.config.Configurator.add_static_view`:
+
+.. code-block:: python
+   :linenos:
+
+   # config is an instance of pyramid.config.Configurator
+   config.add_static_view(name='static', path='mypackage:folder/static',
+                           cache_bust='md5')
+
+Supplying the `cache_bust` argument instructs :app:`Pyramid` to add a query
+string to URLs generated for this static view which includes the md5 checksum
+of the static file being served:
+
+.. code-block:: python
+   :linenos:
+
+   js_url = request.static_url('mypackage:folder/static/js/myapp.js')
+   # Returns: 'http://www.example.com/static/js/myapp.js?md5=c9658b3c0a314a1ca21e5988e662a09e`
+
+When the asset changes, so will its md5 checksum, and therefore so will its
+URL.  Supplying the `cache_bust` argument also causes the static view to set
+headers instructing clients to cache the asset for ten years, unless the
+`max_cache_age` argument is also passed, in which case that value is used.
+
+.. note::
+
+   `md5` is currently the only possible value for the `cache_bust` argument to
+   :meth:`~pyramid.config.Configurator.add_static_view`.
+
+.. note:: 
+
+   md5 checksums are cached in RAM so if you change a static resource without
+   restarting your application, you may still generate URLs with a stale md5
+   checksum. 
+
 .. index::
    single: static assets view
 
-- 
cgit v1.2.3


From b648516a5dd61b3ce155586465f473338c230bf9 Mon Sep 17 00:00:00 2001
From: Chris Rossi <chris@archimedeanco.com>
Date: Mon, 14 Jul 2014 11:25:33 -0400
Subject: API docs scifi.

---
 pyramid/config/views.py | 38 +++++++++++++++++++++++---------------
 1 file changed, 23 insertions(+), 15 deletions(-)

diff --git a/pyramid/config/views.py b/pyramid/config/views.py
index 7a6157ec8..d938a7632 100644
--- a/pyramid/config/views.py
+++ b/pyramid/config/views.py
@@ -302,7 +302,7 @@ class ViewDeriver(object):
                     raise PredicateMismatch(
                          'predicate mismatch for view %s (%s)' % (
                          view_name, predicate.text()))
-            return view(context, request)        
+            return view(context, request)
         def checker(context, request):
             return all((predicate(context, request) for predicate in
                         preds))
@@ -894,8 +894,8 @@ class ViewsConfiguratorMixin(object):
 
         request_param
 
-          This value can be any string or any sequence of strings.  A view 
-          declaration with this argument ensures that the view will only be 
+          This value can be any string or any sequence of strings.  A view
+          declaration with this argument ensures that the view will only be
           called when the :term:`request` has a key in the ``request.params``
           dictionary (an HTTP ``GET`` or ``POST`` variable) that has a
           name which matches the supplied value (if the value is a string)
@@ -1001,7 +1001,7 @@ class ViewsConfiguratorMixin(object):
 
           Note that using this feature requires a :term:`session factory` to
           have been configured.
-         
+
           .. versionadded:: 1.4a2
 
         physical_path
@@ -1039,7 +1039,7 @@ class ViewsConfiguratorMixin(object):
                 This value should be a sequence of references to custom
                 predicate callables.  Use custom predicates when no set of
                 predefined predicates do what you need.  Custom predicates
-                can be combined with predefined predicates as necessary. 
+                can be combined with predefined predicates as necessary.
                 Each custom predicate callable should accept two arguments:
                 ``context`` and ``request`` and should return either
                 ``True`` or ``False`` after doing arbitrary evaluation of
@@ -1074,7 +1074,7 @@ class ViewsConfiguratorMixin(object):
                 DeprecationWarning,
                 stacklevel=4
                 )
-        
+
         view = self.maybe_dotted(view)
         context = self.maybe_dotted(context)
         for_ = self.maybe_dotted(for_)
@@ -1160,7 +1160,7 @@ class ViewsConfiguratorMixin(object):
             view_desc = self.object_description(view)
 
         tmpl_intr = None
-            
+
         view_intr = self.introspectable('views',
                                         discriminator,
                                         view_desc,
@@ -1569,7 +1569,7 @@ class ViewsConfiguratorMixin(object):
         wrapper=None,
         route_name=None,
         request_type=None,
-        request_method=None, 
+        request_method=None,
         request_param=None,
         containment=None,
         xhr=None,
@@ -1612,7 +1612,7 @@ class ViewsConfiguratorMixin(object):
                     '%s may not be used as an argument to add_forbidden_view'
                     % arg
                     )
-        
+
         settings = dict(
             view=view,
             context=HTTPForbidden,
@@ -1623,7 +1623,7 @@ class ViewsConfiguratorMixin(object):
             containment=containment,
             xhr=xhr,
             accept=accept,
-            header=header, 
+            header=header,
             path_info=path_info,
             custom_predicates=custom_predicates,
             decorator=decorator,
@@ -1638,7 +1638,7 @@ class ViewsConfiguratorMixin(object):
         return self.add_view(**settings)
 
     set_forbidden_view = add_forbidden_view # deprecated sorta-bw-compat alias
-    
+
     @viewdefaults
     @action_method
     def add_notfound_view(
@@ -1649,7 +1649,7 @@ class ViewsConfiguratorMixin(object):
         wrapper=None,
         route_name=None,
         request_type=None,
-        request_method=None, 
+        request_method=None,
         request_param=None,
         containment=None,
         xhr=None,
@@ -1700,7 +1700,7 @@ class ViewsConfiguratorMixin(object):
                     '%s may not be used as an argument to add_notfound_view'
                     % arg
                     )
-                    
+
         settings = dict(
             view=view,
             context=HTTPNotFound,
@@ -1711,7 +1711,7 @@ class ViewsConfiguratorMixin(object):
             containment=containment,
             xhr=xhr,
             accept=accept,
-            header=header, 
+            header=header,
             path_info=path_info,
             custom_predicates=custom_predicates,
             decorator=decorator,
@@ -1786,7 +1786,15 @@ class ViewsConfiguratorMixin(object):
         ``Expires`` and ``Cache-Control`` headers for static assets served.
         Note that this argument has no effect when the ``name`` is a *url
         prefix*.  By default, this argument is ``None``, meaning that no
-        particular Expires or Cache-Control headers are set in the response.
+        particular Expires or Cache-Control headers are set in the response,
+        unless ``cache_bust`` is specified.
+
+        The ``cache_bust`` keyword argument may be set to ``"md5"`` to cause
+        :meth:`~pyramid.request.Request.static_url` to generate URLs with an
+        additional query string which includes the md5 checksum for the static
+        asset.  This argument modifies the default for ``cache_max_age``,
+        making it ten years.  ``cache_max_age`` may still be explicitly
+        provided to override this default.
 
         The ``permission`` keyword argument is used to specify the
         :term:`permission` required by a user to execute the static view.  By
-- 
cgit v1.2.3


From 0445bf2ac9c4cb7862464f1ce8f42c640c11ea7d Mon Sep 17 00:00:00 2001
From: Chris Rossi <chris@archimedeanco.com>
Date: Mon, 14 Jul 2014 15:59:05 -0400
Subject: Try this impl on and see how it feels.

---
 pyramid/cachebust.py    | 34 +++++++++++++++++++++++++++++
 pyramid/config/views.py | 19 ++++++++++++++---
 pyramid/interfaces.py   | 57 +++++++++++++++++++++++++++++++++++++++++++------
 pyramid/static.py       |  7 +++---
 4 files changed, 104 insertions(+), 13 deletions(-)
 create mode 100644 pyramid/cachebust.py

diff --git a/pyramid/cachebust.py b/pyramid/cachebust.py
new file mode 100644
index 000000000..69c7eb1d2
--- /dev/null
+++ b/pyramid/cachebust.py
@@ -0,0 +1,34 @@
+import hashlib
+import pkg_resources
+
+from zope.interface import implementer
+
+from .interfaces import ICacheBuster
+
+from pyramid.asset import resolve_asset_spec
+
+
+def generate_md5(spec):
+    package, filename = resolve_asset_spec(spec)
+    md5 = hashlib.md5()
+    with pkg_resources.resource_stream(package, filename) as stream:
+        for block in iter(lambda: stream.read(4096), ''):
+            md5.update(block)
+    return md5.hexdigest()
+
+
+@implementer(ICacheBuster)
+class DefaultCacheBuster(object):
+
+    def generate_token(self, request, pathspec):
+        token_cache = request.registry.setdefault('md5-token-cache', {})
+        token = token_cache.get(pathspec)
+        if not token:
+            token_cache[pathspec] = token = generate_md5(pathspec)
+        return token
+
+    def pregenerate_url(self, request, token, subpath, kw):
+        return token + '/' + subpath, kw
+
+    def match_url(self, request, path_elements):
+        return path_elements[1:]
diff --git a/pyramid/config/views.py b/pyramid/config/views.py
index d938a7632..78c415b14 100644
--- a/pyramid/config/views.py
+++ b/pyramid/config/views.py
@@ -34,6 +34,7 @@ from pyramid.interfaces import (
     )
 
 from pyramid import renderers
+from pyramid.cachebust import DefaultCacheBuster
 
 from pyramid.compat import (
     string_types,
@@ -1905,11 +1906,16 @@ class StaticURLInfo(object):
             registry = request.registry
         except AttributeError: # bw compat (for tests)
             registry = get_current_registry()
-        for (url, spec, route_name) in self._get_registrations(registry):
+        registrations = self._get_registrations(registry)
+        for (url, spec, route_name, cachebust) in registrations:
             if path.startswith(spec):
                 subpath = path[len(spec):]
                 if WIN: # pragma: no cover
                     subpath = subpath.replace('\\', '/') # windows
+                if cachebust:
+                    token = cachebust.generate_token(request, spec + subpath)
+                    subpath, kw = cachebust.pregenerate_url(
+                        request, token, subpath, kw)
                 if url is None:
                     kw['subpath'] = subpath
                     return request.route_url(route_name, **kw)
@@ -1949,6 +1955,10 @@ class StaticURLInfo(object):
             # make sure it ends with a slash
             name = name + '/'
 
+        cachebust = extra.pop('cachebust', None)
+        if cachebust is True:
+            cachebust = DefaultCacheBuster()
+
         if url_parse(name).netloc:
             # it's a URL
             # url, spec, route_name
@@ -1958,9 +1968,12 @@ class StaticURLInfo(object):
             # it's a view name
             url = None
             cache_max_age = extra.pop('cache_max_age', None)
+            if cache_max_age is None and cachebust:
+                cache_max_age = 10 * 365 * 24 * 60 * 60  # Ten(ish) years
+
             # create a view
             view = static_view(spec, cache_max_age=cache_max_age,
-                               use_subpath=True)
+                               use_subpath=True, cachebust=cachebust)
 
             # Mutate extra to allow factory, etc to be passed through here.
             # Treat permission specially because we'd like to default to
@@ -2001,7 +2014,7 @@ class StaticURLInfo(object):
                 registrations.pop(idx)
 
             # url, spec, route_name
-            registrations.append((url, spec, route_name))
+            registrations.append((url, spec, route_name, cachebust))
 
         intr = config.introspectable('static views',
                                      name,
diff --git a/pyramid/interfaces.py b/pyramid/interfaces.py
index aa2dbdafd..e60898dbc 100644
--- a/pyramid/interfaces.py
+++ b/pyramid/interfaces.py
@@ -708,7 +708,7 @@ class IRoute(Interface):
     pregenerator = Attribute('This attribute should either be ``None`` or '
                              'a callable object implementing the '
                              '``IRoutePregenerator`` interface')
-        
+
     def match(path):
         """
         If the ``path`` passed to this function can be matched by the
@@ -803,7 +803,7 @@ class IContextURL(IResourceURL):
     # <__main__.Fudge object at 0x1cda890>
     # <object object at 0x7fa678f3e2a0> <object object at 0x7fa678f3e2a0>
     # <__main__.Another object at 0x1cda850>
-    
+
     def virtual_root():
         """ Return the virtual root related to a request and the
         current context"""
@@ -837,9 +837,9 @@ class IPEP302Loader(Interface):
 
     def get_code(fullname):
         """ Return the code object for the module identified by 'fullname'.
-        
+
         Return 'None' if it's a built-in or extension module.
-        
+
         If the loader doesn't have the code object but it does have the source
         code, return the compiled source code.
 
@@ -848,16 +848,16 @@ class IPEP302Loader(Interface):
 
     def get_source(fullname):
         """ Return the source code for the module identified by 'fullname'.
-        
+
         Return a string, using newline characters for line endings, or None
         if the source is not available.
-            
+
         Raise ImportError if the module can't be found by the importer at all.
         """
 
     def get_filename(fullname):
         """ Return the value of '__file__' if the named module was loaded.
-        
+
         If the module is not found, raise ImportError.
         """
 
@@ -1164,6 +1164,49 @@ class IJSONAdapter(Interface):
 class IPredicateList(Interface):
     """ Interface representing a predicate list """
 
+class ICacheBuster(Interface):
+    """
+    An instance of a class which implements this interface may be passed as the
+    ``cachebust`` argument to
+    :meth:`pyramid.config.Configurator.add_static_view` to add cache busting
+    capability to a static view.
+    """
+    def generate_token(request, pathspec):
+        """
+        Return a token string for a static asset to be used to rewrite a
+        static asset URL for cache busting.
+
+        The ``pathspec`` argument is the path specification for the asset we're
+        generating a token for.
+        """
+
+    def pregenerate_url(request, token, subpath, kw):
+        """
+        Modifies the elements and/or keywords used to generate the URL for a
+        given static asset.
+
+        The ``token`` argument is the result of calling
+        :meth:`~pyramid.interfaces.ICacheBuster.generate_token` for a static
+        asset.
+
+        The ``subpath`` argument is the subpath in the static asset URL that
+        would normally be generated without cache busting.  The ``kw``
+        argument is the keywords dict that would be passed to
+        :meth:`~pyramid.request.Request.route_url`.
+        The return value should be a two-tuple of elements ``(subpath, kw)``
+        which are modified from the incoming arguments.
+        """
+
+    def match_url(request, path_elements):
+        """
+        Undo any modification to the subpath which may have been done by
+        :meth:`~pyramid.interfaces.ICacheBuster.pregenerate_url`.  The
+        ``path_elements`` argument is a tuple of path elements that represent
+        the subpath of the asset request URL.  The return value should be
+        a modified (or not) version of ``path_elements``, which will be used
+        ultimately to find the asset.
+        """
+
 # configuration phases: a lower phase number means the actions associated
 # with this phase will be executed earlier than those with later phase
 # numbers.  The default phase number is 0, FTR.
diff --git a/pyramid/static.py b/pyramid/static.py
index aa67568d3..be191971a 100644
--- a/pyramid/static.py
+++ b/pyramid/static.py
@@ -78,7 +78,7 @@ class static_view(object):
     """
 
     def __init__(self, root_dir, cache_max_age=3600, package_name=None,
-                 use_subpath=False, index='index.html'):
+                 use_subpath=False, index='index.html', cachebust=None):
         # package_name is for bw compat; it is preferred to pass in a
         # package-relative path as root_dir
         # (e.g. ``anotherpackage:foo/static``).
@@ -91,13 +91,15 @@ class static_view(object):
         self.docroot = docroot
         self.norm_docroot = normcase(normpath(docroot))
         self.index = index
+        self.cachebust = cachebust
 
     def __call__(self, context, request):
         if self.use_subpath:
             path_tuple = request.subpath
         else:
             path_tuple = traversal_path_info(request.environ['PATH_INFO'])
-
+        if self.cachebust:
+            path_tuple = self.cachebust.match_url(request, path_tuple)
         path = _secure_path(path_tuple)
 
         if path is None:
@@ -153,4 +155,3 @@ def _secure_path(path_tuple):
         return None
     encoded = slash.join(path_tuple) # will be unicode
     return encoded
-
-- 
cgit v1.2.3


From 9d521efce433af574382c86a7397f1ac53a73804 Mon Sep 17 00:00:00 2001
From: Chris Rossi <chris@archimedeanco.com>
Date: Tue, 15 Jul 2014 09:56:28 -0400
Subject: Try something a little more decoupled and consistent.

---
 pyramid/cachebust.py    | 34 ---------------------
 pyramid/config/views.py | 79 ++++++++++++++++++++++++++++++++++++++-----------
 pyramid/interfaces.py   | 79 ++++++++++++++++++++++++++++---------------------
 pyramid/static.py       |  8 ++---
 4 files changed, 112 insertions(+), 88 deletions(-)
 delete mode 100644 pyramid/cachebust.py

diff --git a/pyramid/cachebust.py b/pyramid/cachebust.py
deleted file mode 100644
index 69c7eb1d2..000000000
--- a/pyramid/cachebust.py
+++ /dev/null
@@ -1,34 +0,0 @@
-import hashlib
-import pkg_resources
-
-from zope.interface import implementer
-
-from .interfaces import ICacheBuster
-
-from pyramid.asset import resolve_asset_spec
-
-
-def generate_md5(spec):
-    package, filename = resolve_asset_spec(spec)
-    md5 = hashlib.md5()
-    with pkg_resources.resource_stream(package, filename) as stream:
-        for block in iter(lambda: stream.read(4096), ''):
-            md5.update(block)
-    return md5.hexdigest()
-
-
-@implementer(ICacheBuster)
-class DefaultCacheBuster(object):
-
-    def generate_token(self, request, pathspec):
-        token_cache = request.registry.setdefault('md5-token-cache', {})
-        token = token_cache.get(pathspec)
-        if not token:
-            token_cache[pathspec] = token = generate_md5(pathspec)
-        return token
-
-    def pregenerate_url(self, request, token, subpath, kw):
-        return token + '/' + subpath, kw
-
-    def match_url(self, request, path_elements):
-        return path_elements[1:]
diff --git a/pyramid/config/views.py b/pyramid/config/views.py
index 78c415b14..c09ddc73d 100644
--- a/pyramid/config/views.py
+++ b/pyramid/config/views.py
@@ -1,6 +1,8 @@
+import hashlib
 import inspect
 import operator
 import os
+import pkg_resources
 import warnings
 
 from zope.interface import (
@@ -34,7 +36,7 @@ from pyramid.interfaces import (
     )
 
 from pyramid import renderers
-from pyramid.cachebust import DefaultCacheBuster
+from pyramid.asset import resolve_asset_spec
 
 from pyramid.compat import (
     string_types,
@@ -45,11 +47,6 @@ from pyramid.compat import (
     is_nonstr_iter
     )
 
-from pyramid.encode import (
-    quote_plus,
-    urlencode,
-)
-
 from pyramid.exceptions import (
     ConfigurationError,
     PredicateMismatch,
@@ -1907,15 +1904,13 @@ class StaticURLInfo(object):
         except AttributeError: # bw compat (for tests)
             registry = get_current_registry()
         registrations = self._get_registrations(registry)
-        for (url, spec, route_name, cachebust) in registrations:
+        for (url, spec, route_name, cachebuster) in registrations:
             if path.startswith(spec):
                 subpath = path[len(spec):]
                 if WIN: # pragma: no cover
                     subpath = subpath.replace('\\', '/') # windows
-                if cachebust:
-                    token = cachebust.generate_token(request, spec + subpath)
-                    subpath, kw = cachebust.pregenerate_url(
-                        request, token, subpath, kw)
+                if cachebuster:
+                    subpath, kw = cachebuster(subpath, kw)
                 if url is None:
                     kw['subpath'] = subpath
                     return request.route_url(route_name, **kw)
@@ -1955,9 +1950,22 @@ class StaticURLInfo(object):
             # make sure it ends with a slash
             name = name + '/'
 
-        cachebust = extra.pop('cachebust', None)
-        if cachebust is True:
-            cachebust = DefaultCacheBuster()
+        cb = extra.pop('cachebust', None)
+        if cb is True:
+            cb_token, cb_pregen, cb_match = DefaultCacheBuster()
+        elif cb:
+            cb_token, cb_pregen, cb_match = cb
+        else:
+            cb_token = cb_pregen = cb_match = None
+
+        if cb_token and cb_pregen:
+            def cachebuster(subpath, kw):
+                token = cb_token(spec + subpath)
+                subpath_tuple = tuple(subpath.split('/'))
+                subpath_tuple, kw = cb_pregen(token, subpath_tuple, kw)
+                return '/'.join(subpath_tuple), kw
+        else:
+            cachebuster = None
 
         if url_parse(name).netloc:
             # it's a URL
@@ -1968,12 +1976,12 @@ class StaticURLInfo(object):
             # it's a view name
             url = None
             cache_max_age = extra.pop('cache_max_age', None)
-            if cache_max_age is None and cachebust:
+            if cache_max_age is None and cb:
                 cache_max_age = 10 * 365 * 24 * 60 * 60  # Ten(ish) years
 
             # create a view
             view = static_view(spec, cache_max_age=cache_max_age,
-                               use_subpath=True, cachebust=cachebust)
+                               use_subpath=True, cachebust_match=cb_match)
 
             # Mutate extra to allow factory, etc to be passed through here.
             # Treat permission specially because we'd like to default to
@@ -2014,7 +2022,7 @@ class StaticURLInfo(object):
                 registrations.pop(idx)
 
             # url, spec, route_name
-            registrations.append((url, spec, route_name, cachebust))
+            registrations.append((url, spec, route_name, cachebuster))
 
         intr = config.introspectable('static views',
                                      name,
@@ -2026,3 +2034,40 @@ class StaticURLInfo(object):
         config.action(None, callable=register, introspectables=(intr,))
 
 
+def _generate_md5(spec):
+    package, filename = resolve_asset_spec(spec)
+    md5 = hashlib.md5()
+    with pkg_resources.resource_stream(package, filename) as stream:
+        for block in iter(lambda: stream.read(4096), ''):
+            md5.update(block)
+    return md5.hexdigest()
+
+
+def DefaultCacheBuster():
+    token_cache = {}
+
+    def generate_token(pathspec):
+        # An astute observer will notice that this use of token_cache doesn't
+        # look particular thread safe.  Basic read/write operations on Python
+        # dicts, however, are atomic, so simply accessing and writing values
+        # to the dict shouldn't cause a segfault or other catastrophic failure.
+        # (See: http://effbot.org/pyfaq/what-kinds-of-global-value-mutation-are-thread-safe.htm)
+        #
+        # We do have a race condition that could result in the same md5
+        # checksum getting computed twice or more times in parallel.  Since
+        # the program would still function just fine if this were to occur,
+        # the extra overhead of using locks to serialize access to the dict
+        # seems an unnecessary burden.
+        #
+        token = token_cache.get(pathspec)
+        if not token:
+            token_cache[pathspec] = token = _generate_md5(pathspec)
+        return token
+
+    def pregenerate_url(token, subpath, kw):
+        return (token,) + subpath, kw
+
+    def match_url(subpath):
+        return subpath[1:]
+
+    return (generate_token, pregenerate_url, match_url)
diff --git a/pyramid/interfaces.py b/pyramid/interfaces.py
index e60898dbc..84a6ad833 100644
--- a/pyramid/interfaces.py
+++ b/pyramid/interfaces.py
@@ -1164,47 +1164,60 @@ class IJSONAdapter(Interface):
 class IPredicateList(Interface):
     """ Interface representing a predicate list """
 
-class ICacheBuster(Interface):
-    """
-    An instance of a class which implements this interface may be passed as the
-    ``cachebust`` argument to
-    :meth:`pyramid.config.Configurator.add_static_view` to add cache busting
-    capability to a static view.
-    """
-    def generate_token(request, pathspec):
+class ICachebustTokenGenerator(Interface):
+    def __call__(pathspec):
         """
-        Return a token string for a static asset to be used to rewrite a
-        static asset URL for cache busting.
+        A function which computes and returns a token string used for cache
+        busting.  ``pathspec`` is the path specification for the resource to be
+        cache busted.  Often a cachebust token might be computed for a specific
+        asset (e.g. an md5 checksum), but probably just as often people use
+        schemes where a single cachebust token is used globally.  It could be a
+        git commit sha1, a timestamp, or something configured manually. A
+        pattern that can be useful is to use to a factory function and a
+        closure to return a function that depends on some configuration.  For
+        example:
 
-        The ``pathspec`` argument is the path specification for the asset we're
-        generating a token for.
+        .. code-block:: python
+           :linenos:
+
+           def use_configured_cachebust_token(config):
+               # config is an instance of pyramid.config.Configurator
+               token = config.registry.settings['myapp.cachebust_token']
+               def cachebust_token(pathspec):
+                   return token
+               return cachebust_token
         """
 
-    def pregenerate_url(request, token, subpath, kw):
+class ICachebustURLPregenerator(Interface):
+    def __call__(token, subpath, kw):
         """
-        Modifies the elements and/or keywords used to generate the URL for a
-        given static asset.
-
-        The ``token`` argument is the result of calling
-        :meth:`~pyramid.interfaces.ICacheBuster.generate_token` for a static
-        asset.
-
-        The ``subpath`` argument is the subpath in the static asset URL that
-        would normally be generated without cache busting.  The ``kw``
-        argument is the keywords dict that would be passed to
-        :meth:`~pyramid.request.Request.route_url`.
-        The return value should be a two-tuple of elements ``(subpath, kw)``
-        which are modified from the incoming arguments.
+        A function which modifies a subpath and/or keyword arguments from which
+        a static asset URL will be computed during URL generation.  The
+        ``token`` argument is a token string computed by an instance of
+        :class:`~pyramid.interfaces.ICachebustTokenGenerator` for a particular
+        asset.  The ``subpath`` argument is a tuple of path elements that
+        represent the portion of the asset URL which is used to find the asset.
+        The ``kw`` argument is a dict of keywords that are to be passed
+        eventually to :meth:`~pyramid.request.Request.route_url` for URL
+        generation.  The return value of this function should be two-tuple of
+        ``(subpath, kw)`` which are versions of the same arguments modified to
+        include the cachebust token in the generated URL.
         """
 
-    def match_url(request, path_elements):
+class ICachebustURLMatcher(Interface):
+    def __call__(subpath):
         """
-        Undo any modification to the subpath which may have been done by
-        :meth:`~pyramid.interfaces.ICacheBuster.pregenerate_url`.  The
-        ``path_elements`` argument is a tuple of path elements that represent
-        the subpath of the asset request URL.  The return value should be
-        a modified (or not) version of ``path_elements``, which will be used
-        ultimately to find the asset.
+        A function which performs the logical inverse of an
+        :class:`~pyramid.interfaces.ICacheBustURLPregenerator`, by taking a
+        subpath from a cache busted URL and removing the cachebust token, so
+        that :app:`Pyramid` can find the underlying asset.  If the cache
+        busting scheme in use doesn't specifically modify the path portion of
+        the generated URL (e.g. it adds a query string), a function which
+        implements this interface may not be necessary.
+
+        ``subpath`` is the subpath portion of the URL for an incoming request
+        for a static asset.  The return value should be the same tuple with the
+        cache busting token elided.
         """
 
 # configuration phases: a lower phase number means the actions associated
diff --git a/pyramid/static.py b/pyramid/static.py
index be191971a..87bbcd34c 100644
--- a/pyramid/static.py
+++ b/pyramid/static.py
@@ -78,7 +78,7 @@ class static_view(object):
     """
 
     def __init__(self, root_dir, cache_max_age=3600, package_name=None,
-                 use_subpath=False, index='index.html', cachebust=None):
+                 use_subpath=False, index='index.html', cachebust_match=None):
         # package_name is for bw compat; it is preferred to pass in a
         # package-relative path as root_dir
         # (e.g. ``anotherpackage:foo/static``).
@@ -91,15 +91,15 @@ class static_view(object):
         self.docroot = docroot
         self.norm_docroot = normcase(normpath(docroot))
         self.index = index
-        self.cachebust = cachebust
+        self.cachebust_match = cachebust_match
 
     def __call__(self, context, request):
         if self.use_subpath:
             path_tuple = request.subpath
         else:
             path_tuple = traversal_path_info(request.environ['PATH_INFO'])
-        if self.cachebust:
-            path_tuple = self.cachebust.match_url(request, path_tuple)
+        if self.cachebust_match:
+            path_tuple = self.cachebust_match(path_tuple)
         path = _secure_path(path_tuple)
 
         if path is None:
-- 
cgit v1.2.3


From 9af33504d9d621bc0f87752837a09f9110e454e5 Mon Sep 17 00:00:00 2001
From: Chris Rossi <chris@archimedeanco.com>
Date: Tue, 15 Jul 2014 10:52:14 -0400
Subject: Show an example.

---
 pyramid/interfaces.py | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/pyramid/interfaces.py b/pyramid/interfaces.py
index 84a6ad833..95aa1d60e 100644
--- a/pyramid/interfaces.py
+++ b/pyramid/interfaces.py
@@ -1202,6 +1202,15 @@ class ICachebustURLPregenerator(Interface):
         generation.  The return value of this function should be two-tuple of
         ``(subpath, kw)`` which are versions of the same arguments modified to
         include the cachebust token in the generated URL.
+
+        Here is an example which places the token in a query string:
+
+        .. code-block:: python
+           :linenos:
+
+           def cb_pregen(token, subpath kw):
+               kw.setdefault('_query', {})['cb'] = token
+               return subpath, kw
         """
 
 class ICachebustURLMatcher(Interface):
-- 
cgit v1.2.3


From de2996ddcc7c2ac5c3e59101df0fed1ab832701b Mon Sep 17 00:00:00 2001
From: Chris Rossi <chris@archimedeanco.com>
Date: Tue, 15 Jul 2014 10:57:36 -0400
Subject: Make sure it's possible to still set cache_max_age to None even if
 cache busting is being used.

---
 pyramid/config/views.py | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/pyramid/config/views.py b/pyramid/config/views.py
index c09ddc73d..b583b59a0 100644
--- a/pyramid/config/views.py
+++ b/pyramid/config/views.py
@@ -1975,9 +1975,9 @@ class StaticURLInfo(object):
         else:
             # it's a view name
             url = None
-            cache_max_age = extra.pop('cache_max_age', None)
-            if cache_max_age is None and cb:
-                cache_max_age = 10 * 365 * 24 * 60 * 60  # Ten(ish) years
+            ten_years = 10 * 365 * 24 * 60 * 60  # more or less
+            default = ten_years if cb else None
+            cache_max_age = extra.pop('cache_max_age', default)
 
             # create a view
             view = static_view(spec, cache_max_age=cache_max_age,
-- 
cgit v1.2.3


From 2a1ca8c542e752bdd1de2bfdac0f3365a209c072 Mon Sep 17 00:00:00 2001
From: Chris Rossi <chris@archimedeanco.com>
Date: Tue, 15 Jul 2014 14:19:07 -0400
Subject: I kind of like Raydeo's last idea.

---
 pyramid/config/views.py | 62 ++++++++++---------------------------------------
 pyramid/interfaces.py   | 29 +++++++++++++----------
 pyramid/static.py       | 56 ++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 85 insertions(+), 62 deletions(-)

diff --git a/pyramid/config/views.py b/pyramid/config/views.py
index b583b59a0..4b7bdaa81 100644
--- a/pyramid/config/views.py
+++ b/pyramid/config/views.py
@@ -1,8 +1,6 @@
-import hashlib
 import inspect
 import operator
 import os
-import pkg_resources
 import warnings
 
 from zope.interface import (
@@ -36,7 +34,10 @@ from pyramid.interfaces import (
     )
 
 from pyramid import renderers
-from pyramid.asset import resolve_asset_spec
+from pyramid.static import (
+    Md5AssetTokenGenerator,
+    PathSegmentCacheBuster,
+)
 
 from pyramid.compat import (
     string_types,
@@ -1950,19 +1951,14 @@ class StaticURLInfo(object):
             # make sure it ends with a slash
             name = name + '/'
 
-        cb = extra.pop('cachebust', None)
+        cb = extra.pop('cachebuster', None)
         if cb is True:
-            cb_token, cb_pregen, cb_match = DefaultCacheBuster()
-        elif cb:
-            cb_token, cb_pregen, cb_match = cb
-        else:
-            cb_token = cb_pregen = cb_match = None
-
-        if cb_token and cb_pregen:
+            cb = DefaultCacheBuster()
+        if cb:
             def cachebuster(subpath, kw):
-                token = cb_token(spec + subpath)
+                token = cb.token(spec + subpath)
                 subpath_tuple = tuple(subpath.split('/'))
-                subpath_tuple, kw = cb_pregen(token, subpath_tuple, kw)
+                subpath_tuple, kw = cb.pregenerate(token, subpath_tuple, kw)
                 return '/'.join(subpath_tuple), kw
         else:
             cachebuster = None
@@ -1980,6 +1976,7 @@ class StaticURLInfo(object):
             cache_max_age = extra.pop('cache_max_age', default)
 
             # create a view
+            cb_match = getattr(cb, 'match', None)
             view = static_view(spec, cache_max_age=cache_max_age,
                                use_subpath=True, cachebust_match=cb_match)
 
@@ -2033,41 +2030,6 @@ class StaticURLInfo(object):
 
         config.action(None, callable=register, introspectables=(intr,))
 
-
-def _generate_md5(spec):
-    package, filename = resolve_asset_spec(spec)
-    md5 = hashlib.md5()
-    with pkg_resources.resource_stream(package, filename) as stream:
-        for block in iter(lambda: stream.read(4096), ''):
-            md5.update(block)
-    return md5.hexdigest()
-
-
 def DefaultCacheBuster():
-    token_cache = {}
-
-    def generate_token(pathspec):
-        # An astute observer will notice that this use of token_cache doesn't
-        # look particular thread safe.  Basic read/write operations on Python
-        # dicts, however, are atomic, so simply accessing and writing values
-        # to the dict shouldn't cause a segfault or other catastrophic failure.
-        # (See: http://effbot.org/pyfaq/what-kinds-of-global-value-mutation-are-thread-safe.htm)
-        #
-        # We do have a race condition that could result in the same md5
-        # checksum getting computed twice or more times in parallel.  Since
-        # the program would still function just fine if this were to occur,
-        # the extra overhead of using locks to serialize access to the dict
-        # seems an unnecessary burden.
-        #
-        token = token_cache.get(pathspec)
-        if not token:
-            token_cache[pathspec] = token = _generate_md5(pathspec)
-        return token
-
-    def pregenerate_url(token, subpath, kw):
-        return (token,) + subpath, kw
-
-    def match_url(subpath):
-        return subpath[1:]
-
-    return (generate_token, pregenerate_url, match_url)
+    return PathSegmentCacheBuster(Md5AssetTokenGenerator())
+
diff --git a/pyramid/interfaces.py b/pyramid/interfaces.py
index 95aa1d60e..822d1624c 100644
--- a/pyramid/interfaces.py
+++ b/pyramid/interfaces.py
@@ -1164,8 +1164,12 @@ class IJSONAdapter(Interface):
 class IPredicateList(Interface):
     """ Interface representing a predicate list """
 
-class ICachebustTokenGenerator(Interface):
-    def __call__(pathspec):
+class ICacheBuster(Interface):
+    """
+    A container for functions which implement a cache busting policy for
+    serving static assets.
+    """
+    def token(pathspec):
         """
         A function which computes and returns a token string used for cache
         busting.  ``pathspec`` is the path specification for the resource to be
@@ -1188,13 +1192,12 @@ class ICachebustTokenGenerator(Interface):
                return cachebust_token
         """
 
-class ICachebustURLPregenerator(Interface):
-    def __call__(token, subpath, kw):
+    def pregenerate(token, subpath, kw):
         """
         A function which modifies a subpath and/or keyword arguments from which
         a static asset URL will be computed during URL generation.  The
         ``token`` argument is a token string computed by an instance of
-        :class:`~pyramid.interfaces.ICachebustTokenGenerator` for a particular
+        :method:`~pyramid.interfaces.ICacheBuster.token` for a particular
         asset.  The ``subpath`` argument is a tuple of path elements that
         represent the portion of the asset URL which is used to find the asset.
         The ``kw`` argument is a dict of keywords that are to be passed
@@ -1213,20 +1216,22 @@ class ICachebustURLPregenerator(Interface):
                return subpath, kw
         """
 
-class ICachebustURLMatcher(Interface):
-    def __call__(subpath):
+    def match(subpath):
         """
         A function which performs the logical inverse of an
-        :class:`~pyramid.interfaces.ICacheBustURLPregenerator`, by taking a
+        :method:`~pyramid.interfaces.ICacheBuster.pregenerate`, by taking a
         subpath from a cache busted URL and removing the cachebust token, so
-        that :app:`Pyramid` can find the underlying asset.  If the cache
-        busting scheme in use doesn't specifically modify the path portion of
-        the generated URL (e.g. it adds a query string), a function which
-        implements this interface may not be necessary.
+        that :app:`Pyramid` can find the underlying asset.
 
         ``subpath`` is the subpath portion of the URL for an incoming request
         for a static asset.  The return value should be the same tuple with the
         cache busting token elided.
+
+        If the cache busting scheme in use doesn't specifically modify the path
+        portion of the generated URL (e.g. it adds a query string), a function
+        which implements this interface may not be necessary.  It is
+        permissible for an instance of
+        :class:`~pyramid.interfaces.ICacheBuster` to omit this function.
         """
 
 # configuration phases: a lower phase number means the actions associated
diff --git a/pyramid/static.py b/pyramid/static.py
index 87bbcd34c..92251721e 100644
--- a/pyramid/static.py
+++ b/pyramid/static.py
@@ -1,5 +1,7 @@
 # -*- coding: utf-8 -*-
+import hashlib
 import os
+import pkg_resources
 
 from os.path import (
     normcase,
@@ -155,3 +157,57 @@ def _secure_path(path_tuple):
         return None
     encoded = slash.join(path_tuple) # will be unicode
     return encoded
+
+def _generate_md5(spec):
+    package, filename = resolve_asset_spec(spec)
+    md5 = hashlib.md5()
+    with pkg_resources.resource_stream(package, filename) as stream:
+        for block in iter(lambda: stream.read(4096), ''):
+            md5.update(block)
+    return md5.hexdigest()
+
+def Md5AssetTokenGenerator():
+    token_cache = {}
+
+    def generate_token(pathspec):
+        # An astute observer will notice that this use of token_cache doesn't
+        # look particularly thread safe.  Basic read/write operations on Python
+        # dicts, however, are atomic, so simply accessing and writing values
+        # to the dict shouldn't cause a segfault or other catastrophic failure.
+        # (See: http://effbot.org/pyfaq/what-kinds-of-global-value-mutation-are-thread-safe.htm)
+        #
+        # We do have a race condition that could result in the same md5
+        # checksum getting computed twice or more times in parallel.  Since
+        # the program would still function just fine if this were to occur,
+        # the extra overhead of using locks to serialize access to the dict
+        # seems an unnecessary burden.
+        #
+        token = token_cache.get(pathspec)
+        if not token:
+            token_cache[pathspec] = token = _generate_md5(pathspec)
+        return token
+
+    return generate_token
+
+class PathSegmentCacheBuster(object):
+
+    def __init__(self, token):
+        self.token = token
+
+    def pregenerate(self, token, subpath, kw):
+        return (token,) + subpath, kw
+
+    def match(self, subpath):
+        return subpath[1:]
+
+class QueryStringCacheBuster(object):
+
+    def __init__(self, token, param='x'):
+        self.param = param
+        self.token = token
+
+    def pregenerate(self, token, subpath, kw):
+        kw.setdefault('_query', {})[self.param] = token
+        return subpath, kw
+
+
-- 
cgit v1.2.3


From cac23bb790da283fad7ad51ac4c18fc3903ebb92 Mon Sep 17 00:00:00 2001
From: Chris Rossi <chris@archimedeanco.com>
Date: Tue, 15 Jul 2014 16:52:15 -0400
Subject: Fix broken tests.

---
 pyramid/tests/test_config/test_views.py | 45 +++++++++++++++++++--------------
 1 file changed, 26 insertions(+), 19 deletions(-)

diff --git a/pyramid/tests/test_config/test_views.py b/pyramid/tests/test_config/test_views.py
index 57bb5e9d0..e01aed1f2 100644
--- a/pyramid/tests/test_config/test_views.py
+++ b/pyramid/tests/test_config/test_views.py
@@ -113,7 +113,7 @@ class TestViewsConfigurationMixin(unittest.TestCase):
         config.add_view(renderer='dummy.pt')
         view = self._getViewCallable(config)
         self.assertRaises(ValueError, view, None, None)
-        
+
     def test_add_view_with_tmpl_renderer_factory_no_renderer_factory(self):
         config = self._makeOne(autocommit=True)
         introspector = DummyIntrospector()
@@ -136,7 +136,7 @@ class TestViewsConfigurationMixin(unittest.TestCase):
             ('renderer factories', '.pt') in introspector.related[-1])
         view = self._getViewCallable(config)
         self.assertTrue(b'Hello!' in view(None, None).body)
-        
+
     def test_add_view_wrapped_view_is_decorated(self):
         def view(request): # request-only wrapper
             """ """
@@ -3742,8 +3742,9 @@ class TestStaticURLInfo(unittest.TestCase):
 
     def test_generate_registration_miss(self):
         inst = self._makeOne()
-        registrations = [(None, 'spec', 'route_name'),
-                         ('http://example.com/foo/', 'package:path/', None)]
+        registrations = [
+            (None, 'spec', 'route_name', None),
+            ('http://example.com/foo/', 'package:path/', None, None)]
         inst._get_registrations = lambda *x: registrations
         request = self._makeRequest()
         result = inst.generate('package:path/abc', request)
@@ -3751,7 +3752,8 @@ class TestStaticURLInfo(unittest.TestCase):
 
     def test_generate_registration_no_registry_on_request(self):
         inst = self._makeOne()
-        registrations = [('http://example.com/foo/', 'package:path/', None)]
+        registrations = [
+            ('http://example.com/foo/', 'package:path/', None, None)]
         inst._get_registrations = lambda *x: registrations
         request = self._makeRequest()
         del request.registry
@@ -3760,7 +3762,8 @@ class TestStaticURLInfo(unittest.TestCase):
 
     def test_generate_slash_in_name1(self):
         inst = self._makeOne()
-        registrations = [('http://example.com/foo/', 'package:path/', None)]
+        registrations = [
+            ('http://example.com/foo/', 'package:path/', None, None)]
         inst._get_registrations = lambda *x: registrations
         request = self._makeRequest()
         result = inst.generate('package:path/abc', request)
@@ -3768,7 +3771,8 @@ class TestStaticURLInfo(unittest.TestCase):
 
     def test_generate_slash_in_name2(self):
         inst = self._makeOne()
-        registrations = [('http://example.com/foo/', 'package:path/', None)]
+        registrations = [
+            ('http://example.com/foo/', 'package:path/', None, None)]
         inst._get_registrations = lambda *x: registrations
         request = self._makeRequest()
         result = inst.generate('package:path/', request)
@@ -3788,7 +3792,7 @@ class TestStaticURLInfo(unittest.TestCase):
 
     def test_generate_route_url(self):
         inst = self._makeOne()
-        registrations = [(None, 'package:path/', '__viewname/')]
+        registrations = [(None, 'package:path/', '__viewname/', None)]
         inst._get_registrations = lambda *x: registrations
         def route_url(n, **kw):
             self.assertEqual(n, '__viewname/')
@@ -3801,7 +3805,7 @@ class TestStaticURLInfo(unittest.TestCase):
 
     def test_generate_url_unquoted_local(self):
         inst = self._makeOne()
-        registrations = [(None, 'package:path/', '__viewname/')]
+        registrations = [(None, 'package:path/', '__viewname/', None)]
         inst._get_registrations = lambda *x: registrations
         def route_url(n, **kw):
             self.assertEqual(n, '__viewname/')
@@ -3814,7 +3818,7 @@ class TestStaticURLInfo(unittest.TestCase):
 
     def test_generate_url_quoted_remote(self):
         inst = self._makeOne()
-        registrations = [('http://example.com/', 'package:path/', None)]
+        registrations = [('http://example.com/', 'package:path/', None, None)]
         inst._get_registrations = lambda *x: registrations
         request = self._makeRequest()
         result = inst.generate('package:path/abc def', request, a=1)
@@ -3822,7 +3826,7 @@ class TestStaticURLInfo(unittest.TestCase):
 
     def test_generate_url_with_custom_query(self):
         inst = self._makeOne()
-        registrations = [('http://example.com/', 'package:path/', None)]
+        registrations = [('http://example.com/', 'package:path/', None, None)]
         inst._get_registrations = lambda *x: registrations
         request = self._makeRequest()
         result = inst.generate('package:path/abc def', request, a=1,
@@ -3832,7 +3836,7 @@ class TestStaticURLInfo(unittest.TestCase):
 
     def test_generate_url_with_custom_anchor(self):
         inst = self._makeOne()
-        registrations = [('http://example.com/', 'package:path/', None)]
+        registrations = [('http://example.com/', 'package:path/', None, None)]
         inst._get_registrations = lambda *x: registrations
         request = self._makeRequest()
         uc = text_(b'La Pe\xc3\xb1a', 'utf-8')
@@ -3846,28 +3850,31 @@ class TestStaticURLInfo(unittest.TestCase):
         config = self._makeConfig(
             [('http://example.com/', 'package:path/', None)])
         inst.add(config, 'http://example.com', 'anotherpackage:path')
-        expected = [('http://example.com/',  'anotherpackage:path/', None)]
+        expected = [
+            ('http://example.com/',  'anotherpackage:path/', None, None)]
         self._assertRegistrations(config, expected)
 
     def test_add_url_withendslash(self):
         inst = self._makeOne()
         config = self._makeConfig()
         inst.add(config, 'http://example.com/', 'anotherpackage:path')
-        expected = [('http://example.com/', 'anotherpackage:path/', None)]
+        expected = [
+            ('http://example.com/', 'anotherpackage:path/', None, None)]
         self._assertRegistrations(config, expected)
 
     def test_add_url_noendslash(self):
         inst = self._makeOne()
         config = self._makeConfig()
         inst.add(config, 'http://example.com', 'anotherpackage:path')
-        expected = [('http://example.com/', 'anotherpackage:path/', None)]
+        expected = [
+            ('http://example.com/', 'anotherpackage:path/', None, None)]
         self._assertRegistrations(config, expected)
 
     def test_add_url_noscheme(self):
         inst = self._makeOne()
         config = self._makeConfig()
         inst.add(config, '//example.com', 'anotherpackage:path')
-        expected = [('//example.com/', 'anotherpackage:path/', None)]
+        expected = [('//example.com/', 'anotherpackage:path/', None, None)]
         self._assertRegistrations(config, expected)
 
     def test_add_viewname(self):
@@ -3876,7 +3883,7 @@ class TestStaticURLInfo(unittest.TestCase):
         config = self._makeConfig()
         inst = self._makeOne()
         inst.add(config, 'view', 'anotherpackage:path', cache_max_age=1)
-        expected = [(None, 'anotherpackage:path/', '__view/')]
+        expected = [(None, 'anotherpackage:path/', '__view/', None)]
         self._assertRegistrations(config, expected)
         self.assertEqual(config.route_args, ('__view/', 'view/*subpath'))
         self.assertEqual(config.view_kw['permission'], NO_PERMISSION_REQUIRED)
@@ -3887,7 +3894,7 @@ class TestStaticURLInfo(unittest.TestCase):
         config.route_prefix = '/abc'
         inst = self._makeOne()
         inst.add(config, 'view', 'anotherpackage:path',)
-        expected = [(None, 'anotherpackage:path/', '__/abc/view/')]
+        expected = [(None, 'anotherpackage:path/', '__/abc/view/', None)]
         self._assertRegistrations(config, expected)
         self.assertEqual(config.route_args, ('__/abc/view/', 'view/*subpath'))
 
@@ -3904,7 +3911,7 @@ class TestStaticURLInfo(unittest.TestCase):
         inst.add(config, 'view', 'anotherpackage:path', cache_max_age=1,
                  context=DummyContext)
         self.assertEqual(config.view_kw['context'], DummyContext)
-        
+
     def test_add_viewname_with_for_(self):
         config = self._makeConfig()
         inst = self._makeOne()
-- 
cgit v1.2.3


From 5350158f666a638293bd2b3d7cd19029e0bab145 Mon Sep 17 00:00:00 2001
From: Chris Rossi <chris@archimedeanco.com>
Date: Tue, 15 Jul 2014 18:02:01 -0400
Subject: Test coverage for pyramid.config.views

---
 pyramid/config/views.py                 | 11 ++++++----
 pyramid/tests/test_config/test_views.py | 39 +++++++++++++++++++++++++++++++++
 2 files changed, 46 insertions(+), 4 deletions(-)

diff --git a/pyramid/config/views.py b/pyramid/config/views.py
index 4b7bdaa81..00c5622e7 100644
--- a/pyramid/config/views.py
+++ b/pyramid/config/views.py
@@ -1891,6 +1891,12 @@ def isexception(o):
 
 @implementer(IStaticURLInfo)
 class StaticURLInfo(object):
+    # Indirection for testing
+    _default_cachebuster = staticmethod(PathSegmentCacheBuster)
+    _default_asset_token_generator = staticmethod(Md5AssetTokenGenerator)
+
+    def _make_default_cachebuster(self):
+        return self._default_cachebuster(self._default_asset_token_generator())
 
     def _get_registrations(self, registry):
         try:
@@ -1953,7 +1959,7 @@ class StaticURLInfo(object):
 
         cb = extra.pop('cachebuster', None)
         if cb is True:
-            cb = DefaultCacheBuster()
+            cb = self._make_default_cachebuster()
         if cb:
             def cachebuster(subpath, kw):
                 token = cb.token(spec + subpath)
@@ -2030,6 +2036,3 @@ class StaticURLInfo(object):
 
         config.action(None, callable=register, introspectables=(intr,))
 
-def DefaultCacheBuster():
-    return PathSegmentCacheBuster(Md5AssetTokenGenerator())
-
diff --git a/pyramid/tests/test_config/test_views.py b/pyramid/tests/test_config/test_views.py
index e01aed1f2..0b81f5a6f 100644
--- a/pyramid/tests/test_config/test_views.py
+++ b/pyramid/tests/test_config/test_views.py
@@ -3845,6 +3845,20 @@ class TestStaticURLInfo(unittest.TestCase):
         self.assertEqual(result,
                          'http://example.com/abc%20def#La%20Pe%C3%B1a')
 
+    def test_generate_url_cachebuster(self):
+        def cachebuster(subpath, kw):
+            kw['foo'] = 'bar'
+            return 'foo' + '/' + subpath, kw
+        inst = self._makeOne()
+        registrations = [(None, 'package:path/', '__viewname', cachebuster)]
+        inst._get_registrations = lambda *x: registrations
+        request = self._makeRequest()
+        def route_url(n, **kw):
+            self.assertEqual(n, '__viewname')
+            self.assertEqual(kw, {'subpath':'foo/abc', 'foo':'bar'})
+        request.route_url = route_url
+        inst.generate('package:path/abc', request)
+
     def test_add_already_exists(self):
         inst = self._makeOne()
         config = self._makeConfig(
@@ -3927,6 +3941,31 @@ class TestStaticURLInfo(unittest.TestCase):
         self.assertEqual(config.view_kw['renderer'],
                          'mypackage:templates/index.pt')
 
+    def test_add_cachebust_default(self):
+        config = self._makeConfig()
+        inst = self._makeOne()
+        inst._default_asset_token_generator = lambda: lambda pathspec: 'foo'
+        inst.add(config, 'view', 'mypackage:path', cachebuster=True)
+        cachebuster = config.registry._static_url_registrations[0][3]
+        subpath, _ = cachebuster('some/path', None)
+        self.assertEqual(subpath, 'foo/some/path')
+
+    def test_add_cachebust_custom(self):
+        class DummyCacheBuster(object):
+            def token(self, pathspec):
+                return 'foo'
+            def pregenerate(self, token, subpath, kw):
+                kw['x'] = token
+                return subpath, kw
+        config = self._makeConfig()
+        inst = self._makeOne()
+        inst.add(config, 'view', 'mypackage:path',
+                 cachebuster=DummyCacheBuster())
+        cachebuster = config.registry._static_url_registrations[0][3]
+        subpath, kw = cachebuster('some/path', {})
+        self.assertEqual(subpath, 'some/path')
+        self.assertEqual(kw['x'], 'foo')
+
 class Test_view_description(unittest.TestCase):
     def _callFUT(self, view):
         from pyramid.config.views import view_description
-- 
cgit v1.2.3


From dc97173e0c7306792814e3fa44dc0cd8e0e493b9 Mon Sep 17 00:00:00 2001
From: Chris Rossi <chris@archimedeanco.com>
Date: Wed, 16 Jul 2014 09:10:25 -0400
Subject: Make sure md5 checksum works for non-package assets.

---
 pyramid/static.py | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/pyramid/static.py b/pyramid/static.py
index 92251721e..290732640 100644
--- a/pyramid/static.py
+++ b/pyramid/static.py
@@ -160,8 +160,12 @@ def _secure_path(path_tuple):
 
 def _generate_md5(spec):
     package, filename = resolve_asset_spec(spec)
+    if package:
+        stream = pkg_resources.resource_stream(package, filename)
+    else:
+        stream = open(filename, 'rb')
     md5 = hashlib.md5()
-    with pkg_resources.resource_stream(package, filename) as stream:
+    with stream:
         for block in iter(lambda: stream.read(4096), ''):
             md5.update(block)
     return md5.hexdigest()
-- 
cgit v1.2.3


From 46c0294c5e66712e186de96f55ced580d3ae4c0b Mon Sep 17 00:00:00 2001
From: Chris Rossi <chris@archimedeanco.com>
Date: Wed, 16 Jul 2014 10:42:37 -0400
Subject: Use the framework, Luke.

---
 pyramid/static.py | 10 +++-------
 1 file changed, 3 insertions(+), 7 deletions(-)

diff --git a/pyramid/static.py b/pyramid/static.py
index 290732640..7616b0a29 100644
--- a/pyramid/static.py
+++ b/pyramid/static.py
@@ -28,7 +28,7 @@ from pyramid.httpexceptions import (
     HTTPMovedPermanently,
     )
 
-from pyramid.path import caller_package
+from pyramid.path import AssetResolver, caller_package
 from pyramid.response import FileResponse
 from pyramid.traversal import traversal_path_info
 
@@ -159,13 +159,9 @@ def _secure_path(path_tuple):
     return encoded
 
 def _generate_md5(spec):
-    package, filename = resolve_asset_spec(spec)
-    if package:
-        stream = pkg_resources.resource_stream(package, filename)
-    else:
-        stream = open(filename, 'rb')
+    asset = AssetResolver(None).resolve(spec)
     md5 = hashlib.md5()
-    with stream:
+    with asset.stream() as stream:
         for block in iter(lambda: stream.read(4096), ''):
             md5.update(block)
     return md5.hexdigest()
-- 
cgit v1.2.3


From e7339162285144e7bfd716e1e4e000f34974b1c2 Mon Sep 17 00:00:00 2001
From: Chris Rossi <chris@archimedeanco.com>
Date: Wed, 16 Jul 2014 10:44:55 -0400
Subject: Unused import.

---
 pyramid/static.py | 1 -
 1 file changed, 1 deletion(-)

diff --git a/pyramid/static.py b/pyramid/static.py
index 7616b0a29..9d691ca46 100644
--- a/pyramid/static.py
+++ b/pyramid/static.py
@@ -1,7 +1,6 @@
 # -*- coding: utf-8 -*-
 import hashlib
 import os
-import pkg_resources
 
 from os.path import (
     normcase,
-- 
cgit v1.2.3


From eac3ff43f78a33d05e634cd5b4866f7681db34c3 Mon Sep 17 00:00:00 2001
From: Chris Rossi <chris@archimedeanco.com>
Date: Wed, 16 Jul 2014 17:22:57 -0400
Subject: Test coverage for static.

---
 pyramid/tests/test_static.py | 99 ++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 96 insertions(+), 3 deletions(-)

diff --git a/pyramid/tests/test_static.py b/pyramid/tests/test_static.py
index 94497d4f6..5edb70b50 100644
--- a/pyramid/tests/test_static.py
+++ b/pyramid/tests/test_static.py
@@ -26,7 +26,7 @@ class Test_static_view_use_subpath_False(unittest.TestCase):
         if kw is not None:
             environ.update(kw)
         return Request(environ=environ)
-    
+
     def test_ctor_defaultargs(self):
         inst = self._makeOne('package:resource_name')
         self.assertEqual(inst.package_name, 'package')
@@ -110,6 +110,14 @@ class Test_static_view_use_subpath_False(unittest.TestCase):
         response = inst(context, request)
         self.assertTrue(b'<html>static</html>' in response.body)
 
+    def test_cachebust_match(self):
+        inst = self._makeOne('pyramid.tests:fixtures/static')
+        inst.cachebust_match = lambda subpath: subpath[1:]
+        request = self._makeRequest({'PATH_INFO':'/foo/index.html'})
+        context = DummyContext()
+        response = inst(context, request)
+        self.assertTrue(b'<html>static</html>' in response.body)
+
     def test_resource_is_file_with_wsgi_file_wrapper(self):
         from pyramid.response import _BLOCK_SIZE
         inst = self._makeOne('pyramid.tests:fixtures/static')
@@ -218,7 +226,7 @@ class Test_static_view_use_subpath_True(unittest.TestCase):
         if kw is not None:
             environ.update(kw)
         return Request(environ=environ)
-    
+
     def test_ctor_defaultargs(self):
         inst = self._makeOne('package:resource_name')
         self.assertEqual(inst.package_name, 'package')
@@ -273,7 +281,7 @@ class Test_static_view_use_subpath_True(unittest.TestCase):
         context = DummyContext()
         from pyramid.httpexceptions import HTTPNotFound
         self.assertRaises(HTTPNotFound, inst, context, request)
-        
+
     def test_oob_os_sep(self):
         import os
         inst = self._makeOne('pyramid.tests:fixtures/static')
@@ -360,6 +368,91 @@ class Test_static_view_use_subpath_True(unittest.TestCase):
         from pyramid.httpexceptions import HTTPNotFound
         self.assertRaises(HTTPNotFound, inst, context, request)
 
+class TestMd5AssetTokenGenerator(unittest.TestCase):
+
+    def setUp(self):
+        import os
+        import tempfile
+        self.tmp = tempfile.mkdtemp()
+        self.fspath = os.path.join(self.tmp, 'test.txt')
+
+    def tearDown(self):
+        import shutil
+        shutil.rmtree(self.tmp)
+
+    def _makeOne(self):
+        from pyramid.static import Md5AssetTokenGenerator as unit
+        return unit()
+
+    def test_package_resource(self):
+        fut = self._makeOne()
+        expected = '76d653a3a044e2f4b38bb001d283e3d9'
+        token = fut('pyramid.tests:fixtures/static/index.html')
+        self.assertEqual(token, expected)
+
+    def test_filesystem_resource(self):
+        fut = self._makeOne()
+        expected = 'd5155f250bef0e9923e894dbc713c5dd'
+        with open(self.fspath, 'w') as f:
+            f.write("Are we rich yet?")
+        token = fut(self.fspath)
+        self.assertEqual(token, expected)
+
+    def test_cache(self):
+        fut = self._makeOne()
+        expected = 'd5155f250bef0e9923e894dbc713c5dd'
+        with open(self.fspath, 'w') as f:
+            f.write("Are we rich yet?")
+        token = fut(self.fspath)
+        self.assertEqual(token, expected)
+
+        # md5 shouldn't change because we've cached it
+        with open(self.fspath, 'w') as f:
+            f.write("Sorry for the convenience.")
+        token = fut(self.fspath)
+        self.assertEqual(token, expected)
+
+class TestPathSegmentCacheBuster(unittest.TestCase):
+
+    def _makeOne(self):
+        from pyramid.static import PathSegmentCacheBuster as unit
+        return unit(lambda pathspec: 'foo')
+
+    def test_token(self):
+        fut = self._makeOne().token
+        self.assertEqual(fut('whatever'), 'foo')
+
+    def test_pregenerate(self):
+        fut = self._makeOne().pregenerate
+        self.assertEqual(fut('foo', ('bar',), 'kw'), (('foo', 'bar'), 'kw'))
+
+    def test_match(self):
+        fut = self._makeOne().match
+        self.assertEqual(fut(('foo', 'bar')), ('bar',))
+
+class TestQueryStringCacheBuster(unittest.TestCase):
+
+    def _makeOne(self):
+        from pyramid.static import QueryStringCacheBuster as unit
+        return unit(lambda pathspec: 'foo')
+
+    def test_token(self):
+        fut = self._makeOne().token
+        self.assertEqual(fut('whatever'), 'foo')
+
+    def test_pregenerate(self):
+        fut = self._makeOne().pregenerate
+        self.assertEqual(
+            fut('foo', ('bar',), {}),
+            (('bar',), {'_query': {'x': 'foo'}}))
+
+    def test_pregenerate_change_param(self):
+        from pyramid.static import QueryStringCacheBuster as unit
+        fut = unit(lambda pathspec: 'foo', 'y').pregenerate
+        self.assertEqual(
+            fut('foo', ('bar',), {}),
+            (('bar',), {'_query': {'y': 'foo'}}))
+
 class DummyContext:
     pass
 
-- 
cgit v1.2.3


From 737016eb553701ec154e33d212379a2356917e4c Mon Sep 17 00:00:00 2001
From: Chris Rossi <chris@archimedeanco.com>
Date: Wed, 16 Jul 2014 17:40:46 -0400
Subject: Handle list of tuples as query string.

---
 pyramid/static.py            | 6 +++++-
 pyramid/tests/test_static.py | 6 ++++++
 2 files changed, 11 insertions(+), 1 deletion(-)

diff --git a/pyramid/static.py b/pyramid/static.py
index 9d691ca46..4ae00b056 100644
--- a/pyramid/static.py
+++ b/pyramid/static.py
@@ -206,7 +206,11 @@ class QueryStringCacheBuster(object):
         self.token = token
 
     def pregenerate(self, token, subpath, kw):
-        kw.setdefault('_query', {})[self.param] = token
+        query = kw.setdefault('_query', {})
+        if isinstance(query, dict):
+            query[self.param] = token
+        else:
+            kw['_query'] = query + [(self.param, token)]
         return subpath, kw
 
 
diff --git a/pyramid/tests/test_static.py b/pyramid/tests/test_static.py
index 5edb70b50..f7b580df2 100644
--- a/pyramid/tests/test_static.py
+++ b/pyramid/tests/test_static.py
@@ -453,6 +453,12 @@ class TestQueryStringCacheBuster(unittest.TestCase):
             fut('foo', ('bar',), {}),
             (('bar',), {'_query': {'y': 'foo'}}))
 
+    def test_pregenerate_query_is_already_tuples(self):
+        fut = self._makeOne().pregenerate
+        self.assertEqual(
+            fut('foo', ('bar',), {'_query': [('a', 'b')]}),
+            (('bar',), {'_query': [('a', 'b'), ('x', 'foo')]}))
+
 class DummyContext:
     pass
 
-- 
cgit v1.2.3


From d4da82c5ea9713f20205f86c3521db7ebabe2479 Mon Sep 17 00:00:00 2001
From: Chris Rossi <chris@archimedeanco.com>
Date: Thu, 17 Jul 2014 09:26:28 -0400
Subject: Fix infinite loop in PY3.

---
 pyramid/static.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/pyramid/static.py b/pyramid/static.py
index 4ae00b056..09743ac15 100644
--- a/pyramid/static.py
+++ b/pyramid/static.py
@@ -161,7 +161,7 @@ def _generate_md5(spec):
     asset = AssetResolver(None).resolve(spec)
     md5 = hashlib.md5()
     with asset.stream() as stream:
-        for block in iter(lambda: stream.read(4096), ''):
+        for block in iter(lambda: stream.read(4096), b''):
             md5.update(block)
     return md5.hexdigest()
 
-- 
cgit v1.2.3


From f729a1e7f1efc27a6df1ae0eaca7fdffdd86ec2f Mon Sep 17 00:00:00 2001
From: Chris Rossi <chris@archimedeanco.com>
Date: Thu, 17 Jul 2014 16:04:28 -0400
Subject: Write the documentation.

---
 docs/api/interfaces.rst |  2 ++
 docs/api/static.rst     |  7 +++++
 docs/narr/assets.rst    | 72 ++++++++++++++++++++++++++++++++++++++++---------
 pyramid/config/views.py | 15 +++++++----
 pyramid/interfaces.py   | 14 +++++++---
 pyramid/static.py       | 41 ++++++++++++++++++++++++++++
 6 files changed, 129 insertions(+), 22 deletions(-)

diff --git a/docs/api/interfaces.rst b/docs/api/interfaces.rst
index d8d935afd..a62976d8a 100644
--- a/docs/api/interfaces.rst
+++ b/docs/api/interfaces.rst
@@ -86,3 +86,5 @@ Other Interfaces
   .. autointerface:: IResourceURL
      :members:
 
+  .. autointerface:: ICacheBuster
+     :members:
diff --git a/docs/api/static.rst b/docs/api/static.rst
index c28473584..8ea2fff75 100644
--- a/docs/api/static.rst
+++ b/docs/api/static.rst
@@ -9,3 +9,10 @@
      :members:
      :inherited-members:
 
+  .. autoclass:: PathSegmentCacheBuster
+     :members:
+
+  .. autoclass:: QueryStringCacheBuster
+     :members:
+
+  .. autofunction:: Md5AssetTokenGenerator
diff --git a/docs/narr/assets.rst b/docs/narr/assets.rst
index a2976de22..97d473761 100644
--- a/docs/narr/assets.rst
+++ b/docs/narr/assets.rst
@@ -315,7 +315,7 @@ requests a copy, regardless of any caching policy set for the resource's old
 URL.
 
 :app:`Pyramid` can be configured to produce cache busting URLs for static 
-assets by passing the optional argument, `cache_bust` to 
+assets by passing the optional argument, ``cachebuster`` to 
 :meth:`~pyramid.config.Configurator.add_static_view`:
 
 .. code-block:: python
@@ -323,27 +323,22 @@ assets by passing the optional argument, `cache_bust` to
 
    # config is an instance of pyramid.config.Configurator
    config.add_static_view(name='static', path='mypackage:folder/static',
-                           cache_bust='md5')
+                          cachebuster=True)
 
-Supplying the `cache_bust` argument instructs :app:`Pyramid` to add a query
-string to URLs generated for this static view which includes the md5 checksum
-of the static file being served:
+Setting the ``cachebuster`` argument instructs :app:`Pyramid` to use a cache 
+busting scheme which adds the md5 checksum for a static asset as a path segment
+in the asset's URL:
 
 .. code-block:: python
    :linenos:
 
    js_url = request.static_url('mypackage:folder/static/js/myapp.js')
-   # Returns: 'http://www.example.com/static/js/myapp.js?md5=c9658b3c0a314a1ca21e5988e662a09e`
+   # Returns: 'http://www.example.com/static/c9658b3c0a314a1ca21e5988e662a09e/js/myapp.js`
 
 When the asset changes, so will its md5 checksum, and therefore so will its
-URL.  Supplying the `cache_bust` argument also causes the static view to set
+URL.  Supplying the ``cachebuster`` argument also causes the static view to set
 headers instructing clients to cache the asset for ten years, unless the
-`max_cache_age` argument is also passed, in which case that value is used.
-
-.. note::
-
-   `md5` is currently the only possible value for the `cache_bust` argument to
-   :meth:`~pyramid.config.Configurator.add_static_view`.
+``max_cache_age`` argument is also passed, in which case that value is used.
 
 .. note:: 
 
@@ -351,6 +346,57 @@ headers instructing clients to cache the asset for ten years, unless the
    restarting your application, you may still generate URLs with a stale md5
    checksum. 
 
+Customizing the Cache Buster
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Revisiting from the previous section:
+
+.. code-block:: python
+   :linenos:
+
+   # config is an instance of pyramid.config.Configurator
+   config.add_static_view(name='static', path='mypackage:folder/static',
+                          cachebuster=True)
+
+Setting ``cachebuster`` to ``True`` instructs :app:`Pyramid` to use a default
+cache busting implementation that should work for many situations.  The 
+``cachebuster`` may be set to any object that implements the interface,
+:class:`~pyramid.interfaces.ICacheBuster`.  The above configuration is exactly
+equivalent to:
+
+.. code-block:: python
+   :linenos:
+
+   from pyramid.static import (
+       Md5AssetTokenGenerator,
+       PathSegmentCacheBuster)
+
+   # config is an instance of pyramid.config.Configurator
+   cachebuster = PathSegmentCacheBuster(Md5AssetTokenGenerator())
+   config.add_static_view(name='static', path='mypackage:folder/static',
+                          cachebuster=cachebuster)
+
+:app:`Pyramid` includes two ready to use cache buster implementations: 
+:class:`~pyramid.static.PathSegmentCacheBuster`, which inserts an asset token
+in the path portion of the asset's URL, and 
+:class:`~pyramid.static.QueryStringCacheBuster`, which adds an asset token to
+the query string of the asset's URL.  Both of these classes have constructors
+which accept a token generator function as an argument, allowing for the way a
+token is generated to be decoupled from the way it is inserted into a URL.  
+:app:`Pyramid` provides a single asset token generator, 
+:meth:`~pyramid.static.Md5AssetTokenGenerator`.
+
+In order to implement your own cache buster, see the
+:class:`~pyramid.interfaces.ICacheBuster` interface and the existing 
+implementations in the :mod:`~pyramid.static` module.
+
+.. note::
+
+   Many HTTP caching proxy implementations will fail to cache any URL which
+   has a query string. For this reason, you should probably prefer 
+   :class:`~pyramid.static.PathSegementCacheBuster` to 
+   :class:`~pyramid.static.QueryStringCacheBuster`.
+
 .. index::
    single: static assets view
 
diff --git a/pyramid/config/views.py b/pyramid/config/views.py
index 00c5622e7..d74ecfadb 100644
--- a/pyramid/config/views.py
+++ b/pyramid/config/views.py
@@ -1788,11 +1788,16 @@ class ViewsConfiguratorMixin(object):
         particular Expires or Cache-Control headers are set in the response,
         unless ``cache_bust`` is specified.
 
-        The ``cache_bust`` keyword argument may be set to ``"md5"`` to cause
-        :meth:`~pyramid.request.Request.static_url` to generate URLs with an
-        additional query string which includes the md5 checksum for the static
-        asset.  This argument modifies the default for ``cache_max_age``,
-        making it ten years.  ``cache_max_age`` may still be explicitly
+        The ``cachebuster`` keyword argument may be set to cause
+        :meth:`~pyramid.request.Request.static_url` to use cache busting when
+        generating URLs. See :ref:`cache_busting` for general information
+        about cache busting.  The value of the ``cachebuster`` argument may be
+        ``True``, in which case a default cache busting implementation is used.
+        The value of the ``cachebuster`` argument may also be an object which
+        implements :class:`~pyramid.interfaces.ICacheBuster`.  See the
+        :mod:`~pyramid.static` module for some implementations.  If the
+        ``cachebuster`` argument is provided, the default for ``cache_max_age``
+        is modified to be ten years.  ``cache_max_age`` may still be explicitly
         provided to override this default.
 
         The ``permission`` keyword argument is used to specify the
diff --git a/pyramid/interfaces.py b/pyramid/interfaces.py
index 822d1624c..f3d7b1798 100644
--- a/pyramid/interfaces.py
+++ b/pyramid/interfaces.py
@@ -1168,6 +1168,12 @@ class ICacheBuster(Interface):
     """
     A container for functions which implement a cache busting policy for
     serving static assets.
+
+    The implementations provided by :app:`Pyramid` use standard instance
+    methods for ``pregenerate`` and ``match``, while accepting an
+    implementation of ``token`` as an argument to their constructor.  This
+    pattern allows for the decoupling of how a token is generated and how it is
+    inserted into a URL.  For examples see the :mod:`~pyramid.static` module.
     """
     def token(pathspec):
         """
@@ -1197,7 +1203,7 @@ class ICacheBuster(Interface):
         A function which modifies a subpath and/or keyword arguments from which
         a static asset URL will be computed during URL generation.  The
         ``token`` argument is a token string computed by an instance of
-        :method:`~pyramid.interfaces.ICacheBuster.token` for a particular
+        :meth:`~pyramid.interfaces.ICacheBuster.token` for a particular
         asset.  The ``subpath`` argument is a tuple of path elements that
         represent the portion of the asset URL which is used to find the asset.
         The ``kw`` argument is a dict of keywords that are to be passed
@@ -1218,9 +1224,9 @@ class ICacheBuster(Interface):
 
     def match(subpath):
         """
-        A function which performs the logical inverse of an
-        :method:`~pyramid.interfaces.ICacheBuster.pregenerate`, by taking a
-        subpath from a cache busted URL and removing the cachebust token, so
+        A function which performs the logical inverse of
+        :meth:`~pyramid.interfaces.ICacheBuster.pregenerate` by taking a
+        subpath from a cache busted URL and removing the cache bust token, so
         that :app:`Pyramid` can find the underlying asset.
 
         ``subpath`` is the subpath portion of the URL for an incoming request
diff --git a/pyramid/static.py b/pyramid/static.py
index 09743ac15..ab9d47aa5 100644
--- a/pyramid/static.py
+++ b/pyramid/static.py
@@ -166,6 +166,12 @@ def _generate_md5(spec):
     return md5.hexdigest()
 
 def Md5AssetTokenGenerator():
+    """
+    A factory method which returns a function that implements
+    :meth:`~pyramid.interfaces.ICacheBuster.token`.  The function computes and
+    returns md5 checksums for static assets, caching them in memory for speedy
+    retrieval on subsequent calls.
+    """
     token_cache = {}
 
     def generate_token(pathspec):
@@ -189,7 +195,23 @@ def Md5AssetTokenGenerator():
     return generate_token
 
 class PathSegmentCacheBuster(object):
+    """
+    An implementation of :class:`~pyramid.interfaces.ICacheBuster` which
+    inserts a token for cache busting in the path portion of an asset URL.
+
+    The ``token`` argument should be an implementation of
+    :meth:`~pyramid.interfaces.ICacheBuster.token`.  For example, to use
+    this cache buster with an md5 token generator:
 
+    .. code-block:: python
+       :linenos:
+
+       from pyramid.static import (
+           Md5AssetTokenGenerator,
+           PathSegmentCacheBuster)
+
+       cachebuster = PathSegmentCacheBuster(Md5AssetTokenGenerator())
+    """
     def __init__(self, token):
         self.token = token
 
@@ -200,7 +222,26 @@ class PathSegmentCacheBuster(object):
         return subpath[1:]
 
 class QueryStringCacheBuster(object):
+    """
+    An implementation of :class:`~pyramid.interfaces.ICacheBuster` which
+    adds a token for cache busting in the query string of an asset URL.
+
+    The ``token`` argument should be an implementation of
+    :meth:`~pyramid.interfaces.ICacheBuster.token`.  For example, to use
+    this cache buster with an md5 token generator:
+
+    .. code-block:: python
+       :linenos:
 
+       from pyramid.static import (
+           Md5AssetTokenGenerator,
+           PathSegmentCacheBuster)
+
+       cachebuster = QueryStringCacheBuster(Md5AssetTokenGenerator())
+
+    The optional ``param`` argument determines the name of the parameter added
+    to the query string and defaults to ``'x'``.
+    """
     def __init__(self, token, param='x'):
         self.param = param
         self.token = token
-- 
cgit v1.2.3


From 002da7991f4433e5fd5a07489038a6bd2720a526 Mon Sep 17 00:00:00 2001
From: Chris Rossi <chris@archimedeanco.com>
Date: Thu, 17 Jul 2014 16:10:52 -0400
Subject: Add index entry.

---
 docs/narr/assets.rst | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/docs/narr/assets.rst b/docs/narr/assets.rst
index 97d473761..642211f5b 100644
--- a/docs/narr/assets.rst
+++ b/docs/narr/assets.rst
@@ -286,6 +286,9 @@ the application is being run in development or in production (use a different
 suggestion for a pattern; any setting name other than ``media_location``
 could be used.
 
+.. index::
+   single: Cache Busting
+
 .. _cache_busting:
 
 Cache Busting
-- 
cgit v1.2.3


From aa96dda157d39c57c0d2fe8399db0b2175fa83d2 Mon Sep 17 00:00:00 2001
From: Chris Rossi <chris@archimedeanco.com>
Date: Fri, 18 Jul 2014 17:18:56 -0400
Subject: Take mcdonc's advice.  This should be easier for users to understand.

---
 docs/api/static.rst                     |  2 -
 docs/narr/assets.rst                    | 41 +++++++++++++-------
 pyramid/config/views.py                 |  8 +---
 pyramid/static.py                       | 66 ++++++++++-----------------------
 pyramid/tests/test_config/test_views.py | 20 +++++-----
 pyramid/tests/test_static.py            | 46 ++++++++++++++---------
 6 files changed, 87 insertions(+), 96 deletions(-)

diff --git a/docs/api/static.rst b/docs/api/static.rst
index 8ea2fff75..de5bcabda 100644
--- a/docs/api/static.rst
+++ b/docs/api/static.rst
@@ -14,5 +14,3 @@
 
   .. autoclass:: QueryStringCacheBuster
      :members:
-
-  .. autofunction:: Md5AssetTokenGenerator
diff --git a/docs/narr/assets.rst b/docs/narr/assets.rst
index 642211f5b..7987d03a6 100644
--- a/docs/narr/assets.rst
+++ b/docs/narr/assets.rst
@@ -370,28 +370,18 @@ equivalent to:
 .. code-block:: python
    :linenos:
 
-   from pyramid.static import (
-       Md5AssetTokenGenerator,
-       PathSegmentCacheBuster)
+   from pyramid.static import PathSegmentCacheBuster
 
    # config is an instance of pyramid.config.Configurator
-   cachebuster = PathSegmentCacheBuster(Md5AssetTokenGenerator())
    config.add_static_view(name='static', path='mypackage:folder/static',
-                          cachebuster=cachebuster)
+                          cachebuster=PathSegmentCacheBuster())
 
 :app:`Pyramid` includes two ready to use cache buster implementations: 
 :class:`~pyramid.static.PathSegmentCacheBuster`, which inserts an asset token
 in the path portion of the asset's URL, and 
 :class:`~pyramid.static.QueryStringCacheBuster`, which adds an asset token to
-the query string of the asset's URL.  Both of these classes have constructors
-which accept a token generator function as an argument, allowing for the way a
-token is generated to be decoupled from the way it is inserted into a URL.  
-:app:`Pyramid` provides a single asset token generator, 
-:meth:`~pyramid.static.Md5AssetTokenGenerator`.
-
-In order to implement your own cache buster, see the
-:class:`~pyramid.interfaces.ICacheBuster` interface and the existing 
-implementations in the :mod:`~pyramid.static` module.
+the query string of the asset's URL.  Both of these classes generate md5 
+checksums as asset tokens.
 
 .. note::
 
@@ -400,6 +390,29 @@ implementations in the :mod:`~pyramid.static` module.
    :class:`~pyramid.static.PathSegementCacheBuster` to 
    :class:`~pyramid.static.QueryStringCacheBuster`.
 
+In order to implement your own cache buster, you can write your own class from
+scratch which implements the :class:`~pyramid.interfaces.ICacheBuster`
+interface.  Alternatively you may choose to subclass one of the existing
+implementations.  One of the most likely scenarios is you'd want to change the
+way the asset token is generated.  To do this just subclass an existing
+implementation and replace the :meth:`~pyramid.interfaces.ICacheBuster.token`
+method.  Here is an example which just uses a global setting for the asset
+token:
+
+.. code-block:: python
+   :linenos:
+    
+   from pyramid.static import PathSegmentCacheBuster
+
+   class MyCacheBuster(PathSegmentCacheBuster):
+
+       def __init__(self, config):
+           # config is an instance of pyramid.config.Configurator
+           self._token = config.registry.settings['myapp.cachebust_token']
+
+       def token(self, pathspec):
+           return self._token
+
 .. index::
    single: static assets view
 
diff --git a/pyramid/config/views.py b/pyramid/config/views.py
index d74ecfadb..f186a44ae 100644
--- a/pyramid/config/views.py
+++ b/pyramid/config/views.py
@@ -1897,11 +1897,7 @@ def isexception(o):
 @implementer(IStaticURLInfo)
 class StaticURLInfo(object):
     # Indirection for testing
-    _default_cachebuster = staticmethod(PathSegmentCacheBuster)
-    _default_asset_token_generator = staticmethod(Md5AssetTokenGenerator)
-
-    def _make_default_cachebuster(self):
-        return self._default_cachebuster(self._default_asset_token_generator())
+    _default_cachebuster = PathSegmentCacheBuster
 
     def _get_registrations(self, registry):
         try:
@@ -1964,7 +1960,7 @@ class StaticURLInfo(object):
 
         cb = extra.pop('cachebuster', None)
         if cb is True:
-            cb = self._make_default_cachebuster()
+            cb = self._default_cachebuster()
         if cb:
             def cachebuster(subpath, kw):
                 token = cb.token(spec + subpath)
diff --git a/pyramid/static.py b/pyramid/static.py
index ab9d47aa5..34fc3f55c 100644
--- a/pyramid/static.py
+++ b/pyramid/static.py
@@ -165,16 +165,16 @@ def _generate_md5(spec):
             md5.update(block)
     return md5.hexdigest()
 
-def Md5AssetTokenGenerator():
+class Md5AssetTokenGenerator(object):
     """
-    A factory method which returns a function that implements
-    :meth:`~pyramid.interfaces.ICacheBuster.token`.  The function computes and
-    returns md5 checksums for static assets, caching them in memory for speedy
-    retrieval on subsequent calls.
+    A mixin class which provides an implementation of
+    :meth:`~pyramid.interfaces.ICacheBuster.target` which generates an md5
+    checksum token for an asset, caching it for subsequent calls.
     """
-    token_cache = {}
+    def __init__(self):
+        self.token_cache = {}
 
-    def generate_token(pathspec):
+    def token(self, pathspec):
         # An astute observer will notice that this use of token_cache doesn't
         # look particularly thread safe.  Basic read/write operations on Python
         # dicts, however, are atomic, so simply accessing and writing values
@@ -187,64 +187,36 @@ def Md5AssetTokenGenerator():
         # the extra overhead of using locks to serialize access to the dict
         # seems an unnecessary burden.
         #
-        token = token_cache.get(pathspec)
+        token = self.token_cache.get(pathspec)
         if not token:
-            token_cache[pathspec] = token = _generate_md5(pathspec)
+            self.token_cache[pathspec] = token = _generate_md5(pathspec)
         return token
 
-    return generate_token
-
-class PathSegmentCacheBuster(object):
+class PathSegmentCacheBuster(Md5AssetTokenGenerator):
     """
     An implementation of :class:`~pyramid.interfaces.ICacheBuster` which
-    inserts a token for cache busting in the path portion of an asset URL.
-
-    The ``token`` argument should be an implementation of
-    :meth:`~pyramid.interfaces.ICacheBuster.token`.  For example, to use
-    this cache buster with an md5 token generator:
-
-    .. code-block:: python
-       :linenos:
-
-       from pyramid.static import (
-           Md5AssetTokenGenerator,
-           PathSegmentCacheBuster)
-
-       cachebuster = PathSegmentCacheBuster(Md5AssetTokenGenerator())
+    inserts an md5 checksum token for cache busting in the path portion of an
+    asset URL.  Generated md5 checksums are cached in order to speed up
+    subsequent calls.
     """
-    def __init__(self, token):
-        self.token = token
-
     def pregenerate(self, token, subpath, kw):
         return (token,) + subpath, kw
 
     def match(self, subpath):
         return subpath[1:]
 
-class QueryStringCacheBuster(object):
+class QueryStringCacheBuster(Md5AssetTokenGenerator):
     """
-    An implementation of :class:`~pyramid.interfaces.ICacheBuster` which
-    adds a token for cache busting in the query string of an asset URL.
-
-    The ``token`` argument should be an implementation of
-    :meth:`~pyramid.interfaces.ICacheBuster.token`.  For example, to use
-    this cache buster with an md5 token generator:
-
-    .. code-block:: python
-       :linenos:
-
-       from pyramid.static import (
-           Md5AssetTokenGenerator,
-           PathSegmentCacheBuster)
-
-       cachebuster = QueryStringCacheBuster(Md5AssetTokenGenerator())
+    An implementation of :class:`~pyramid.interfaces.ICacheBuster` which adds a
+    token for cache busting in the query string of an asset URL.  Generated md5
+    checksums are cached in order to speed up subsequent calls.
 
     The optional ``param`` argument determines the name of the parameter added
     to the query string and defaults to ``'x'``.
     """
-    def __init__(self, token, param='x'):
+    def __init__(self, param='x'):
+        super(QueryStringCacheBuster, self).__init__()
         self.param = param
-        self.token = token
 
     def pregenerate(self, token, subpath, kw):
         query = kw.setdefault('_query', {})
diff --git a/pyramid/tests/test_config/test_views.py b/pyramid/tests/test_config/test_views.py
index 0b81f5a6f..10a2f6f53 100644
--- a/pyramid/tests/test_config/test_views.py
+++ b/pyramid/tests/test_config/test_views.py
@@ -3944,19 +3944,14 @@ class TestStaticURLInfo(unittest.TestCase):
     def test_add_cachebust_default(self):
         config = self._makeConfig()
         inst = self._makeOne()
-        inst._default_asset_token_generator = lambda: lambda pathspec: 'foo'
+        inst._default_cachebuster = DummyCacheBuster
         inst.add(config, 'view', 'mypackage:path', cachebuster=True)
         cachebuster = config.registry._static_url_registrations[0][3]
-        subpath, _ = cachebuster('some/path', None)
-        self.assertEqual(subpath, 'foo/some/path')
+        subpath, kw = cachebuster('some/path', {})
+        self.assertEqual(subpath, 'some/path')
+        self.assertEqual(kw['x'], 'foo')
 
     def test_add_cachebust_custom(self):
-        class DummyCacheBuster(object):
-            def token(self, pathspec):
-                return 'foo'
-            def pregenerate(self, token, subpath, kw):
-                kw['x'] = token
-                return subpath, kw
         config = self._makeConfig()
         inst = self._makeOne()
         inst.add(config, 'view', 'mypackage:path',
@@ -4071,6 +4066,13 @@ class DummyMultiView:
     def __permitted__(self, context, request):
         """ """
 
+class DummyCacheBuster(object):
+    def token(self, pathspec):
+        return 'foo'
+    def pregenerate(self, token, subpath, kw):
+        kw['x'] = token
+        return subpath, kw
+
 def parse_httpdate(s):
     import datetime
     # cannot use %Z, must use literal GMT; Jython honors timezone
diff --git a/pyramid/tests/test_static.py b/pyramid/tests/test_static.py
index f7b580df2..6ae9b13db 100644
--- a/pyramid/tests/test_static.py
+++ b/pyramid/tests/test_static.py
@@ -369,29 +369,33 @@ class Test_static_view_use_subpath_True(unittest.TestCase):
         self.assertRaises(HTTPNotFound, inst, context, request)
 
 class TestMd5AssetTokenGenerator(unittest.TestCase):
+    _fspath = None
+
+    @property
+    def fspath(self):
+        if self._fspath:
+            return self._fspath
 
-    def setUp(self):
         import os
         import tempfile
-        self.tmp = tempfile.mkdtemp()
-        self.fspath = os.path.join(self.tmp, 'test.txt')
-
-    def tearDown(self):
         import shutil
-        shutil.rmtree(self.tmp)
+        tmp = tempfile.mkdtemp()
+        self.addCleanup(lambda: shutil.rmtree(tmp))
+        self._fspath = os.path.join(tmp, 'test.txt')
+        return self._fspath
 
     def _makeOne(self):
-        from pyramid.static import Md5AssetTokenGenerator as unit
-        return unit()
+        from pyramid.static import Md5AssetTokenGenerator as cls
+        return cls()
 
     def test_package_resource(self):
-        fut = self._makeOne()
+        fut = self._makeOne().token
         expected = '76d653a3a044e2f4b38bb001d283e3d9'
         token = fut('pyramid.tests:fixtures/static/index.html')
         self.assertEqual(token, expected)
 
     def test_filesystem_resource(self):
-        fut = self._makeOne()
+        fut = self._makeOne().token
         expected = 'd5155f250bef0e9923e894dbc713c5dd'
         with open(self.fspath, 'w') as f:
             f.write("Are we rich yet?")
@@ -399,7 +403,7 @@ class TestMd5AssetTokenGenerator(unittest.TestCase):
         self.assertEqual(token, expected)
 
     def test_cache(self):
-        fut = self._makeOne()
+        fut = self._makeOne().token
         expected = 'd5155f250bef0e9923e894dbc713c5dd'
         with open(self.fspath, 'w') as f:
             f.write("Are we rich yet?")
@@ -415,8 +419,10 @@ class TestMd5AssetTokenGenerator(unittest.TestCase):
 class TestPathSegmentCacheBuster(unittest.TestCase):
 
     def _makeOne(self):
-        from pyramid.static import PathSegmentCacheBuster as unit
-        return unit(lambda pathspec: 'foo')
+        from pyramid.static import PathSegmentCacheBuster as cls
+        inst = cls()
+        inst.token = lambda pathspec: 'foo'
+        return inst
 
     def test_token(self):
         fut = self._makeOne().token
@@ -432,9 +438,14 @@ class TestPathSegmentCacheBuster(unittest.TestCase):
 
 class TestQueryStringCacheBuster(unittest.TestCase):
 
-    def _makeOne(self):
-        from pyramid.static import QueryStringCacheBuster as unit
-        return unit(lambda pathspec: 'foo')
+    def _makeOne(self, param=None):
+        from pyramid.static import QueryStringCacheBuster as cls
+        if param:
+            inst = cls(param)
+        else:
+            inst = cls()
+        inst.token = lambda pathspec: 'foo'
+        return inst
 
     def test_token(self):
         fut = self._makeOne().token
@@ -447,8 +458,7 @@ class TestQueryStringCacheBuster(unittest.TestCase):
             (('bar',), {'_query': {'x': 'foo'}}))
 
     def test_pregenerate_change_param(self):
-        from pyramid.static import QueryStringCacheBuster as unit
-        fut = unit(lambda pathspec: 'foo', 'y').pregenerate
+        fut = self._makeOne('y').pregenerate
         self.assertEqual(
             fut('foo', ('bar',), {}),
             (('bar',), {'_query': {'y': 'foo'}}))
-- 
cgit v1.2.3


From 6596304446f8369dfbcf264d143fe85d75832dba Mon Sep 17 00:00:00 2001
From: Chris Rossi <chris@archimedeanco.com>
Date: Mon, 21 Jul 2014 16:46:35 -0400
Subject: Add 'prevent_cachebuster' setting.

---
 docs/narr/assets.rst                       | 11 ++++++++++-
 docs/narr/environment.rst                  | 20 +++++++++++++++++++
 pyramid/config/settings.py                 |  9 ++++++++-
 pyramid/config/views.py                    | 12 ++++++------
 pyramid/tests/test_config/test_settings.py | 31 +++++++++++++++++++++++++++++-
 pyramid/tests/test_config/test_views.py    | 11 ++++++++++-
 6 files changed, 84 insertions(+), 10 deletions(-)

diff --git a/docs/narr/assets.rst b/docs/narr/assets.rst
index 7987d03a6..fea3fae48 100644
--- a/docs/narr/assets.rst
+++ b/docs/narr/assets.rst
@@ -349,6 +349,15 @@ headers instructing clients to cache the asset for ten years, unless the
    restarting your application, you may still generate URLs with a stale md5
    checksum. 
 
+Disabling the Cache Buster
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+It can be useful in some situations (e.g. development) to globally disable all
+configured cache busters without changing calls to
+:meth:`~pyramid.config.Configurator.add_static_view`.  To do this set the 
+``PYRAMID_PREVENT_CACHEBUSTER`` environment variable or the 
+``pyramid.prevent_cachebuster`` configuration value to a true value.
+
 Customizing the Cache Buster
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -387,7 +396,7 @@ checksums as asset tokens.
 
    Many HTTP caching proxy implementations will fail to cache any URL which
    has a query string. For this reason, you should probably prefer 
-   :class:`~pyramid.static.PathSegementCacheBuster` to 
+   :class:`~pyramid.static.PathSegmentCacheBuster` to 
    :class:`~pyramid.static.QueryStringCacheBuster`.
 
 In order to implement your own cache buster, you can write your own class from
diff --git a/docs/narr/environment.rst b/docs/narr/environment.rst
index 412635f08..7e2f19278 100644
--- a/docs/narr/environment.rst
+++ b/docs/narr/environment.rst
@@ -158,6 +158,26 @@ feature when this is true.
 |                                 |                                  |
 +---------------------------------+----------------------------------+
 
+Preventing Cache Busting
+------------------------
+
+Prevent the ``cachebuster`` static view configuration argument from having any
+effect globally in this process when this value is true.  No cache buster will
+be configured or used when this is true.  
+
+.. seealso::
+
+    See also :ref:`cache_busting`.
+
++---------------------------------+----------------------------------+
+| Environment Variable Name       | Config File Setting Name         |
++=================================+==================================+
+| ``PYRAMID_PREVENT_CACHEBUSTER`` |  ``pyramid.prevent_cachebuster`` |
+|                                 |  or ``prevent_cachebuster``      |
+|                                 |                                  |
+|                                 |                                  |
++---------------------------------+----------------------------------+
+
 Debugging All
 -------------
 
diff --git a/pyramid/config/settings.py b/pyramid/config/settings.py
index 565a6699c..4d7af6015 100644
--- a/pyramid/config/settings.py
+++ b/pyramid/config/settings.py
@@ -17,7 +17,7 @@ class SettingsConfiguratorMixin(object):
 
     def add_settings(self, settings=None, **kw):
         """Augment the :term:`deployment settings` with one or more
-        key/value pairs. 
+        key/value pairs.
 
         You may pass a dictionary::
 
@@ -117,6 +117,11 @@ class Settings(dict):
                                              config_prevent_http_cache)
         eff_prevent_http_cache = asbool(eget('PYRAMID_PREVENT_HTTP_CACHE',
                                              config_prevent_http_cache))
+        config_prevent_cachebuster = self.get('prevent_cachebuster', '')
+        config_prevent_cachebuster = self.get('pyramid.prevent_cachebuster',
+                                             config_prevent_cachebuster)
+        eff_prevent_cachebuster = asbool(eget('PYRAMID_PREVENT_CACHEBUSTER',
+                                             config_prevent_cachebuster))
 
         update = {
             'debug_authorization': eff_debug_all or eff_debug_auth,
@@ -128,6 +133,7 @@ class Settings(dict):
             'reload_assets':eff_reload_all or eff_reload_assets,
             'default_locale_name':eff_locale_name,
             'prevent_http_cache':eff_prevent_http_cache,
+            'prevent_cachebuster':eff_prevent_cachebuster,
 
             'pyramid.debug_authorization': eff_debug_all or eff_debug_auth,
             'pyramid.debug_notfound': eff_debug_all or eff_debug_notfound,
@@ -138,6 +144,7 @@ class Settings(dict):
             'pyramid.reload_assets':eff_reload_all or eff_reload_assets,
             'pyramid.default_locale_name':eff_locale_name,
             'pyramid.prevent_http_cache':eff_prevent_http_cache,
+            'pyramid.prevent_cachebuster':eff_prevent_cachebuster,
             }
 
         self.update(update)
diff --git a/pyramid/config/views.py b/pyramid/config/views.py
index f186a44ae..62feca77e 100644
--- a/pyramid/config/views.py
+++ b/pyramid/config/views.py
@@ -34,10 +34,7 @@ from pyramid.interfaces import (
     )
 
 from pyramid import renderers
-from pyramid.static import (
-    Md5AssetTokenGenerator,
-    PathSegmentCacheBuster,
-)
+from pyramid.static import PathSegmentCacheBuster
 
 from pyramid.compat import (
     string_types,
@@ -1786,7 +1783,7 @@ class ViewsConfiguratorMixin(object):
         Note that this argument has no effect when the ``name`` is a *url
         prefix*.  By default, this argument is ``None``, meaning that no
         particular Expires or Cache-Control headers are set in the response,
-        unless ``cache_bust`` is specified.
+        unless ``cachebuster`` is specified.
 
         The ``cachebuster`` keyword argument may be set to cause
         :meth:`~pyramid.request.Request.static_url` to use cache busting when
@@ -1958,7 +1955,10 @@ class StaticURLInfo(object):
             # make sure it ends with a slash
             name = name + '/'
 
-        cb = extra.pop('cachebuster', None)
+        if config.registry.settings.get('pyramid.prevent_cachebuster'):
+            cb = None
+        else:
+            cb = extra.pop('cachebuster', None)
         if cb is True:
             cb = self._default_cachebuster()
         if cb:
diff --git a/pyramid/tests/test_config/test_settings.py b/pyramid/tests/test_config/test_settings.py
index c74f96375..7cf550c1d 100644
--- a/pyramid/tests/test_config/test_settings.py
+++ b/pyramid/tests/test_config/test_settings.py
@@ -57,7 +57,7 @@ class TestSettingsConfiguratorMixin(unittest.TestCase):
         self.assertEqual(settings['a'], 1)
 
 class TestSettings(unittest.TestCase):
-        
+
     def _getTargetClass(self):
         from pyramid.config.settings import Settings
         return Settings
@@ -131,6 +131,35 @@ class TestSettings(unittest.TestCase):
         self.assertEqual(result['prevent_http_cache'], True)
         self.assertEqual(result['pyramid.prevent_http_cache'], True)
 
+    def test_prevent_cachebuster(self):
+        settings = self._makeOne({})
+        self.assertEqual(settings['prevent_cachebuster'], False)
+        self.assertEqual(settings['pyramid.prevent_cachebuster'], False)
+        result = self._makeOne({'prevent_cachebuster':'false'})
+        self.assertEqual(result['prevent_cachebuster'], False)
+        self.assertEqual(result['pyramid.prevent_cachebuster'], False)
+        result = self._makeOne({'prevent_cachebuster':'t'})
+        self.assertEqual(result['prevent_cachebuster'], True)
+        self.assertEqual(result['pyramid.prevent_cachebuster'], True)
+        result = self._makeOne({'prevent_cachebuster':'1'})
+        self.assertEqual(result['prevent_cachebuster'], True)
+        self.assertEqual(result['pyramid.prevent_cachebuster'], True)
+        result = self._makeOne({'pyramid.prevent_cachebuster':'t'})
+        self.assertEqual(result['prevent_cachebuster'], True)
+        self.assertEqual(result['pyramid.prevent_cachebuster'], True)
+        result = self._makeOne({}, {'PYRAMID_PREVENT_CACHEBUSTER':'1'})
+        self.assertEqual(result['prevent_cachebuster'], True)
+        self.assertEqual(result['pyramid.prevent_cachebuster'], True)
+        result = self._makeOne({'prevent_cachebuster':'false',
+                                'pyramid.prevent_cachebuster':'1'})
+        self.assertEqual(result['prevent_cachebuster'], True)
+        self.assertEqual(result['pyramid.prevent_cachebuster'], True)
+        result = self._makeOne({'prevent_cachebuster':'false',
+                                'pyramid.prevent_cachebuster':'f'},
+                               {'PYRAMID_PREVENT_CACHEBUSTER':'1'})
+        self.assertEqual(result['prevent_cachebuster'], True)
+        self.assertEqual(result['pyramid.prevent_cachebuster'], True)
+
     def test_reload_templates(self):
         settings = self._makeOne({})
         self.assertEqual(settings['reload_templates'], False)
diff --git a/pyramid/tests/test_config/test_views.py b/pyramid/tests/test_config/test_views.py
index 10a2f6f53..8f600c1d2 100644
--- a/pyramid/tests/test_config/test_views.py
+++ b/pyramid/tests/test_config/test_views.py
@@ -3951,6 +3951,14 @@ class TestStaticURLInfo(unittest.TestCase):
         self.assertEqual(subpath, 'some/path')
         self.assertEqual(kw['x'], 'foo')
 
+    def test_add_cachebust_prevented(self):
+        config = self._makeConfig()
+        config.registry.settings['pyramid.prevent_cachebuster'] = True
+        inst = self._makeOne()
+        inst.add(config, 'view', 'mypackage:path', cachebuster=True)
+        cachebuster = config.registry._static_url_registrations[0][3]
+        self.assertEqual(cachebuster, None)
+
     def test_add_cachebust_custom(self):
         config = self._makeConfig()
         inst = self._makeOne()
@@ -3980,7 +3988,8 @@ class Test_view_description(unittest.TestCase):
 
 
 class DummyRegistry:
-    pass
+    def __init__(self):
+        self.settings = {}
 
 from zope.interface import implementer
 from pyramid.interfaces import IResponse
-- 
cgit v1.2.3


From 026e292aa8d6da7a2e62eab05d8ceb5f061ac44e Mon Sep 17 00:00:00 2001
From: Chris Rossi <chris@archimedeanco.com>
Date: Mon, 21 Jul 2014 17:26:17 -0400
Subject: Fix tests on py26.

---
 pyramid/tests/test_static.py | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)

diff --git a/pyramid/tests/test_static.py b/pyramid/tests/test_static.py
index 6ae9b13db..aca5c4bbd 100644
--- a/pyramid/tests/test_static.py
+++ b/pyramid/tests/test_static.py
@@ -370,6 +370,7 @@ class Test_static_view_use_subpath_True(unittest.TestCase):
 
 class TestMd5AssetTokenGenerator(unittest.TestCase):
     _fspath = None
+    _tmp = None
 
     @property
     def fspath(self):
@@ -378,12 +379,15 @@ class TestMd5AssetTokenGenerator(unittest.TestCase):
 
         import os
         import tempfile
-        import shutil
-        tmp = tempfile.mkdtemp()
-        self.addCleanup(lambda: shutil.rmtree(tmp))
+        self._tmp = tmp = tempfile.mkdtemp()
         self._fspath = os.path.join(tmp, 'test.txt')
         return self._fspath
 
+    def tearDown(self):
+        import shutil
+        if self._tmp:
+            shutil.rmtree(self._tmp)
+
     def _makeOne(self):
         from pyramid.static import Md5AssetTokenGenerator as cls
         return cls()
-- 
cgit v1.2.3


From 9177d010e6646161e674b82b88bf177ebe8a7b2e Mon Sep 17 00:00:00 2001
From: Chris Rossi <chris@archimedeanco.com>
Date: Mon, 21 Jul 2014 17:29:11 -0400
Subject: Update change log.

---
 CHANGES.txt | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/CHANGES.txt b/CHANGES.txt
index 51af8ee01..54c1a20ed 100644
--- a/CHANGES.txt
+++ b/CHANGES.txt
@@ -1,6 +1,12 @@
 Next release
 ============
 
+Features
+--------
+
+- Cache busting for static resources has been added and is available via a new
+  argument to ``pyramid.config.Configurator.add_static_view``: ``cachebuster``.
+
 Bug Fixes
 ---------
 
-- 
cgit v1.2.3


From 40c6bfa85a75ffacf23a3ccd128dc5b8bb57a464 Mon Sep 17 00:00:00 2001
From: Chris Rossi <chris@archimedeanco.com>
Date: Tue, 22 Jul 2014 09:28:17 -0400
Subject: Forgot to update interface docs earlier.

---
 pyramid/interfaces.py | 74 ++++++++++++++++-----------------------------------
 1 file changed, 23 insertions(+), 51 deletions(-)

diff --git a/pyramid/interfaces.py b/pyramid/interfaces.py
index f3d7b1798..2b6ba7eb6 100644
--- a/pyramid/interfaces.py
+++ b/pyramid/interfaces.py
@@ -1166,65 +1166,37 @@ class IPredicateList(Interface):
 
 class ICacheBuster(Interface):
     """
-    A container for functions which implement a cache busting policy for
-    serving static assets.
-
-    The implementations provided by :app:`Pyramid` use standard instance
-    methods for ``pregenerate`` and ``match``, while accepting an
-    implementation of ``token`` as an argument to their constructor.  This
-    pattern allows for the decoupling of how a token is generated and how it is
-    inserted into a URL.  For examples see the :mod:`~pyramid.static` module.
+    Instances of ``ICacheBuster`` may be provided as arguments to
+    :meth:`~pyramid.config.Configurator.add_static_view`.  Instances of
+    ``ICacheBuster`` provide mechanisms for generating a cache bust token for
+    a static asset, modifying a static asset URL to include a cache bust token,
+    and, optionally, unmodifying a static asset URL in order to look up an
+    asset.  See :ref:`cache_busting`.
     """
     def token(pathspec):
         """
-        A function which computes and returns a token string used for cache
-        busting.  ``pathspec`` is the path specification for the resource to be
-        cache busted.  Often a cachebust token might be computed for a specific
-        asset (e.g. an md5 checksum), but probably just as often people use
-        schemes where a single cachebust token is used globally.  It could be a
-        git commit sha1, a timestamp, or something configured manually. A
-        pattern that can be useful is to use to a factory function and a
-        closure to return a function that depends on some configuration.  For
-        example:
-
-        .. code-block:: python
-           :linenos:
-
-           def use_configured_cachebust_token(config):
-               # config is an instance of pyramid.config.Configurator
-               token = config.registry.settings['myapp.cachebust_token']
-               def cachebust_token(pathspec):
-                   return token
-               return cachebust_token
-        """
+        Computes and returns a token string used for cache busting.
+        ``pathspec`` is the path specification for the resource to be cache
+        busted.  """
 
     def pregenerate(token, subpath, kw):
         """
-        A function which modifies a subpath and/or keyword arguments from which
-        a static asset URL will be computed during URL generation.  The
-        ``token`` argument is a token string computed by an instance of
-        :meth:`~pyramid.interfaces.ICacheBuster.token` for a particular
-        asset.  The ``subpath`` argument is a tuple of path elements that
-        represent the portion of the asset URL which is used to find the asset.
-        The ``kw`` argument is a dict of keywords that are to be passed
-        eventually to :meth:`~pyramid.request.Request.route_url` for URL
-        generation.  The return value of this function should be two-tuple of
-        ``(subpath, kw)`` which are versions of the same arguments modified to
-        include the cachebust token in the generated URL.
-
-        Here is an example which places the token in a query string:
-
-        .. code-block:: python
-           :linenos:
-
-           def cb_pregen(token, subpath kw):
-               kw.setdefault('_query', {})['cb'] = token
-               return subpath, kw
+        Modifies a subpath and/or keyword arguments from which a static asset
+        URL will be computed during URL generation.  The ``token`` argument is
+        a token string computed by
+        :meth:`~pyramid.interfaces.ICacheBuster.token` for a particular asset.
+        The ``subpath`` argument is a tuple of path elements that represent the
+        portion of the asset URL which is used to find the asset.  The ``kw``
+        argument is a dict of keywords that are to be passed eventually to
+        :meth:`~pyramid.request.Request.route_url` for URL generation.  The
+        return value should be a two-tuple of ``(subpath, kw)`` which are
+        versions of the same arguments modified to include the cachebust token
+        in the generated URL.
         """
 
     def match(subpath):
         """
-        A function which performs the logical inverse of
+        Performs the logical inverse of
         :meth:`~pyramid.interfaces.ICacheBuster.pregenerate` by taking a
         subpath from a cache busted URL and removing the cache bust token, so
         that :app:`Pyramid` can find the underlying asset.
@@ -1234,10 +1206,10 @@ class ICacheBuster(Interface):
         cache busting token elided.
 
         If the cache busting scheme in use doesn't specifically modify the path
-        portion of the generated URL (e.g. it adds a query string), a function
+        portion of the generated URL (e.g. it adds a query string), a method
         which implements this interface may not be necessary.  It is
         permissible for an instance of
-        :class:`~pyramid.interfaces.ICacheBuster` to omit this function.
+        :class:`~pyramid.interfaces.ICacheBuster` to omit this method.
         """
 
 # configuration phases: a lower phase number means the actions associated
-- 
cgit v1.2.3


From 4d32f73a86e7223dbdb96b39193d357b38ea1a13 Mon Sep 17 00:00:00 2001
From: Chris Rossi <chris@archimedeanco.com>
Date: Tue, 22 Jul 2014 10:00:47 -0400
Subject: Make sure any sequence type works with _query.

---
 pyramid/static.py            | 2 +-
 pyramid/tests/test_static.py | 8 +++++++-
 2 files changed, 8 insertions(+), 2 deletions(-)

diff --git a/pyramid/static.py b/pyramid/static.py
index 34fc3f55c..0cbb5533f 100644
--- a/pyramid/static.py
+++ b/pyramid/static.py
@@ -223,7 +223,7 @@ class QueryStringCacheBuster(Md5AssetTokenGenerator):
         if isinstance(query, dict):
             query[self.param] = token
         else:
-            kw['_query'] = query + [(self.param, token)]
+            kw['_query'] = tuple(query) + ((self.param, token),)
         return subpath, kw
 
 
diff --git a/pyramid/tests/test_static.py b/pyramid/tests/test_static.py
index aca5c4bbd..134bea25e 100644
--- a/pyramid/tests/test_static.py
+++ b/pyramid/tests/test_static.py
@@ -471,7 +471,13 @@ class TestQueryStringCacheBuster(unittest.TestCase):
         fut = self._makeOne().pregenerate
         self.assertEqual(
             fut('foo', ('bar',), {'_query': [('a', 'b')]}),
-            (('bar',), {'_query': [('a', 'b'), ('x', 'foo')]}))
+            (('bar',), {'_query': (('a', 'b'), ('x', 'foo'))}))
+
+    def test_pregenerate_query_is_tuple_of_tuples(self):
+        fut = self._makeOne().pregenerate
+        self.assertEqual(
+            fut('foo', ('bar',), {'_query': (('a', 'b'),)}),
+            (('bar',), {'_query': (('a', 'b'), ('x', 'foo'))}))
 
 class DummyContext:
     pass
-- 
cgit v1.2.3


From 15b979413c700fbc289328b25aaa4ba1c4cbdda9 Mon Sep 17 00:00:00 2001
From: Chris Rossi <chris@archimedeanco.com>
Date: Thu, 24 Jul 2014 17:13:08 -0400
Subject: cachebuster -> cachebust

---
 CHANGES.txt                                |  2 +-
 docs/narr/assets.rst                       | 20 +++++------
 docs/narr/environment.rst                  |  6 ++--
 pyramid/config/settings.py                 | 14 ++++----
 pyramid/config/views.py                    | 30 ++++++++---------
 pyramid/tests/test_config/test_settings.py | 54 +++++++++++++++---------------
 pyramid/tests/test_config/test_views.py    | 28 ++++++++--------
 7 files changed, 77 insertions(+), 77 deletions(-)

diff --git a/CHANGES.txt b/CHANGES.txt
index 54c1a20ed..63987d980 100644
--- a/CHANGES.txt
+++ b/CHANGES.txt
@@ -5,7 +5,7 @@ Features
 --------
 
 - Cache busting for static resources has been added and is available via a new
-  argument to ``pyramid.config.Configurator.add_static_view``: ``cachebuster``.
+  argument to ``pyramid.config.Configurator.add_static_view``: ``cachebust``.
 
 Bug Fixes
 ---------
diff --git a/docs/narr/assets.rst b/docs/narr/assets.rst
index fea3fae48..7fb0ec40b 100644
--- a/docs/narr/assets.rst
+++ b/docs/narr/assets.rst
@@ -318,7 +318,7 @@ requests a copy, regardless of any caching policy set for the resource's old
 URL.
 
 :app:`Pyramid` can be configured to produce cache busting URLs for static 
-assets by passing the optional argument, ``cachebuster`` to 
+assets by passing the optional argument, ``cachebust`` to 
 :meth:`~pyramid.config.Configurator.add_static_view`:
 
 .. code-block:: python
@@ -326,9 +326,9 @@ assets by passing the optional argument, ``cachebuster`` to
 
    # config is an instance of pyramid.config.Configurator
    config.add_static_view(name='static', path='mypackage:folder/static',
-                          cachebuster=True)
+                          cachebust=True)
 
-Setting the ``cachebuster`` argument instructs :app:`Pyramid` to use a cache 
+Setting the ``cachebust`` argument instructs :app:`Pyramid` to use a cache 
 busting scheme which adds the md5 checksum for a static asset as a path segment
 in the asset's URL:
 
@@ -339,7 +339,7 @@ in the asset's URL:
    # Returns: 'http://www.example.com/static/c9658b3c0a314a1ca21e5988e662a09e/js/myapp.js`
 
 When the asset changes, so will its md5 checksum, and therefore so will its
-URL.  Supplying the ``cachebuster`` argument also causes the static view to set
+URL.  Supplying the ``cachebust`` argument also causes the static view to set
 headers instructing clients to cache the asset for ten years, unless the
 ``max_cache_age`` argument is also passed, in which case that value is used.
 
@@ -355,8 +355,8 @@ Disabling the Cache Buster
 It can be useful in some situations (e.g. development) to globally disable all
 configured cache busters without changing calls to
 :meth:`~pyramid.config.Configurator.add_static_view`.  To do this set the 
-``PYRAMID_PREVENT_CACHEBUSTER`` environment variable or the 
-``pyramid.prevent_cachebuster`` configuration value to a true value.
+``PYRAMID_PREVENT_CACHEBUST`` environment variable or the 
+``pyramid.prevent_cachebust`` configuration value to a true value.
 
 Customizing the Cache Buster
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -368,11 +368,11 @@ Revisiting from the previous section:
 
    # config is an instance of pyramid.config.Configurator
    config.add_static_view(name='static', path='mypackage:folder/static',
-                          cachebuster=True)
+                          cachebust=True)
 
-Setting ``cachebuster`` to ``True`` instructs :app:`Pyramid` to use a default
+Setting ``cachebust`` to ``True`` instructs :app:`Pyramid` to use a default
 cache busting implementation that should work for many situations.  The 
-``cachebuster`` may be set to any object that implements the interface,
+``cachebust`` may be set to any object that implements the interface,
 :class:`~pyramid.interfaces.ICacheBuster`.  The above configuration is exactly
 equivalent to:
 
@@ -383,7 +383,7 @@ equivalent to:
 
    # config is an instance of pyramid.config.Configurator
    config.add_static_view(name='static', path='mypackage:folder/static',
-                          cachebuster=PathSegmentCacheBuster())
+                          cachebust=PathSegmentCacheBuster())
 
 :app:`Pyramid` includes two ready to use cache buster implementations: 
 :class:`~pyramid.static.PathSegmentCacheBuster`, which inserts an asset token
diff --git a/docs/narr/environment.rst b/docs/narr/environment.rst
index 7e2f19278..a81ad19af 100644
--- a/docs/narr/environment.rst
+++ b/docs/narr/environment.rst
@@ -161,7 +161,7 @@ feature when this is true.
 Preventing Cache Busting
 ------------------------
 
-Prevent the ``cachebuster`` static view configuration argument from having any
+Prevent the ``cachebust`` static view configuration argument from having any
 effect globally in this process when this value is true.  No cache buster will
 be configured or used when this is true.  
 
@@ -172,8 +172,8 @@ be configured or used when this is true.
 +---------------------------------+----------------------------------+
 | Environment Variable Name       | Config File Setting Name         |
 +=================================+==================================+
-| ``PYRAMID_PREVENT_CACHEBUSTER`` |  ``pyramid.prevent_cachebuster`` |
-|                                 |  or ``prevent_cachebuster``      |
+| ``PYRAMID_PREVENT_CACHEBUST``   |  ``pyramid.prevent_cachebust``   |
+|                                 |  or ``prevent_cachebust``        |
 |                                 |                                  |
 |                                 |                                  |
 +---------------------------------+----------------------------------+
diff --git a/pyramid/config/settings.py b/pyramid/config/settings.py
index 4d7af6015..492b7d524 100644
--- a/pyramid/config/settings.py
+++ b/pyramid/config/settings.py
@@ -117,11 +117,11 @@ class Settings(dict):
                                              config_prevent_http_cache)
         eff_prevent_http_cache = asbool(eget('PYRAMID_PREVENT_HTTP_CACHE',
                                              config_prevent_http_cache))
-        config_prevent_cachebuster = self.get('prevent_cachebuster', '')
-        config_prevent_cachebuster = self.get('pyramid.prevent_cachebuster',
-                                             config_prevent_cachebuster)
-        eff_prevent_cachebuster = asbool(eget('PYRAMID_PREVENT_CACHEBUSTER',
-                                             config_prevent_cachebuster))
+        config_prevent_cachebust = self.get('prevent_cachebust', '')
+        config_prevent_cachebust = self.get('pyramid.prevent_cachebust',
+                                             config_prevent_cachebust)
+        eff_prevent_cachebust = asbool(eget('PYRAMID_PREVENT_CACHEBUST',
+                                             config_prevent_cachebust))
 
         update = {
             'debug_authorization': eff_debug_all or eff_debug_auth,
@@ -133,7 +133,7 @@ class Settings(dict):
             'reload_assets':eff_reload_all or eff_reload_assets,
             'default_locale_name':eff_locale_name,
             'prevent_http_cache':eff_prevent_http_cache,
-            'prevent_cachebuster':eff_prevent_cachebuster,
+            'prevent_cachebust':eff_prevent_cachebust,
 
             'pyramid.debug_authorization': eff_debug_all or eff_debug_auth,
             'pyramid.debug_notfound': eff_debug_all or eff_debug_notfound,
@@ -144,7 +144,7 @@ class Settings(dict):
             'pyramid.reload_assets':eff_reload_all or eff_reload_assets,
             'pyramid.default_locale_name':eff_locale_name,
             'pyramid.prevent_http_cache':eff_prevent_http_cache,
-            'pyramid.prevent_cachebuster':eff_prevent_cachebuster,
+            'pyramid.prevent_cachebust':eff_prevent_cachebust,
             }
 
         self.update(update)
diff --git a/pyramid/config/views.py b/pyramid/config/views.py
index 62feca77e..e6c5baf58 100644
--- a/pyramid/config/views.py
+++ b/pyramid/config/views.py
@@ -1783,17 +1783,17 @@ class ViewsConfiguratorMixin(object):
         Note that this argument has no effect when the ``name`` is a *url
         prefix*.  By default, this argument is ``None``, meaning that no
         particular Expires or Cache-Control headers are set in the response,
-        unless ``cachebuster`` is specified.
+        unless ``cachebust`` is specified.
 
-        The ``cachebuster`` keyword argument may be set to cause
+        The ``cachebust`` keyword argument may be set to cause
         :meth:`~pyramid.request.Request.static_url` to use cache busting when
         generating URLs. See :ref:`cache_busting` for general information
-        about cache busting.  The value of the ``cachebuster`` argument may be
+        about cache busting.  The value of the ``cachebust`` argument may be
         ``True``, in which case a default cache busting implementation is used.
-        The value of the ``cachebuster`` argument may also be an object which
+        The value of the ``cachebust`` argument may also be an object which
         implements :class:`~pyramid.interfaces.ICacheBuster`.  See the
         :mod:`~pyramid.static` module for some implementations.  If the
-        ``cachebuster`` argument is provided, the default for ``cache_max_age``
+        ``cachebust`` argument is provided, the default for ``cache_max_age``
         is modified to be ten years.  ``cache_max_age`` may still be explicitly
         provided to override this default.
 
@@ -1894,7 +1894,7 @@ def isexception(o):
 @implementer(IStaticURLInfo)
 class StaticURLInfo(object):
     # Indirection for testing
-    _default_cachebuster = PathSegmentCacheBuster
+    _default_cachebust = PathSegmentCacheBuster
 
     def _get_registrations(self, registry):
         try:
@@ -1909,13 +1909,13 @@ class StaticURLInfo(object):
         except AttributeError: # bw compat (for tests)
             registry = get_current_registry()
         registrations = self._get_registrations(registry)
-        for (url, spec, route_name, cachebuster) in registrations:
+        for (url, spec, route_name, cachebust) in registrations:
             if path.startswith(spec):
                 subpath = path[len(spec):]
                 if WIN: # pragma: no cover
                     subpath = subpath.replace('\\', '/') # windows
-                if cachebuster:
-                    subpath, kw = cachebuster(subpath, kw)
+                if cachebust:
+                    subpath, kw = cachebust(subpath, kw)
                 if url is None:
                     kw['subpath'] = subpath
                     return request.route_url(route_name, **kw)
@@ -1955,20 +1955,20 @@ class StaticURLInfo(object):
             # make sure it ends with a slash
             name = name + '/'
 
-        if config.registry.settings.get('pyramid.prevent_cachebuster'):
+        if config.registry.settings.get('pyramid.prevent_cachebust'):
             cb = None
         else:
-            cb = extra.pop('cachebuster', None)
+            cb = extra.pop('cachebust', None)
         if cb is True:
-            cb = self._default_cachebuster()
+            cb = self._default_cachebust()
         if cb:
-            def cachebuster(subpath, kw):
+            def cachebust(subpath, kw):
                 token = cb.token(spec + subpath)
                 subpath_tuple = tuple(subpath.split('/'))
                 subpath_tuple, kw = cb.pregenerate(token, subpath_tuple, kw)
                 return '/'.join(subpath_tuple), kw
         else:
-            cachebuster = None
+            cachebust = None
 
         if url_parse(name).netloc:
             # it's a URL
@@ -2026,7 +2026,7 @@ class StaticURLInfo(object):
                 registrations.pop(idx)
 
             # url, spec, route_name
-            registrations.append((url, spec, route_name, cachebuster))
+            registrations.append((url, spec, route_name, cachebust))
 
         intr = config.introspectable('static views',
                                      name,
diff --git a/pyramid/tests/test_config/test_settings.py b/pyramid/tests/test_config/test_settings.py
index 7cf550c1d..d2a98b347 100644
--- a/pyramid/tests/test_config/test_settings.py
+++ b/pyramid/tests/test_config/test_settings.py
@@ -131,34 +131,34 @@ class TestSettings(unittest.TestCase):
         self.assertEqual(result['prevent_http_cache'], True)
         self.assertEqual(result['pyramid.prevent_http_cache'], True)
 
-    def test_prevent_cachebuster(self):
+    def test_prevent_cachebust(self):
         settings = self._makeOne({})
-        self.assertEqual(settings['prevent_cachebuster'], False)
-        self.assertEqual(settings['pyramid.prevent_cachebuster'], False)
-        result = self._makeOne({'prevent_cachebuster':'false'})
-        self.assertEqual(result['prevent_cachebuster'], False)
-        self.assertEqual(result['pyramid.prevent_cachebuster'], False)
-        result = self._makeOne({'prevent_cachebuster':'t'})
-        self.assertEqual(result['prevent_cachebuster'], True)
-        self.assertEqual(result['pyramid.prevent_cachebuster'], True)
-        result = self._makeOne({'prevent_cachebuster':'1'})
-        self.assertEqual(result['prevent_cachebuster'], True)
-        self.assertEqual(result['pyramid.prevent_cachebuster'], True)
-        result = self._makeOne({'pyramid.prevent_cachebuster':'t'})
-        self.assertEqual(result['prevent_cachebuster'], True)
-        self.assertEqual(result['pyramid.prevent_cachebuster'], True)
-        result = self._makeOne({}, {'PYRAMID_PREVENT_CACHEBUSTER':'1'})
-        self.assertEqual(result['prevent_cachebuster'], True)
-        self.assertEqual(result['pyramid.prevent_cachebuster'], True)
-        result = self._makeOne({'prevent_cachebuster':'false',
-                                'pyramid.prevent_cachebuster':'1'})
-        self.assertEqual(result['prevent_cachebuster'], True)
-        self.assertEqual(result['pyramid.prevent_cachebuster'], True)
-        result = self._makeOne({'prevent_cachebuster':'false',
-                                'pyramid.prevent_cachebuster':'f'},
-                               {'PYRAMID_PREVENT_CACHEBUSTER':'1'})
-        self.assertEqual(result['prevent_cachebuster'], True)
-        self.assertEqual(result['pyramid.prevent_cachebuster'], True)
+        self.assertEqual(settings['prevent_cachebust'], False)
+        self.assertEqual(settings['pyramid.prevent_cachebust'], False)
+        result = self._makeOne({'prevent_cachebust':'false'})
+        self.assertEqual(result['prevent_cachebust'], False)
+        self.assertEqual(result['pyramid.prevent_cachebust'], False)
+        result = self._makeOne({'prevent_cachebust':'t'})
+        self.assertEqual(result['prevent_cachebust'], True)
+        self.assertEqual(result['pyramid.prevent_cachebust'], True)
+        result = self._makeOne({'prevent_cachebust':'1'})
+        self.assertEqual(result['prevent_cachebust'], True)
+        self.assertEqual(result['pyramid.prevent_cachebust'], True)
+        result = self._makeOne({'pyramid.prevent_cachebust':'t'})
+        self.assertEqual(result['prevent_cachebust'], True)
+        self.assertEqual(result['pyramid.prevent_cachebust'], True)
+        result = self._makeOne({}, {'PYRAMID_PREVENT_CACHEBUST':'1'})
+        self.assertEqual(result['prevent_cachebust'], True)
+        self.assertEqual(result['pyramid.prevent_cachebust'], True)
+        result = self._makeOne({'prevent_cachebust':'false',
+                                'pyramid.prevent_cachebust':'1'})
+        self.assertEqual(result['prevent_cachebust'], True)
+        self.assertEqual(result['pyramid.prevent_cachebust'], True)
+        result = self._makeOne({'prevent_cachebust':'false',
+                                'pyramid.prevent_cachebust':'f'},
+                               {'PYRAMID_PREVENT_CACHEBUST':'1'})
+        self.assertEqual(result['prevent_cachebust'], True)
+        self.assertEqual(result['pyramid.prevent_cachebust'], True)
 
     def test_reload_templates(self):
         settings = self._makeOne({})
diff --git a/pyramid/tests/test_config/test_views.py b/pyramid/tests/test_config/test_views.py
index 8f600c1d2..a0d9ee0c3 100644
--- a/pyramid/tests/test_config/test_views.py
+++ b/pyramid/tests/test_config/test_views.py
@@ -3845,12 +3845,12 @@ class TestStaticURLInfo(unittest.TestCase):
         self.assertEqual(result,
                          'http://example.com/abc%20def#La%20Pe%C3%B1a')
 
-    def test_generate_url_cachebuster(self):
-        def cachebuster(subpath, kw):
+    def test_generate_url_cachebust(self):
+        def cachebust(subpath, kw):
             kw['foo'] = 'bar'
             return 'foo' + '/' + subpath, kw
         inst = self._makeOne()
-        registrations = [(None, 'package:path/', '__viewname', cachebuster)]
+        registrations = [(None, 'package:path/', '__viewname', cachebust)]
         inst._get_registrations = lambda *x: registrations
         request = self._makeRequest()
         def route_url(n, **kw):
@@ -3944,28 +3944,28 @@ class TestStaticURLInfo(unittest.TestCase):
     def test_add_cachebust_default(self):
         config = self._makeConfig()
         inst = self._makeOne()
-        inst._default_cachebuster = DummyCacheBuster
-        inst.add(config, 'view', 'mypackage:path', cachebuster=True)
-        cachebuster = config.registry._static_url_registrations[0][3]
-        subpath, kw = cachebuster('some/path', {})
+        inst._default_cachebust = DummyCacheBuster
+        inst.add(config, 'view', 'mypackage:path', cachebust=True)
+        cachebust = config.registry._static_url_registrations[0][3]
+        subpath, kw = cachebust('some/path', {})
         self.assertEqual(subpath, 'some/path')
         self.assertEqual(kw['x'], 'foo')
 
     def test_add_cachebust_prevented(self):
         config = self._makeConfig()
-        config.registry.settings['pyramid.prevent_cachebuster'] = True
+        config.registry.settings['pyramid.prevent_cachebust'] = True
         inst = self._makeOne()
-        inst.add(config, 'view', 'mypackage:path', cachebuster=True)
-        cachebuster = config.registry._static_url_registrations[0][3]
-        self.assertEqual(cachebuster, None)
+        inst.add(config, 'view', 'mypackage:path', cachebust=True)
+        cachebust = config.registry._static_url_registrations[0][3]
+        self.assertEqual(cachebust, None)
 
     def test_add_cachebust_custom(self):
         config = self._makeConfig()
         inst = self._makeOne()
         inst.add(config, 'view', 'mypackage:path',
-                 cachebuster=DummyCacheBuster())
-        cachebuster = config.registry._static_url_registrations[0][3]
-        subpath, kw = cachebuster('some/path', {})
+                 cachebust=DummyCacheBuster())
+        cachebust = config.registry._static_url_registrations[0][3]
+        subpath, kw = cachebust('some/path', {})
         self.assertEqual(subpath, 'some/path')
         self.assertEqual(kw['x'], 'foo')
 
-- 
cgit v1.2.3


From f674a8f691d260d44e0f76e3afecfb15484c45b9 Mon Sep 17 00:00:00 2001
From: Chris Rossi <chris@archimedeanco.com>
Date: Mon, 28 Jul 2014 17:26:11 -0400
Subject: Mo' features, mo' problems.

---
 docs/api/static.rst          |  7 +++-
 docs/narr/assets.rst         | 87 +++++++++++++++++++++++++++++++-------------
 pyramid/config/views.py      |  4 +-
 pyramid/static.py            | 30 ++++++++++++---
 pyramid/tests/test_static.py | 46 +++++++++++++++++++++--
 5 files changed, 135 insertions(+), 39 deletions(-)

diff --git a/docs/api/static.rst b/docs/api/static.rst
index de5bcabda..543e526ad 100644
--- a/docs/api/static.rst
+++ b/docs/api/static.rst
@@ -9,8 +9,11 @@
      :members:
      :inherited-members:
 
-  .. autoclass:: PathSegmentCacheBuster
+  .. autoclass:: PathSegmentMd5CacheBuster
      :members:
 
-  .. autoclass:: QueryStringCacheBuster
+  .. autoclass:: QueryStringMd5CacheBuster
+     :members:
+
+  .. autoclass:: QueryStringConstantCacheBuster
      :members:
diff --git a/docs/narr/assets.rst b/docs/narr/assets.rst
index 7fb0ec40b..33677988d 100644
--- a/docs/narr/assets.rst
+++ b/docs/narr/assets.rst
@@ -379,25 +379,19 @@ equivalent to:
 .. code-block:: python
    :linenos:
 
-   from pyramid.static import PathSegmentCacheBuster
+   from pyramid.static import PathSegmentMd5CacheBuster
 
    # config is an instance of pyramid.config.Configurator
    config.add_static_view(name='static', path='mypackage:folder/static',
-                          cachebust=PathSegmentCacheBuster())
+                          cachebust=PathSegmentMd5CacheBuster())
 
-:app:`Pyramid` includes two ready to use cache buster implementations: 
-:class:`~pyramid.static.PathSegmentCacheBuster`, which inserts an asset token
-in the path portion of the asset's URL, and 
-:class:`~pyramid.static.QueryStringCacheBuster`, which adds an asset token to
-the query string of the asset's URL.  Both of these classes generate md5 
-checksums as asset tokens.
-
-.. note::
-
-   Many HTTP caching proxy implementations will fail to cache any URL which
-   has a query string. For this reason, you should probably prefer 
-   :class:`~pyramid.static.PathSegmentCacheBuster` to 
-   :class:`~pyramid.static.QueryStringCacheBuster`.
+:app:`Pyramid` includes a handful of ready to use cache buster implementations:
+:class:`~pyramid.static.PathSegmentMd5CacheBuster`, which inserts an md5
+checksum token in the path portion of the asset's URL,
+:class:`~pyramid.static.QueryStringMd5CacheBuster`, which adds an md5 checksum
+token to the query string of the asset's URL, and
+:class:`~pyramid.static.QueryStringConstantCacheBuster`, which adds an
+arbitrary token you provide to the query string of the asset's URL.  
 
 In order to implement your own cache buster, you can write your own class from
 scratch which implements the :class:`~pyramid.interfaces.ICacheBuster`
@@ -405,22 +399,65 @@ interface.  Alternatively you may choose to subclass one of the existing
 implementations.  One of the most likely scenarios is you'd want to change the
 way the asset token is generated.  To do this just subclass an existing
 implementation and replace the :meth:`~pyramid.interfaces.ICacheBuster.token`
-method.  Here is an example which just uses a global setting for the asset
-token:
+method.  Here is an example which just uses Git to get the hash of the 
+currently checked out code:
 
 .. code-block:: python
    :linenos:
-    
-   from pyramid.static import PathSegmentCacheBuster
 
-   class MyCacheBuster(PathSegmentCacheBuster):
-
-       def __init__(self, config):
-           # config is an instance of pyramid.config.Configurator
-           self._token = config.registry.settings['myapp.cachebust_token']
+   import os
+   import subprocess
+   from pyramid.static import PathSegmentMd5CacheBuster
+
+   class GitCacheBuster(PathSegmentMd5CacheBuster):
+       """
+       Assuming your code is installed as a Git checkout, as opposed to as an
+       egg from an egg repository like PYPI, you can use this cachebuster to
+       get the current commit's SHA1 to use as the cache bust token.
+       """
+       def __init__(self):
+           here = os.path.dirname(os.path.abspath(__file__))
+           self.sha1 = subprocess.check_output(
+               ['git', 'rev-parse', 'HEAD'],
+               cwd=here).strip()
 
        def token(self, pathspec):
-           return self._token
+           return self.sha1
+   
+Choosing a Cache Buster
+~~~~~~~~~~~~~~~~~~~~~~~
+
+The default cache buster implementation, 
+:class:`~pyramid.static.PathSegmentMd5CacheBuster`, works very well assuming 
+that you're using :app:`Pyramid` to serve your static assets.  The md5 checksum
+is fine grained enough that browsers should only request new versions of 
+specific assets that have changed.  Many caching HTTP proxies will fail to 
+cache a resource if the URL contains a query string.  In general, therefore, 
+you should prefer a cache busting strategy which modifies the path segment to
+a strategy which adds a query string.  
+
+It is possible, however, that your static assets are being served by another
+web server or externally on a CDN.  In these cases modifying the path segment
+for a static asset URL would cause the external service to fail to find the
+asset, causing your customer to get a 404.  In these cases you would need to 
+fall back to a cache buster which adds a query string.  It is even possible 
+that there isn't a copy of your static assets available to the :app:`Pyramid`
+application, so a cache busting implementation that generates md5 checksums
+would fail since it can't access the assets.  In such a case, 
+:class:`~pyramid.static.QueryStringConstantCacheBuster` is a reasonable 
+fallback.  The following code would set up a cachebuster that just uses the 
+time at start up as a cachebust token:
+
+.. code-block:: python
+   :linenos:
+
+   import time
+   from pyramid.static import QueryStringConstantCacheBuster
+
+   config.add_static_view(
+       name='http://mycdn.example.com/', 
+       path='mypackage:static',
+       cachebust=QueryStringConstantCacheBuster(str(time.time())))
 
 .. index::
    single: static assets view
diff --git a/pyramid/config/views.py b/pyramid/config/views.py
index e6c5baf58..5ca696069 100644
--- a/pyramid/config/views.py
+++ b/pyramid/config/views.py
@@ -34,7 +34,7 @@ from pyramid.interfaces import (
     )
 
 from pyramid import renderers
-from pyramid.static import PathSegmentCacheBuster
+from pyramid.static import PathSegmentMd5CacheBuster
 
 from pyramid.compat import (
     string_types,
@@ -1894,7 +1894,7 @@ def isexception(o):
 @implementer(IStaticURLInfo)
 class StaticURLInfo(object):
     # Indirection for testing
-    _default_cachebust = PathSegmentCacheBuster
+    _default_cachebust = PathSegmentMd5CacheBuster
 
     def _get_registrations(self, registry):
         try:
diff --git a/pyramid/static.py b/pyramid/static.py
index 0cbb5533f..5e017e1cd 100644
--- a/pyramid/static.py
+++ b/pyramid/static.py
@@ -192,7 +192,7 @@ class Md5AssetTokenGenerator(object):
             self.token_cache[pathspec] = token = _generate_md5(pathspec)
         return token
 
-class PathSegmentCacheBuster(Md5AssetTokenGenerator):
+class PathSegmentMd5CacheBuster(Md5AssetTokenGenerator):
     """
     An implementation of :class:`~pyramid.interfaces.ICacheBuster` which
     inserts an md5 checksum token for cache busting in the path portion of an
@@ -205,17 +205,18 @@ class PathSegmentCacheBuster(Md5AssetTokenGenerator):
     def match(self, subpath):
         return subpath[1:]
 
-class QueryStringCacheBuster(Md5AssetTokenGenerator):
+class QueryStringMd5CacheBuster(Md5AssetTokenGenerator):
     """
-    An implementation of :class:`~pyramid.interfaces.ICacheBuster` which adds a
-    token for cache busting in the query string of an asset URL.  Generated md5
-    checksums are cached in order to speed up subsequent calls.
+    An implementation of :class:`~pyramid.interfaces.ICacheBuster` which adds
+    an md5 checksum token for cache busting in the query string of an asset
+    URL.  Generated md5 checksums are cached in order to speed up subsequent
+    calls.
 
     The optional ``param`` argument determines the name of the parameter added
     to the query string and defaults to ``'x'``.
     """
     def __init__(self, param='x'):
-        super(QueryStringCacheBuster, self).__init__()
+        super(QueryStringMd5CacheBuster, self).__init__()
         self.param = param
 
     def pregenerate(self, token, subpath, kw):
@@ -226,4 +227,21 @@ class QueryStringCacheBuster(Md5AssetTokenGenerator):
             kw['_query'] = tuple(query) + ((self.param, token),)
         return subpath, kw
 
+class QueryStringConstantCacheBuster(QueryStringMd5CacheBuster):
+    """
+    An implementation of :class:`~pyramid.interfaces.ICacheBuster` which adds
+    an arbitrary token for cache busting in the query string of an asset URL.
+
+    The ``token`` parameter is the token string to use for cache busting and
+    will be the same for every request.
+
+    The optional ``param`` argument determines the name of the parameter added
+    to the query string and defaults to ``'x'``.
+    """
+    def __init__(self, token, param='x'):
+        self._token = token
+        self.param = param
+
+    def token(self, pathspec):
+        return self._token
 
diff --git a/pyramid/tests/test_static.py b/pyramid/tests/test_static.py
index 134bea25e..2f4de249e 100644
--- a/pyramid/tests/test_static.py
+++ b/pyramid/tests/test_static.py
@@ -420,10 +420,10 @@ class TestMd5AssetTokenGenerator(unittest.TestCase):
         token = fut(self.fspath)
         self.assertEqual(token, expected)
 
-class TestPathSegmentCacheBuster(unittest.TestCase):
+class TestPathSegmentMd5CacheBuster(unittest.TestCase):
 
     def _makeOne(self):
-        from pyramid.static import PathSegmentCacheBuster as cls
+        from pyramid.static import PathSegmentMd5CacheBuster as cls
         inst = cls()
         inst.token = lambda pathspec: 'foo'
         return inst
@@ -440,10 +440,10 @@ class TestPathSegmentCacheBuster(unittest.TestCase):
         fut = self._makeOne().match
         self.assertEqual(fut(('foo', 'bar')), ('bar',))
 
-class TestQueryStringCacheBuster(unittest.TestCase):
+class TestQueryStringMd5CacheBuster(unittest.TestCase):
 
     def _makeOne(self, param=None):
-        from pyramid.static import QueryStringCacheBuster as cls
+        from pyramid.static import QueryStringMd5CacheBuster as cls
         if param:
             inst = cls(param)
         else:
@@ -479,6 +479,44 @@ class TestQueryStringCacheBuster(unittest.TestCase):
             fut('foo', ('bar',), {'_query': (('a', 'b'),)}),
             (('bar',), {'_query': (('a', 'b'), ('x', 'foo'))}))
 
+class TestQueryStringConstantCacheBuster(TestQueryStringMd5CacheBuster):
+
+    def _makeOne(self, param=None):
+        from pyramid.static import QueryStringConstantCacheBuster as cls
+        if param:
+            inst = cls('foo', param)
+        else:
+            inst = cls('foo')
+        return inst
+
+    def test_token(self):
+        fut = self._makeOne().token
+        self.assertEqual(fut('whatever'), 'foo')
+
+    def test_pregenerate(self):
+        fut = self._makeOne().pregenerate
+        self.assertEqual(
+            fut('foo', ('bar',), {}),
+            (('bar',), {'_query': {'x': 'foo'}}))
+
+    def test_pregenerate_change_param(self):
+        fut = self._makeOne('y').pregenerate
+        self.assertEqual(
+            fut('foo', ('bar',), {}),
+            (('bar',), {'_query': {'y': 'foo'}}))
+
+    def test_pregenerate_query_is_already_tuples(self):
+        fut = self._makeOne().pregenerate
+        self.assertEqual(
+            fut('foo', ('bar',), {'_query': [('a', 'b')]}),
+            (('bar',), {'_query': (('a', 'b'), ('x', 'foo'))}))
+
+    def test_pregenerate_query_is_tuple_of_tuples(self):
+        fut = self._makeOne().pregenerate
+        self.assertEqual(
+            fut('foo', ('bar',), {'_query': (('a', 'b'),)}),
+            (('bar',), {'_query': (('a', 'b'), ('x', 'foo'))}))
+
 class DummyContext:
     pass
 
-- 
cgit v1.2.3


From 6b88bdf7680151345debec0c8651f164a149a53a Mon Sep 17 00:00:00 2001
From: Chris McDonough <chrism@plope.com>
Date: Mon, 28 Jul 2014 21:06:34 -0400
Subject: add versionadded notes

---
 docs/narr/assets.rst      | 2 ++
 docs/narr/environment.rst | 2 ++
 pyramid/interfaces.py     | 2 ++
 pyramid/static.py         | 6 ++++++
 4 files changed, 12 insertions(+)

diff --git a/docs/narr/assets.rst b/docs/narr/assets.rst
index 33677988d..95863848b 100644
--- a/docs/narr/assets.rst
+++ b/docs/narr/assets.rst
@@ -294,6 +294,8 @@ could be used.
 Cache Busting
 -------------
 
+.. versionadded:: 1.6
+
 In order to maximize performance of a web application, you generally want to 
 limit the number of times a particular client requests the same static asset.
 Ideally a client would cache a particular static asset "forever", requiring 
diff --git a/docs/narr/environment.rst b/docs/narr/environment.rst
index a81ad19af..e1171d710 100644
--- a/docs/narr/environment.rst
+++ b/docs/narr/environment.rst
@@ -165,6 +165,8 @@ Prevent the ``cachebust`` static view configuration argument from having any
 effect globally in this process when this value is true.  No cache buster will
 be configured or used when this is true.  
 
+.. versionadded:: 1.6
+
 .. seealso::
 
     See also :ref:`cache_busting`.
diff --git a/pyramid/interfaces.py b/pyramid/interfaces.py
index 2b6ba7eb6..c5a70dbfd 100644
--- a/pyramid/interfaces.py
+++ b/pyramid/interfaces.py
@@ -1172,6 +1172,8 @@ class ICacheBuster(Interface):
     a static asset, modifying a static asset URL to include a cache bust token,
     and, optionally, unmodifying a static asset URL in order to look up an
     asset.  See :ref:`cache_busting`.
+
+    .. versionadded:: 1.6
     """
     def token(pathspec):
         """
diff --git a/pyramid/static.py b/pyramid/static.py
index 5e017e1cd..c4a9e3cc4 100644
--- a/pyramid/static.py
+++ b/pyramid/static.py
@@ -198,6 +198,8 @@ class PathSegmentMd5CacheBuster(Md5AssetTokenGenerator):
     inserts an md5 checksum token for cache busting in the path portion of an
     asset URL.  Generated md5 checksums are cached in order to speed up
     subsequent calls.
+
+    .. versionadded:: 1.6
     """
     def pregenerate(self, token, subpath, kw):
         return (token,) + subpath, kw
@@ -214,6 +216,8 @@ class QueryStringMd5CacheBuster(Md5AssetTokenGenerator):
 
     The optional ``param`` argument determines the name of the parameter added
     to the query string and defaults to ``'x'``.
+
+    .. versionadded:: 1.6
     """
     def __init__(self, param='x'):
         super(QueryStringMd5CacheBuster, self).__init__()
@@ -237,6 +241,8 @@ class QueryStringConstantCacheBuster(QueryStringMd5CacheBuster):
 
     The optional ``param`` argument determines the name of the parameter added
     to the query string and defaults to ``'x'``.
+
+    .. versionadded:: 1.6
     """
     def __init__(self, token, param='x'):
         self._token = token
-- 
cgit v1.2.3