The environment¶

The environment has two responsibilities: One, it acts as a registry for bundles, meaning you only have to pass around a single object to access all your bundles.

Also, it holds the configuration.

Registering bundles¶

Bundles can be registered with the environment:

my_bundle = Bundle(...)
environment.register('my_bundle', my_bundle)

A shortcut syntax is also available - you may simply call register() with the arguments which you would pass to the Bundle constructor:

environment.register('my_bundle', 'file1.js', 'file2.js', output='packed.js')

The environment allows dictionary-style access to the registered bundles:

>>> len(environment)
1

>>> list(environment)
[<Bundle ...>]

>>> environment['my_bundle']
<Bundle ...>

Configuration¶

The environment supports the following configuration options:

Environment.directory¶

The base directory to which all paths will be relative to, unless load_path are given, in which case this will only serve as the output directory.

In the url space, it is mapped to urls.

Environment.url¶

The url prefix used to construct urls for files in directory.

To define url spaces for other directories, see url_mapping.

Environment.debug¶

Enable/disable debug mode. Possible values are:

False: Production mode. Bundles will be merged and filters applied.
True: Enable debug mode. Bundles will output their individual source files.
“merge”: Merge the source files, but do not apply filters.

Environment.auto_build¶

Controls whether bundles should be automatically built, and rebuilt, when required (if set to True), or whether they must be built manually be the user, for example via a management command.

This is a good setting to have enabled during debugging, and can be very convenient for low-traffic sites in production as well. However, there is a cost in checking whether the source files have changed, so if you care about performance, or if your build process takes very long, then you may want to disable this.

By default automatic building is enabled.

Environment.url_expire¶

If you send your assets to the client using a far future expires header (to minimize the 304 responses your server has to send), you need to make sure that assets will be reloaded by the browser when they change.

If this is set to True, then the Bundle URLs generated by webassets will have their version (see Environment.versions) appended as a querystring.

An alternative approach would be to use the %(version)s placeholder in the bundle output file.

The default behavior (indicated by a None value) is to add an expiry querystring if the bundle does not use a version placeholder.

Environment.versions¶

Defines what should be used as a Bundle version.

A bundle’s version is what is appended to URLs when the url_expire option is enabled, and the version can be part of a Bundle’s output filename by use of the %(version)s placeholder.

Valid values are:

timestamp

The version is determined by looking at the mtime of a bundle’s output file.

hash (default)

The version is a hash over the output file’s content.

False, None

Functionality that requires a version is disabled. This includes the url_expire option, the auto_build option, and support for the %(version)s placeholder.

Any custom version implementation.

Environment.manifest¶

A manifest persists information about the versions bundles are at.

The Manifest plays a role only if you insert the bundle version in your output filenames, or append the version as a querystring to the url (via the url_expire option). It serves two purposes:

Without a manifest, it may be impossible to determine the version at runtime. In a deployed app, the media files may be stored on a different server entirely, and be inaccessible from the application code. The manifest, if shipped with your application, is what still allows to construct the proper URLs.

Even if it were possible to determine the version at runtime without a manifest, it may be a costly process, and using a manifest may give you better performance. If you use a hash-based version for example, this hash would need to be recalculated every time a new process is started.

Valid values are:

"cache" (default)

The cache is used to remember version information. This is useful to avoid recalculating the version hash.

"file:{path}"

Stores version information in a file at {path}. If not path is given, the manifest will be stored as .webassets-manifest in Environment.directory.

"json:{path}"

Same as “file:{path}”, but uses JSON to store the information.

False, None

No manifest is used.

Any custom manifest implementation.

Environment.cache¶

Controls the behavior of the cache. The cache will speed up rebuilding of your bundles, by caching individual filter results. This can be particularly useful while developing, if your bundles would otherwise take a long time to rebuild.

Possible values are:

False

Do not use the cache.

True (default)

Cache using default location, a .webassets-cache folder inside directory.

custom path

Use the given directory as the cache directory.

Environment.load_path¶

An list of directories that will be searched for source files.

If this is set, source files will only be looked for in these directories, and directory is used as a location for output files only.

To modify this list, you should use append_path(), since it makes it easy to add the corresponding url prefix to url_mapping.

Environment.url_mapping¶

A dictionary of directory -> url prefix mappings that will be considered when generating urls, in addition to the pair of directory and url, which is always active.

You should use append_path() to add directories to the load path along with their respective url spaces, instead of modifying this setting directly.

Filter configuration¶

In addition to the standard options listed above, you can set custom configuration values using Environment.config. This is so that you can configure filters through the environment:

environment.config['sass_bin'] = '/opt/sass/bin/sass')

This allows the Sass filter to find the sass binary.

Note: Filters usually allow you to define these values as system environment variables as well. That is, you could also define a SASS_BIN environment variable to setup the filter.