path: root/docs/settings.txt

.. _settings:

Settings
========

.. currentmodule:: django.conf.settings

Django Compressor has a number of settings that control its behavior.
They've been given sensible defaults.

Base settings
-------------

.. attribute:: COMPRESS_ENABLED

    :default: the opposite of ``DEBUG``

    Boolean that decides if compression will happen. To test compression
    when ``DEBUG`` is ``True`` ``COMPRESS_ENABLED`` must also be set to
    ``True``.

    When ``COMPRESS_ENABLED`` is ``False`` the input will be rendered without
    any compression except for code with a mimetype matching one listed in the
    :attr:`~django.conf.settings.COMPRESS_PRECOMPILERS` setting. These
    matching files are still passed to the precompiler before rendering.

    An example for some javascript and coffeescript.

    .. code-block:: django

        {% load compress %}

        {% compress js %}
        <script type="text/javascript" src="/static/js/site-base.js" />
        <script type="text/coffeescript" charset="utf-8" src="/static/js/awesome.coffee" />
        {% endcompress %}

    With ``COMPRESS_ENABLED`` set to ``False`` this would give you something
    like this::

        <script type="text/javascript" src="/static/js/site-base.js"></script>
        <script type="text/javascript" src="/static/CACHE/js/awesome.8dd1a2872443.js" charset="utf-8"></script>

.. attribute:: COMPRESS_URL

    :Default: ``STATIC_URL``

    Controls the URL that linked files will be read from and compressed files
    will be written to.

.. attribute:: COMPRESS_ROOT

    :Default: ``STATIC_ROOT``

    Controls the absolute file path that linked static will be read from and
    compressed static will be written to when using the default
    :attr:`~django.conf.settings.COMPRESS_STORAGE`
    ``compressor.storage.CompressorFileStorage``.

.. attribute:: COMPRESS_OUTPUT_DIR

    :Default: ``'CACHE'``

    Controls the directory inside :attr:`~django.conf.settings.COMPRESS_ROOT`
    that compressed files will be written to.

Backend settings
----------------

