Expand docs on send_file option hook, #433.

CHANGES

@@ -48,6 +48,10 @@ Relase date to be decided, codename to be chosen.
 - View functions can now return a tuple with the first instance being an
   instance of :class:`flask.Response`.  This allows for returning
   ``jsonify(error="error msg"), 400`` from a view function.
+- :class:`flask.Flask` now provides a `get_static_file_options` hook for
+  subclasses to override behavior of serving static files through Flask,
+  optionally by filename, which for example allows changing cache controls by
+  file extension.
 
 
 Version 0.8.1

flask/helpers.py

@@ -653,8 +653,22 @@ class _PackageBoundObject(object):
                                                  self.template_folder))
 
     def get_static_file_options(self, filename):
-        """Function used internally to determine what keyword arguments
-        to send to :func:`send_from_directory` for a specific file."""
+        """Provides keyword arguments to send to :func:`send_from_directory`.
+
+        This allows subclasses to change the behavior when sending files based
+        on the filename.  For example, to set the cache timeout for .js files
+        to 60 seconds (note the options are keywords for :func:`send_file`)::
+
+            class MyFlask(flask.Flask):
+                def get_static_file_options(self, filename):
+                    options = super(MyFlask, self).get_static_file_options(filename)
+                    if filename.lower().endswith('.js'):
+                        options['cache_timeout'] = 60
+                        options['conditional'] = True
+                    return options
+
+        .. versionaded:: 0.9
+        """
         return {}
 
     def send_static_file(self, filename):

flask/testsuite/helpers.py

@@ -213,8 +213,6 @@ class SendfileTestCase(FlaskTestCase):
             self.assert_equal(cc.max_age, 12 * 60 * 60)
         # override get_static_file_options with some new values and check them
         class StaticFileApp(flask.Flask):
-            def __init__(self):
-                super(StaticFileApp, self).__init__(__name__)
             def get_static_file_options(self, filename):
                 opts = super(StaticFileApp, self).get_static_file_options(filename)
                 opts['cache_timeout'] = 10
@@ -222,7 +220,7 @@ class SendfileTestCase(FlaskTestCase):
                 # keyword arg in the guts
                 opts['conditional'] = True
                 return opts
-        app = StaticFileApp()
+        app = StaticFileApp(__name__)
         with app.test_request_context():
             rv = app.send_static_file('index.html')
             cc = parse_cache_control_header(rv.headers['Cache-Control'])