# 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.