.. attribute:: COMPRESS_FILTERS

    :default: ``{'css': ['compressor.filters.css_default.CssAbsoluteFilter', 'compressor.filters.cssmin.rCSSMinFilter'], 'js': ['compressor.filters.jsmin.rJSMinFilter']}``

    A mapping of resource kinds to the list of filters to apply.
    The key is used to refer to this resource type in templates
    when using the `{% compress [resource_kind] %}` template tag.
    The value is a list of filters to apply in the given order
    for that resource.

    This library currently includes filters for CSS and Javascript.

    - CSS Filters

      .. _compress_css_filters:

      :default: ``['compressor.filters.css_default.CssAbsoluteFilter', 'compressor.filters.cssmin.rCSSMinFilter']``

      A list of filters that will be applied to CSS.

      Possible options for CSS filters are (including their settings):

      - ``compressor.filters.css_default.CssAbsoluteFilter``

        A filter that normalizes the URLs used in ``url()`` CSS statements. This
        is necessary since the output css files produced by Django Compressor
        are in a different location than the source files and relative paths
        might have become invalid. The filter also appends a hash as query string
        to the normalized URLs to help with cache busting.

        .. attribute:: COMPRESS_CSS_HASHING_METHOD

           The method to use when calculating the query string.  Either ``None``,
           ``'mtime'`` (default) or ``'content'``. Use the ``None`` if you want
           to completely disable that feature, and the ``'content'`` in case
           you're using multiple servers to serve your content.

      - ``compressor.filters.css_default.CssRelativeFilter``

        An alternative to ``CssAbsoluteFilter``. It uses a relative instead of an
        absolute path to prefix URLs. Specifically, the prefix will be  ``'../' * (N + 1)``
        where ``N`` is the *depth* of ``settings.COMPRESS_OUTPUT_DIR`` folder
        (i.e. ``1`` for ``'CACHE'``, or ``2``for ``CACHE/data`` etc). This can be
        useful if you don't want to hard-code :attr:`~django.conf.settings.COMPRESS_URL`
        into CSS code.

      - ``compressor.filters.datauri.CssDataUriFilter``

        A filter for embedding media as `data: URIs`_ in the CSS.

        .. attribute:: COMPRESS_DATA_URI_MAX_SIZE

           Only files that are smaller than this in bytes value will be embedded.

      - ``compressor.filters.yui.YUICSSFilter``

        A filter that passes the CSS content to the `YUI compressor`_.

        .. attribute:: COMPRESS_YUI_BINARY

           The YUI compressor filesystem path. Make sure to also prepend this
           setting with ``java -jar`` if you use that kind of distribution.

        .. attribute:: COMPRESS_YUI_CSS_ARGUMENTS

           The arguments passed to the compressor.

      - ``compressor.filters.yuglify.YUglifyCSSFilter``

        A filter that passes the CSS content to the `yUglify compressor`_.

        .. attribute:: COMPRESS_YUGLIFY_BINARY

           The yUglify compressor filesystem path.

        .. attribute:: COMPRESS_YUGLIFY_CSS_ARGUMENTS

           The arguments passed to the compressor. Defaults to --terminal.

      .. _csscompressor_filter:

      - ``compressor.filters.cssmin.CSSCompressorFilter``

        A filter that uses Yury Selivanov's Python port of the YUI CSS compression
        algorithm csscompressor_.

      - ``compressor.filters.cssmin.rCSSMinFilter``

        A filter that uses the cssmin implementation rCSSmin_ to compress CSS
        (installed by default).

      - ``compressor.filters.cleancss.CleanCSSFilter``

        A filter that passes the CSS content to the `clean-css`_ tool.

        .. attribute:: COMPRESS_CLEAN_CSS_BINARY

           The clean-css binary filesystem path.

        .. attribute:: COMPRESS_CLEAN_CSS_ARGUMENTS

           The arguments passed to clean-css.


      .. _`data: URIs`: http://en.wikipedia.org/wiki/Data_URI_scheme
      .. _csscompressor: http://pypi.python.org/pypi/csscompressor/
      .. _rCSSmin: http://opensource.perlig.de/rcssmin/
      .. _`clean-css`: https://github.com/GoalSmashers/clean-css/


      - ``compressor.filters.template.TemplateFilter``

        A filter that renders the CSS content with Django templating system.

        .. attribute:: COMPRESS_TEMPLATE_FILTER_CONTEXT

           The context to render your css files with.


    - Javascript Filters

      .. _compress_js_filters:

      :Default: ``['compressor.filters.jsmin.rJSMinFilter']``

      A list of filters that will be applied to javascript.

      Possible options are:

      - ``compressor.filters.jsmin.rJSMinFilter``

        A filter that uses the jsmin implementation rJSmin_ to compress
        JavaScript code (installed by default).

      .. _calmjs_filter:

      - ``compressor.filters.jsmin.CalmjsFilter``

        A filter that uses the jsmin implementation `Calmjs`_ to compress
        JavaScript code.

      - ``compressor.filters.closure.ClosureCompilerFilter``

        A filter that uses `Google Closure compiler`_.

        .. attribute:: COMPRESS_CLOSURE_COMPILER_BINARY

           The Closure compiler filesystem path. Make sure to also prepend
           this setting with ``java -jar`` if you use that kind of distribution.

        .. attribute:: COMPRESS_CLOSURE_COMPILER_ARGUMENTS

           The arguments passed to the compiler.

      - ``compressor.filters.yui.YUIJSFilter``

        A filter that passes the JavaScript code to the `YUI compressor`_.

        .. attribute:: COMPRESS_YUI_BINARY

           The YUI compressor filesystem path.

        .. attribute:: COMPRESS_YUI_JS_ARGUMENTS

           The arguments passed to the compressor.

      - ``compressor.filters.yuglify.YUglifyJSFilter``

        A filter that passes the JavaScript code to the `yUglify compressor`_.

        .. attribute:: COMPRESS_YUGLIFY_BINARY

           The yUglify compressor filesystem path.

        .. attribute:: COMPRESS_YUGLIFY_JS_ARGUMENTS

           The arguments passed to the compressor.

      - ``compressor.filters.template.TemplateFilter``

        A filter that renders the JavaScript code with Django templating system.

        .. attribute:: COMPRESS_TEMPLATE_FILTER_CONTEXT

           The context to render your JavaScript code with.

      .. _rJSmin: http://opensource.perlig.de/rjsmin/
      .. _`Google Closure compiler`: http://code.google.com/closure/compiler/
      .. _`YUI compressor`: http://developer.yahoo.com/yui/compressor/
      .. _`yUglify compressor`: https://github.com/yui/yuglify
      .. _`Slim It`: https://github.com/rspivak/slimit
      .. _`Calmjs`: https://github.com/calmjs/calmjs.parse

