Flask-MakeStatic¶
Flask-MakeStatic is an extension for Flask that adds support for compilation of static files such as sass or coffeescript files.
In order to use it you simply create an assets directory and an assets.cfg file in the same directory as your static directory. assets should contain all files that require compilation and assets.cfg specifies how the files in assets should be compiled.
The simplest possible assets.cfg file would look like this:
[.*]
cp {asset} {static}
This defines a regular expression .* which matches any file in assets and copies the file to the static directory. {asset} will be replaced with the path to the file in the assets directory and {static} with the corresponding location within the static directory.
As you can see the syntax is kind of like an ini file. You have sections which match files in your assets directory followed by one or more commands that are executed when a matched file is compiled.
Within these commands several substitutions are available, which you can use with the .format() string formatting syntax:
| asset | The absolute path to matched asset. |
| static | The absolute path to the corresponding location in the static directory. |
| static_dir | The absolute path to the static directory. |
| static_base | Like static but without the file extension. |
In order to compile your assets you have to first create a MakeStatic instance, this should be familiar if you have used other flask extensions:
from flask import Flask
from flask.ext.makestatic import MakeStatic
app = Flask(__name__)
makestatic = MakeStatic(app)
First of all you are probably concerned about development. During development you do not want to manually recompile all the time, so what you should do is call MakeStatic.watch() before calling flask.Flask.run():
if __name__ == '__main__':
makestatic.watch()
app.run(debug=True)
This will compile your assets whenever a change is detected.
In production environments using MakeStatic.watch() is not a good idea because it starts a new thread to look for changes and has to compile all assets at least once. This costs performance and may unnecessarily compile your assets in environments using multiple workers.
Instead what you want to do, is compile your assets during your deployment process. You can do this by calling MakeStatic.compile().
API¶
- class flask.ext.makestatic.MakeStatic(app)¶
This class provides the extension interface. You can use it by calling it directly with a flask.Flask instance:
app = Flask(__name__) make_static = MakeStatic(app)
Once initialized MakeStatic will parse the assets.cfg configuration file corresponding to the initialized application.
- watch(sleep=0.1)¶
Starts a daemon thread that watches the static directory for changes and compiles the files that do change.
Returns a ThreadedWatcher, if you want to turn of watching you can call ThreadedWatcher.stop().
When run in a process started by the reloader, this does nothing to prevent the start of an unnecessary second watcher.
Parameters: sleep – The amount of time in seconds that should be slept between checks for changes, may be ignored.
- compile()¶
Compiles all assets to static files in one go.
This works only when done within an application context of an initialized application.
Emits a RuleMissing warning for each file in assets for which no rule exists.
- class flask.ext.makestatic.RuleMissing¶
Warning that is emitted if a rule cannot be found.
License¶
Copyright (c) 2013 by Daniel Neuhäuser
Redistribution and use in source and binary forms of the software as well as documentation, with or without modification, are permitted provided that the following conditions are met:
- Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
- Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
- The names of the contributors may not be used to endorse or promote products derived from this software without specific prior written permission.
THIS SOFTWARE AND DOCUMENTATION IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE AND DOCUMENTATION, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
