When upgrading from an older version, you might encounter some backwards incompatibility. The webassets API is not stable yet.
django-assets is no longer included! You need to install it’s package separately. See the current development version.
When upgrading, you need to take extra care to rid yourself of the old version of webassets before installing the separate django-assets package. This is to avoid that Python still finds the old django_assets module that used to be included with webassets.
In some cases, even pip uninstall webassets is not enough, and old *.pyc files are kept around. I recommend that you delete your old webassets install manually from the filesystem. To find out where it is stored, open a Python shell and do:
>>> import webassets >>> webassets <module 'webassets' from '/usr/local/lib/python2.7/dist-packages/webassets/src/webassets/__init__.pyc'>
Some filters now run in debug mode. Specifically, there are two things that deserve mention:
cssrewrite now runs when debug="merge". This is always what is wanted; it was essentially a bug that this didn’t happen before.
All kinds of compiler-style filters (Sass, less, Coffeescript, JST templates etc). all now run in debug mode. The presence of such a filter causes bundles to be merged even while debug=True.
In practice, if you’ve been using custom bundle debug values to get such compilers to run, this will continue to work. Though it can now be simplified. Code like this:
Bundle( Bundle('*.coffee', filters='coffeescript', debug=False) filters='jsmin')
can be replaced with:
which has the same effect, which is that during debugging, Coffeescript will be compiled, but not minimized. This also allows you to define bundles that use compilers from within the templates tags, because nesting is no longer necessary.
However, if you need to combine Coffeescript files (or other files needing compiling) with regular CSS or JS files, nesting is still required:
Bundle('*.js' Bundle('*.coffee', filters='coffeescript'), filters='jsmin')
If for some reason you do not want these compilers to run, you may still use a manual debug value to override the behavior. A case where this is useful is the less filter, which can be compiled in the browser:
Bundle('*.less', filters='less', debug=True)
Here, as long as the environment is in debug mode, the bundle will output the source urls, despite the less filter normally forcing a merge.
As part of this new feature, the handling of nested bundle debug values has changed such that in rare cases you may see a different outcome. In the unlikely case that you are using these a lot, the rule is simple: The debug level can only ever be decreased. Child bundles cannot cannot do “more debugging” than their parent, and if Environment.debug=False, all bundle debug values are effectively ignored.
The internal class names of filters have been renamed. For example, JSMinFilter is now simply JSMin. This only affects you if you reference these classes directly, rather than using their id (such as jsmin), which should be rare.
Removed the previously deprecated rebuild alias for the build command.
Subtly changed how the auto_build setting affects the Bundle.build() method: It doesn’t anymore. Instead, the setting now only works on the level of Bundle.urls(). The new behaviour is more consistent, makes more sense, and simplifies the code.
The main backwards-incompatiblity caused by this is that when environment.auto_build=False, and you are calling bundle.build() without specifying an explicit force argument, it used to be the case that force=True was assumed, i.e. the bundle was built without looking at the timestamps to see if a rebuild is necessary. Now, the timestamps will be checked, unless force=True is explicitly given.
In case you don’t want to pass force=True, you can instead also set the Environment.updater property to False; without an updater to check timestamps, every build() call will act as if force=True.
Note: This only affects you if you work with the Bundle.build() and Bundle.url() methods directly. The behavior of the command line interface, or the template tags is not affected.
The implementation of the CommandLineEnvironment has changed, and each command is now a separate class. If you have been subclassing CommandLineEnvironment to override individual command methods like CommandLineEnvironment.build(), you need to update your code.
The JavaMixin helper class to implement Java-based filters has been removed, and in it’s stead there is now a JavaTool base class that can be used.
The code to resolve bundle contents has been refactored. As a result, the behavior of the semi-internal method Bundle.resolve_contents() has changed slightly; in addition, the Environment._normalize_source_path() method used mainly by extensions like Flask-Assets has been removed. Instead, extensions now need to implement a custom Resolver. The Evironment.absurl method has also disappeared, and replacing it can now be done via a custom Resolver` class.
Environment.directory now always returns an absolute path; if a relative path is stored, it is based off on the current working directory. This spares a lot of calls to os.abspath throughout the code. If you need the original value you can always use environment.config['directory'].
If the JST_COMPILER option of the jst filter is set to False (as opposed to the default value, None), the templates will now be output as raw strings. Before, False behaved like None and used the builtin compiler.
The API of the concat() filter method has changed. Instead of a list of hunks, it is now given a list of 2-tuples of (hunk, info_dict).
The internal JSTTemplateFilter base class has changed API. - concat filter - jst handlebar filters have changed, use concat, base class has changed
There are some significant backwards incompatible changes in this release.
The semantics of the ASSETS_DEBUG setting have changed. In 0.1, setting this to True meant enable the django-assets debugging mode. However, django-assets now follows the default Django DEBUG setting, and ASSETS_DEBUG should be understood as meaning how to behave when in debug mode. See ASSETS_DEBUG for more information.
ASSETS_AUTO_CREATE now causes an error to be thrown if due it it being disabled a file cannot be created. Previously, it caused the source files to be linked directly (as if debug mode were active).
This was done due to Explicit is better than implicit, and for security considerations; people might trusting their comments to be removed. If it turns out to be necessary, the functionality to fall back to source could be added again in a future version through a separate setting.