1 files changed, 57 insertions, 7 deletions

diff --git a/pyramid/interfaces.py b/pyramid/interfaces.py
index aa2dbdafd..c5a70dbfd 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,56 @@ class IJSONAdapter(Interface):
 class IPredicateList(Interface):
     """ Interface representing a predicate list """
 
+class ICacheBuster(Interface):
+    """
+    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`.
+
+    .. versionadded:: 1.6
+    """
+    def token(pathspec):
+        """
+        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):
+        """
+        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):
+        """
+        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
+        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 method
+        which implements this interface may not be necessary.  It is
+        permissible for an instance of
+        :class:`~pyramid.interfaces.ICacheBuster` to omit this method.
+        """
+
 # 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.