.. attribute:: COMPRESS_PRECOMPILERS

    :Default: ``()``

    An iterable of two-tuples whose first item is the mimetype of the files or
    hunks you want to compile with the command or filter specified as the second
    item:

    #. mimetype
        The mimetype of the file or inline code that should be compiled.

    #. command_or_filter
        The command to call on each of the files. Modern Python string
        formatting will be provided for the two placeholders ``{infile}`` and
        ``{outfile}`` whose existence in the command string also triggers the
        actual creation of those temporary files. If not given in the command
        string, Django Compressor will use ``stdin`` and ``stdout`` respectively
        instead.

        Alternatively, you may provide the fully qualified class name of a
        filter you wish to use as a precompiler.

    Example::

        COMPRESS_PRECOMPILERS = (
            ('text/coffeescript', 'coffee --compile --stdio'),
            ('text/less', 'lessc {infile} {outfile}'),
            ('text/x-sass', 'sass {infile} {outfile}'),
            ('text/x-scss', 'sass --scss {infile} {outfile}'),
            ('text/stylus', 'stylus < {infile} > {outfile}'),
            ('text/foobar', 'path.to.MyPrecompilerFilter'),
        )

    .. note::
        Depending on the implementation, some precompilers might not support
        outputting to something else than ``stdout``, so you'll need to omit the
        ``{outfile}`` parameter when working with those. For instance, if you
        are using the Ruby version of lessc, you'll need to set up the
        precompiler like this::

            ('text/less', 'lessc {infile}'),

    With that setting (and CoffeeScript_ installed), you could add the following
    code to your templates:

    .. code-block:: django

        {% load compress %}

        {% compress js %}
        <script type="text/coffeescript" charset="utf-8" src="/static/js/awesome.coffee" />
        <script type="text/coffeescript" charset="utf-8">
        # Functions:
        square = (x) -> x * x
        </script>
        {% endcompress %}

    This would give you something like this::

        <script type="text/javascript" src="/static/CACHE/js/output.8dd1a2872443.js" charset="utf-8"></script>

    The same works for less_, too:

    .. code-block:: django

        {% load compress %}

        {% compress css %}
        <link type="text/less" rel="stylesheet" href="/static/css/styles.less" charset="utf-8">
        <style type="text/less">
        @color: #4D926F;

        #header {
          color: @color;
        }
        </style>
        {% endcompress %}

    Which would be rendered something like::

        <link rel="stylesheet" href="/static/CACHE/css/output.8ccf8d877f18.css" type="text/css" charset="utf-8">

    .. _less: http://lesscss.org/
    .. _CoffeeScript: http://coffeescript.org/

.. attribute:: COMPRESS_STORAGE

    :Default: ``'compressor.storage.CompressorFileStorage'``

    The dotted path to a Django Storage backend to be used to save the
    compressed files.

    Django Compressor ships with some additional storage backends:

    * ``'compressor.storage.GzipCompressorFileStorage'``

      A subclass of the default storage backend, which will additionally
      create ``*.gz`` files of each of the compressed files.

    * ``'compressor.storage.BrotliCompressorFileStorage'``

      A subclass of the default storage backend, which will additionally
      create ``*.br`` files of each of the compressed files. It is using
      the maximum level of compression (11) so compression speed will be low.

.. attribute:: COMPRESS_PARSER

    :Default: ``'compressor.parser.AutoSelectParser'``

    The backend to use when parsing the JavaScript or Stylesheet files. The
    ``AutoSelectParser`` picks the ``lxml`` based parser when available, and falls
    back to ``HtmlParser`` if ``lxml`` is not available.

    ``LxmlParser`` is the fastest available parser, but ``HtmlParser`` is not much
    slower. ``AutoSelectParser`` adds a slight overhead, but in most cases it
    won't be necessary to change the default parser.

    The other two included parsers are considerably slower and should only be
    used if absolutely necessary.

    .. warning::

        In some cases the ``compressor.parser.HtmlParser`` parser isn't able to
        parse invalid HTML in JavaScript or CSS content. As a workaround you
        should use one of the more forgiving parsers, e.g. the
        ``BeautifulSoupParser``.

    The backends included in Django Compressor:

    - ``compressor.parser.AutoSelectParser``
    - ``compressor.parser.LxmlParser``
    - ``compressor.parser.HtmlParser``
    - ``compressor.parser.BeautifulSoupParser``
    - ``compressor.parser.Html5LibParser``

    See :ref:`dependencies` for more info about the packages you need
    for each parser.

Caching settings
----------------

.. attribute:: COMPRESS_CACHE_BACKEND

    :Default: ``"default"``

    The cache to use by Django Compressor. Must be a cache alias specified in
    your ``CACHES`` setting.

.. attribute:: COMPRESS_REBUILD_TIMEOUT

    :Default: ``2592000`` (30 days in seconds)

    The period of time after which the compressed files are rebuilt even if
    no file changes are detected.

.. attribute:: COMPRESS_MINT_DELAY

    :Default: ``30`` (seconds)

    The upper bound on how long any compression should take to run. Prevents
    dog piling, should be a lot smaller than
    :attr:`~django.conf.settings.COMPRESS_REBUILD_TIMEOUT`.

.. attribute:: COMPRESS_MTIME_DELAY

    :Default: ``10``

    The amount of time (in seconds) to cache the modification timestamp of a
    file. Should be smaller than
    :attr:`~django.conf.settings.COMPRESS_REBUILD_TIMEOUT` and
    :attr:`~django.conf.settings.COMPRESS_MINT_DELAY`.

.. attribute:: COMPRESS_CACHEABLE_PRECOMPILERS

    :Default: ``()``

    An iterable of precompiler mimetypes as defined in :attr:`~django.conf.settings.COMPRESS_PRECOMPILERS`
    for which the compiler output can be cached based solely on the contents
    of the input file. This lets Django Compressor avoid recompiling unchanged
    files. Caching is appropriate for compilers such as CoffeeScript where files
    are compiled one-to-one, but not for compilers such as SASS that have an
    ``import`` mechanism for including one file from another. If caching is enabled
    for such a compiler, Django Compressor will not know to recompile files when a file
    they import is modified.

.. attribute:: COMPRESS_DEBUG_TOGGLE

    :Default: None

    The name of the GET variable that toggles the debug mode and prevents Django
    Compressor from performing the actual compression. Only useful for debugging.

    .. warning::

        Don't use this option in production!

        An easy convention is to only set it depending on the ``DEBUG`` setting::

            if DEBUG:
                COMPRESS_DEBUG_TOGGLE = 'whatever'

    .. note::

        This only works for pages that are rendered using the RequestContext_
        and the ``django.core.context_processors.request`` context processor.

    .. _RequestContext: http://docs.djangoproject.com/en/dev/ref/templates/api/#django.template.RequestContext

.. attribute:: COMPRESS_CACHE_KEY_FUNCTION

    :Default: ``'compressor.cache.simple_cachekey'``

    The function to use when generating the cache key. The function must take
    one argument which is the partial key based on the source's hex digest.
    It must return the full key as a string.

Offline settings
----------------

.. attribute:: COMPRESS_OFFLINE

    :Default: ``False``

    Boolean that decides if compression should be done outside of the
    request/response loop. See :ref:`offline_compression` for details.

.. attribute:: COMPRESS_OFFLINE_TIMEOUT

    :Default: ``31536000`` (1 year in seconds)

    The period of time with which the ``compress`` management command stores
    the pre-compressed the contents of ``{% compress %}`` template tags in
    the cache.

.. attribute:: COMPRESS_OFFLINE_CONTEXT

    :Default: ``{'STATIC_URL': settings.STATIC_URL}``

    The context to be used by the ``compress`` management command when rendering
    the contents of ``{% compress %}`` template tags and saving the result in the
    offline cache.

    If available, the ``STATIC_URL`` setting is also added to the context.

    .. note::

        It is also possible to perform offline compression for multiple
        contexts by providing a list or tuple of dictionaries, or by providing
        a dotted string pointing to a generator function.

        This makes it easier to generate contexts dynamically for situations
        where a user might be able to select a different theme in their user
        profile, or be served different stylesheets based on other criteria.

        An example of multiple offline contexts by providing a list or tuple::

            # project/settings.py:
            COMPRESS_OFFLINE_CONTEXT = [
                {'THEME': 'plain', 'STATIC_URL': STATIC_URL},
                {'THEME': 'fancy', 'STATIC_URL': STATIC_URL},
                # ...
            ]

        An example of multiple offline contexts generated dynamically::

            # project/settings.py:
            COMPRESS_OFFLINE_CONTEXT = 'project.module.offline_context'

            # project/module.py:
            from django.conf import settings
            def offline_context():
                from project.models import Company
                for theme in set(Company.objects.values_list('theme', flat=True)):
                    yield {'THEME': theme, 'STATIC_URL': settings.STATIC_URL}

.. attribute:: COMPRESS_OFFLINE_MANIFEST

    :Default: ``manifest.json``

    The name of the file to be used for saving the names of the files
    compressed offline.

.. attribute:: COMPRESS_OFFLINE_MANIFEST_STORAGE

    :Default: ``compressor.storage.OfflineManifestFileStorage``

    The dotted path to a Django Storage backend to be used to save the
    offline manifest.

    By default, the file configured with
    :attr:`~django.conf.settings.COMPRESS_OFFLINE_MANIFEST` will be stored
    into :attr:`~django.conf.settings.COMPRESS_OUTPUT_DIR`.

    An example to output the manifest into the project's root directory::

        # project/settings.py:
        COMPRESS_STORAGE = 'project.module.PrivateOfflineManifestFileStorage'

        # project/module.py:
        from compressor.storage import OfflineManifestFileStorage
        from django.conf import settings
        class PrivateOfflineManifestFileStorage(OfflineManifestFileStorage):
            def __init__(self, *args, **kwargs):
                super().__init__(settings.BASE_DIR, None, *args, **kwargs)