openstack/deb-python-django-compressor
Code Issues Proposed changes

Cleaned up the settings documentation and the docs frontpage.

Browse Source
This commit is contained in:
Jannis Leidel
2011-12-15 00:07:16 +01:00
parent 898199f05a
commit 78df87d733
6 changed files with 338 additions and 336 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
docs/changelog.txt
View File

@@ -79,8 +79,8 @@ v1.1
manifest.json file). manifest.json file).
You can now easily run the :ref:`compress <pre-compression>` management You can now easily run the :ref:`compress <pre-compression>` management
command locally and transfer the :ref:`COMPRESS_ROOT <compress_root>` dir command locally and transfer the :attr:`~django.conf.settings.COMPRESS_ROOT`
to your server. dir to your server.
- Updated installation instructions to properly mention all dependencies, - Updated installation instructions to properly mention all dependencies,
even those internally used. even those internally used.
@@ -257,7 +257,7 @@ Major improvements and a lot of bugfixes, some of which are:
- New precompilation support, which allows compilation of files and - New precompilation support, which allows compilation of files and
hunks with easily configurable compilers before calling the actual hunks with easily configurable compilers before calling the actual
output filters. See the output filters. See the
:ref:`COMPRESS_PRECOMPILERS <compress_precompilers>` for more details. :attr:`~django.conf.settings.COMPRESS_PRECOMPILERS` for more details.
- New staticfiles support. With the introduction of the staticfiles app - New staticfiles support. With the introduction of the staticfiles app
to Django 1.3, compressor officially supports finding the files to to Django 1.3, compressor officially supports finding the files to
@@ -272,7 +272,7 @@ Major improvements and a lot of bugfixes, some of which are:
- Various perfomance improvements by better caching and mtime cheking. - Various perfomance improvements by better caching and mtime cheking.
- Deprecated ``COMPRESS_LESSC_BINARY`` setting because it's now - Deprecated ``COMPRESS_LESSC_BINARY`` setting because it's now
superseded by the :ref:`COMPRESS_PRECOMPILERS <compress_precompilers>` superseded by the :attr:`~django.conf.settings.COMPRESS_PRECOMPILERS`
setting. Just make sure to use the correct mimetype when linking to less setting. Just make sure to use the correct mimetype when linking to less
files or adding inline code and add the following to your settings:: files or adding inline code and add the following to your settings::

2
docs/index.txt
View File

@@ -33,7 +33,7 @@ Contents
======== ========
.. toctree:: .. toctree::
:maxdepth: 1 :maxdepth: 2
installation installation
usage usage

73
docs/installation.txt
View File

@@ -1,5 +1,8 @@
Quickstart
==========
Installation Installation
============ ------------
* Install Django Compressor with your favorite Python package manager:: * Install Django Compressor with your favorite Python package manager::
@@ -18,7 +21,9 @@ Installation
* In case you use Django 1.3's staticfiles_ contrib app (or its standalone * In case you use Django 1.3's staticfiles_ contrib app (or its standalone
counterpart django-staticfiles_) you have to add Django Compressor's file counterpart django-staticfiles_) you have to add Django Compressor's file
finder to the ``STATICFILES_FINDERS`` setting, for example with finder to the ``STATICFILES_FINDERS`` setting, for example with
``django.contrib.staticfiles``:: ``django.contrib.staticfiles``:
.. code-block:: python
STATICFILES_FINDERS = ( STATICFILES_FINDERS = (
'django.contrib.staticfiles.finders.FileSystemFinder', 'django.contrib.staticfiles.finders.FileSystemFinder',
@@ -35,60 +40,64 @@ Installation
Dependencies Dependencies
------------ ------------
django-appconf_ (required) Required
^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^
Used internally to handle Django's settings, this is In case you're installing Django Compressor differently
automatically installed when following the above (e.g. from the Git repo), make sure to install the following
installation instructions. In case you're installing dependencies.
Django Compressor differently, make sure to install
it, e.g.:: - django-appconf_
Used internally to handle Django's settings, this is
automatically installed when following the above
installation instructions.
pip install django-appconf pip install django-appconf
versiontools_ (required) - versiontools_
^^^^^^^^^^^^^^^^^^^^^^^^
Used internally to handle versions better, this is Used internally to handle versions better, this is
automatically installed when following the above automatically installed when following the above
installation instructions. In case you're installing installation instructions.
Django Compressor differently, make sure to install
it, e.g.:: In case you're installing Django Compressor differently
(e.g. from the Git repo), make sure to install it, e.g.::
pip install versiontools pip install versiontools
BeautifulSoup_ (optional) Optional
^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^
for the :ref:`parser <compress_parser>` - BeautifulSoup_
``compressor.parser.BeautifulSoupParser`` and
``compressor.parser.LxmlParser``:: For the :attr:`parser <django.conf.settings.COMPRESS_PARSER>`
``compressor.parser.BeautifulSoupParser`` and
``compressor.parser.LxmlParser``::
pip install BeautifulSoup<=4.0 pip install BeautifulSoup<=4.0
lxml_ (optional) - lxml_
^^^^^^^^^^^^^^^^
for the :ref:`parser <compress_parser>` ``compressor.parser.LxmlParser``, For the :attr:`parser <django.conf.settings.COMPRESS_PARSER>`
also requires libxml2_:: ``compressor.parser.LxmlParser``, also requires libxml2_::
STATIC_DEPS=true pip install lxml STATIC_DEPS=true pip install lxml
html5lib_ (optional) - html5lib_
^^^^^^^^^^^^^^^^^^^^
for the :ref:`parser <compress_parser>` ``compressor.parser.Html5LibParser``:: For the :attr:`parser <django.conf.settings.COMPRESS_PARSER>`
``compressor.parser.Html5LibParser``::
pip install html5lib pip install html5lib
`Slim It`_ (optional) - `Slim It`_
^^^^^^^^^^^^^^^^^^^^^
for the :ref:`Slim It filter <slimit_filter>` ``compressor.filters.jsmin.SlimItFilter``:: For the :ref:`Slim It filter <slimit_filter>`
``compressor.filters.jsmin.SlimItFilter``::
pip install slimit pip install slimit
.. _BeautifulSoup: http://www.crummy.com/software/BeautifulSoup/ .. _BeautifulSoup: http://www.crummy.com/software/BeautifulSoup/
.. _lxml: http://codespeak.net/lxml/ .. _lxml: http://codespeak.net/lxml/
.. _libxml2: http://xmlsoft.org/ .. _libxml2: http://xmlsoft.org/

18
docs/remote-storages.txt
View File

@@ -9,9 +9,12 @@ processes files, it requires the files to be processed (in the
``{% compress %}`` block) to be available in a local file system cache. ``{% compress %}`` block) to be available in a local file system cache.
Django Compressor provides hooks to automatically have compressed files Django Compressor provides hooks to automatically have compressed files
pushed to a remote storage backend. Simply pushed to a remote storage backend. Simply set the storage backend
:ref:`set the storage backend <compress_storage>` that saves the result to a that saves the result to a remote service (see
remote service. :attr:`~django.conf.settings.COMPRESS_STORAGE`).
django-storages
^^^^^^^^^^^^^^^
So assuming your CDN is `Amazon S3`_, you can use the boto_ storage backend So assuming your CDN is `Amazon S3`_, you can use the boto_ storage backend
from the 3rd party app `django-storages`_. Some required settings are:: from the 3rd party app `django-storages`_. Some required settings are::
@@ -43,7 +46,7 @@ provides a management command to collect static files from various
locations which uses a storage backend, this is where both apps can be locations which uses a storage backend, this is where both apps can be
integrated. integrated.
#. Make sure the :ref:`COMPRESS_ROOT <compress_root>` and STATIC_ROOT_ #. Make sure the :attr:`~django.conf.settings.COMPRESS_ROOT` and STATIC_ROOT_
settings are equal since both apps need to look at the same directories settings are equal since both apps need to look at the same directories
when to do their job. when to do their job.
@@ -68,13 +71,14 @@ integrated.
self.local_storage._save(name, content) self.local_storage._save(name, content)
return name return name
#. Set your :ref:`COMPRESS_STORAGE <compress_storage>` and STATICFILES_STORAGE_ #. Set your :attr:`~django.conf.settings.COMPRESS_STORAGE` and STATICFILES_STORAGE_
settings to the dotted path of your custom cached storage backend, e.g. settings to the dotted path of your custom cached storage backend, e.g.
``'mysite.storage.CachedS3BotoStorage'``. ``'mysite.storage.CachedS3BotoStorage'``.
#. To have Django correctly render the URLs to your static files, set the #. To have Django correctly render the URLs to your static files, set the
STATIC_URL_ setting to the same value as :ref:`COMPRESS_URL <compress_url>` STATIC_URL_ setting to the same value as
(e.g. ``"http://compressor-test.s3.amazon.com/"``). :attr:`~django.conf.settings.COMPRESS_URL` (e.g.
``"http://compressor-test.s3.amazon.com/"``).
.. _CDN: http://en.wikipedia.org/wiki/Content_delivery_network .. _CDN: http://en.wikipedia.org/wiki/Content_delivery_network
.. _Amazon S3: https://s3.amazonaws.com/ .. _Amazon S3: https://s3.amazonaws.com/

430
docs/settings.txt
View File

@@ -1,29 +1,32 @@
.. _settings: .. _settings:
Settings Settings
-------- ========
.. currentmodule:: django.conf.settings
Django Compressor has a number of settings that control its behavior. Django Compressor has a number of settings that control its behavior.
They've been given sensible defaults. They've been given sensible defaults.
.. _compress_enabled: Base settings
-------------
COMPRESS_ENABLED .. attribute:: COMPRESS_ENABLED
^^^^^^^^^^^^^^^^
:Default: the opposite of ``DEBUG`` :default: the opposite of ``DEBUG``
Boolean that decides if compression will happen. To test compression Boolean that decides if compression will happen. To test compression
when ``DEBUG`` is ``True`` COMPRESS_ENABLED_ must also be set to ``True``. when ``DEBUG`` is ``True`` ``COMPRESS_ENABLED`` must also be set to
``True``.
When COMPRESS_ENABLED_ is ``False`` the input will be rendered without any When ``COMPRESS_ENABLED`` is ``False`` the input will be rendered without
compression except for code with a mimetype matching one listed in the any compression except for code with a mimetype matching one listed in the
COMPRESS_PRECOMPILERS_ setting. These matching files are still passed to the :attr:`~django.conf.settings.COMPRESS_PRECOMPILERS` setting. These
precompiler before rendering. matching files are still passed to the precompiler before rendering.
An example for some javascript and coffeescript. An example for some javascript and coffeescript.
.. code-block:: django .. code-block:: django
{% load compress %} {% load compress %}
@@ -32,172 +35,172 @@ An example for some javascript and coffeescript.
<script type="text/coffeescript" charset="utf-8" src="/static/js/awesome.coffee" /> <script type="text/coffeescript" charset="utf-8" src="/static/js/awesome.coffee" />
{% endcompress %} {% endcompress %}
With COMPRESS_ENABLED_ set to ``False`` this would give you something like With ``COMPRESS_ENABLED`` set to ``False`` this would give you something
this:: like this::
<script type="text/javascript" src="/static/js/site-base.js"></script> <script type="text/javascript" src="/static/js/site-base.js"></script>
<script type="text/javascript" src="/static/CACHE/js/8dd1a2872443.js" charset="utf-8"></script> <script type="text/javascript" src="/static/CACHE/js/8dd1a2872443.js" charset="utf-8"></script>
.. attribute:: COMPRESS_URL
:Default: ``STATIC_URL`` (``MEDIA_URL`` for older Django versions)
.. _compress_url: Controls the URL that linked files will be read from and compressed files
will be written to.
COMPRESS_URL .. note::
^^^^^^^^^^^^
:Default: ``STATIC_URL`` (``MEDIA_URL`` for older Django versions)
Controls the URL that linked files will be read from and compressed files
will be written to.
.. note::
This setting defaults to ``MEDIA_URL`` in case ``STATIC_URL`` This setting defaults to ``MEDIA_URL`` in case ``STATIC_URL``
is not given or empty, e.g. on older Django versions (<1.3). is not given or empty, e.g. on older Django versions (< 1.3).
.. _compress_root: .. attribute:: COMPRESS_ROOT
COMPRESS_ROOT :Default: ``STATIC_ROOT`` (``MEDIA_ROOT`` for older Django versions)
^^^^^^^^^^^^^
:Default: ``STATIC_ROOT`` (``MEDIA_ROOT`` for older Django versions) 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``.
Controls the absolute file path that linked static will be read from and .. note::
compressed static will be written to when using the default COMPRESS_STORAGE_
``compressor.storage.CompressorFileStorage``.
.. note::
This setting defaults to ``MEDIA_ROOT`` in case ``STATIC_ROOT`` This setting defaults to ``MEDIA_ROOT`` in case ``STATIC_ROOT``
is not given, e.g. on older Django versions (<1.3). is not given, e.g. on older Django versions (< 1.3).
COMPRESS_OUTPUT_DIR .. attribute:: COMPRESS_OUTPUT_DIR
^^^^^^^^^^^^^^^^^^^
:Default: ``'CACHE'`` :Default: ``'CACHE'``
Controls the directory inside COMPRESS_ROOT_ that compressed files will Controls the directory inside :attr:`~django.conf.settings.COMPRESS_ROOT`
be written to. that compressed files will be written to.
.. _compress_css_filters: Backend settings
----------------
COMPRESS_CSS_FILTERS .. attribute:: COMPRESS_CSS_FILTERS
^^^^^^^^^^^^^^^^^^^^
:Default: ``['compressor.filters.css_default.CssAbsoluteFilter']`` :default: ``['compressor.filters.css_default.CssAbsoluteFilter']``
A list of filters that will be applied to CSS. A list of filters that will be applied to CSS.
Possible options are: Possible options are (including their settings):
``compressor.filters.css_default.CssAbsoluteFilter`` - ``compressor.filters.css_default.CssAbsoluteFilter``
""""""""""""""""""""""""""""""""""""""""""""""""""""
A filter that normalizes the URLs used in ``url()`` CSS statements. A filter that normalizes the URLs used in ``url()`` CSS statements.
- ``COMPRESS_CSS_HASHING_METHOD`` -- The method to use when calculating .. attribute:: COMPRESS_CSS_HASHING_METHOD
the hash to append to processed URLs. Either ``'mtime'`` (default) or
``'content'``. Use the latter in case you're using multiple server to
serve your static files.
``compressor.filters.csstidy.CSSTidyFilter`` The method to use when calculating the hash to append to
"""""""""""""""""""""""""""""""""""""""""""" processed URLs. Either ``'mtime'`` (default) or ``'content'``.
Use the latter in case you're using multiple server to serve your
static files.
A filter that passes the CSS content to the CSSTidy_ tool. - ``compressor.filters.csstidy.CSSTidyFilter``
- ``COMPRESS_CSSTIDY_BINARY`` -- The CSSTidy binary filesystem path. A filter that passes the CSS content to the CSSTidy_ tool.
- ``COMPRESS_CSSTIDY_ARGUMENTS`` -- The arguments passed to CSSTidy. .. attribute:: COMPRESS_CSSTIDY_BINARY
``compressor.filters.datauri.DataUriFilter`` The CSSTidy binary filesystem path.
""""""""""""""""""""""""""""""""""""""""""""
A filter for embedding media as `data: URIs`_ in the CSS. .. attribute:: COMPRESS_CSSTIDY_ARGUMENTS
- ``COMPRESS_DATA_URI_MAX_SIZE`` -- Only files that are smaller than The arguments passed to CSSTidy.
this value will be embedded. In bytes.
``compressor.filters.yui.YUICSSFilter`` - ``compressor.filters.datauri.DataUriFilter``
"""""""""""""""""""""""""""""""""""""""
A filter that passes the CSS content to the `YUI compressor`_. A filter for embedding media as `data: URIs`_ in the CSS.
- ``COMPRESS_YUI_BINARY`` -- The YUI compressor filesystem path. Make sure .. attribute:: COMPRESS_DATA_URI_MAX_SIZE
to also prepend this setting with ``java -jar`` if you use that kind of
distribution.
- ``COMPRESS_YUI_CSS_ARGUMENTS``-- The arguments passed to the compressor. Only files that are smaller than this in bytes value will be embedded.
``compressor.filters.cssmin.CSSMinFilter`` - ``compressor.filters.yui.YUICSSFilter``
""""""""""""""""""""""""""""""""""""""""""
A filter that uses Zachary Voase's Python port of the YUI CSS compression A filter that passes the CSS content to the `YUI compressor`_.
algorithm cssmin_.
.. _CSSTidy: http://csstidy.sourceforge.net/ .. attribute:: COMPRESS_YUI_BINARY
.. _`data: URIs`: http://en.wikipedia.org/wiki/Data_URI_scheme
.. _cssmin: http://pypi.python.org/pypi/cssmin/ 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.cssmin.CSSMinFilter``
A filter that uses Zachary Voase's Python port of the YUI CSS compression
algorithm cssmin_.
.. _CSSTidy: http://csstidy.sourceforge.net/
.. _`data: URIs`: http://en.wikipedia.org/wiki/Data_URI_scheme
.. _cssmin: http://pypi.python.org/pypi/cssmin/
.. _compress_js_filters: .. _compress_js_filters:
COMPRESS_JS_FILTERS .. attribute:: COMPRESS_JS_FILTERS
^^^^^^^^^^^^^^^^^^^
:Default: ``['compressor.filters.jsmin.JSMinFilter']`` :Default: ``['compressor.filters.jsmin.JSMinFilter']``
A list of filters that will be applied to javascript. Possible options are: A list of filters that will be applied to javascript.
``compressor.filters.jsmin.JSMinFilter`` Possible options are:
"""""""""""""""""""""""""""""""""""""""""
A filter that uses the jsmin implementation rJSmin_ to compress JavaScript code. - ``compressor.filters.jsmin.JSMinFilter``
.. _slimit_filter: A filter that uses the jsmin implementation rJSmin_ to compress
JavaScript code.
``compressor.filters.jsmin.SlimItFilter`` .. _slimit_filter:
"""""""""""""""""""""""""""""""""""""""""
A filter that uses the jsmin implementation `Slim It`_ to compress JavaScript code. - ``compressor.filters.jsmin.SlimItFilter``
``compressor.filters.closure.ClosureCompilerFilter`` A filter that uses the jsmin implementation `Slim It`_ to compress
"""""""""""""""""""""""""""""""""""""""""""""""""""" JavaScript code.
A filter that uses `Google Closure compiler`_. - ``compressor.filters.closure.ClosureCompilerFilter``
- ``COMPRESS_CLOSURE_COMPILER_BINARY`` -- The Closure compiler filesystem A filter that uses `Google Closure compiler`_.
path. Make sure to also prepend this setting with ``java -jar`` if you
use that kind of distribution.
- ``COMPRESS_CLOSURE_COMPILER_ARGUMENTS`` -- The arguments passed to the compiler. .. attribute:: COMPRESS_CLOSURE_COMPILER_BINARY
``compressor.filters.yui.YUIJSFilter`` The Closure compiler filesystem path. Make sure to also prepend
"""""""""""""""""""""""""""""""""""""" this setting with ``java -jar`` if you use that kind of distribution.
A filter that passes the JavaScript code to the `YUI compressor`_. .. attribute:: COMPRESS_CLOSURE_COMPILER_ARGUMENTS
- ``COMPRESS_YUI_BINARY`` -- The YUI compressor filesystem path. The arguments passed to the compiler.
- ``COMPRESS_YUI_JS_ARGUMENTS`` -- The arguments passed to the compressor. - ``compressor.filters.yui.YUIJSFilter``
.. _rJSmin: http://opensource.perlig.de/rjsmin/ A filter that passes the JavaScript code to the `YUI compressor`_.
.. _`Google Closure compiler`: http://code.google.com/closure/compiler/
.. _`YUI compressor`: http://developer.yahoo.com/yui/compressor/
.. _`Slim It`: http://slimit.org/
.. _compress_precompilers: .. attribute:: COMPRESS_YUI_BINARY
COMPRESS_PRECOMPILERS The YUI compressor filesystem path.
^^^^^^^^^^^^^^^^^^^^^
:Default: ``()`` .. attribute:: COMPRESS_YUI_JS_ARGUMENTS
An iterable of two-tuples whose first item is the mimetype of the files or The arguments passed to the compressor.
hunks you want to compile with the command specified as the second item:
#. mimetype .. _rJSmin: http://opensource.perlig.de/rjsmin/
.. _`Google Closure compiler`: http://code.google.com/closure/compiler/
.. _`YUI compressor`: http://developer.yahoo.com/yui/compressor/
.. _`Slim It`: http://slimit.org/
.. 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 specified as the second item:
#. mimetype
The mimetype of the file or inline code should that should be compiled. The mimetype of the file or inline code should that should be compiled.
#. command #. command
The command to call on each of the files. Modern Python string The command to call on each of the files. Modern Python string
formatting will be provided for the two placeholders ``{infile}`` and formatting will be provided for the two placeholders ``{infile}`` and
``{outfile}`` whose existence in the command string also triggers the ``{outfile}`` whose existence in the command string also triggers the
@@ -205,7 +208,7 @@ hunks you want to compile with the command specified as the second item:
string, Django Compressor will use ``stdin`` and ``stdout`` respectively string, Django Compressor will use ``stdin`` and ``stdout`` respectively
instead. instead.
Example:: Example::
COMPRESS_PRECOMPILERS = ( COMPRESS_PRECOMPILERS = (
('text/coffeescript', 'coffee --compile --stdio'), ('text/coffeescript', 'coffee --compile --stdio'),
@@ -214,10 +217,10 @@ Example::
('text/x-scss', 'sass --scss {infile} {outfile}'), ('text/x-scss', 'sass --scss {infile} {outfile}'),
) )
With that setting (and CoffeeScript_ installed), you could add the following With that setting (and CoffeeScript_ installed), you could add the following
code to your templates: code to your templates:
.. code-block:: django .. code-block:: django
{% load compress %} {% load compress %}
@@ -229,13 +232,13 @@ code to your templates:
</script> </script>
{% endcompress %} {% endcompress %}
This would give you something like this:: This would give you something like this::
<script type="text/javascript" src="/static/CACHE/js/8dd1a2872443.js" charset="utf-8"></script> <script type="text/javascript" src="/static/CACHE/js/8dd1a2872443.js" charset="utf-8"></script>
The same works for less_, too: The same works for less_, too:
.. code-block:: django .. code-block:: django
{% load compress %} {% load compress %}
@@ -250,118 +253,110 @@ The same works for less_, too:
</style> </style>
{% endcompress %} {% endcompress %}
Which would be rendered something like:: Which would be rendered something like::
<link rel="stylesheet" href="/static/CACHE/css/8ccf8d877f18.css" type="text/css" charset="utf-8"> <link rel="stylesheet" href="/static/CACHE/css/8ccf8d877f18.css" type="text/css" charset="utf-8">
.. _less: http://lesscss.org/ .. _less: http://lesscss.org/
.. _CoffeeScript: http://jashkenas.github.com/coffee-script/ .. _CoffeeScript: http://jashkenas.github.com/coffee-script/
.. _compress_storage: .. attribute:: COMPRESS_STORAGE
COMPRESS_STORAGE :Default: ``'compressor.storage.CompressorFileStorage'``
^^^^^^^^^^^^^^^^
:Default: ``'compressor.storage.CompressorFileStorage'`` The dotted path to a Django Storage backend to be used to save the
compressed files.
The dotted path to a Django Storage backend to be used to save the Django Compressor ships with one additional storage backend:
compressed files.
Django Compressor ships with one additional storage backend: * ``'compressor.storage.GzipCompressorFileStorage'``
* ``'compressor.storage.GzipCompressorFileStorage'``
A subclass of the default storage backend, which will additionally A subclass of the default storage backend, which will additionally
create ``*.gz`` files of each of the compressed files. create ``*.gz`` files of each of the compressed files.
.. _compress_parser: .. attribute:: COMPRESS_PARSER
COMPRESS_PARSER :Default: ``'compressor.parser.AutoSelectParser'``
^^^^^^^^^^^^^^^
: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.
The backend to use when parsing the JavaScript or Stylesheet files. The ``LxmlParser`` is the fastest available parser, but ``HtmlParser`` is not much
``AutoSelectParser`` picks the ``lxml`` based parser when available, and falls slower. ``AutoSelectParser`` adds a slight overhead, but in most cases it
back to ``HtmlParser`` if ``lxml`` is not available. won't be necessary to change the default parser.
``LxmlParser`` is the fastest available parser, but ``HtmlParser`` is not much The other two included parsers are considerably slower and should only be
slower. ``AutoSelectParser`` adds a slight overhead, but in most cases it used if absolutely necessary.
won't be necessary to change the default parser.
The other two included parsers are considerably slower and should only be .. warning::
used if absolutely necessary.
.. warning::
In some cases the ``compressor.parser.HtmlParser`` parser isn't able to In some cases the ``compressor.parser.HtmlParser`` parser isn't able to
parse invalid HTML in JavaScript or CSS content. As a workaround you parse invalid HTML in JavaScript or CSS content. As a workaround you
should use one of the more forgiving parsers, e.g. the should use one of the more forgiving parsers, e.g. the
``BeautifulSoupParser``. ``BeautifulSoupParser``.
The backends included in Django Compressor: The backends included in Django Compressor:
- ``compressor.parser.AutoSelectParser`` - ``compressor.parser.AutoSelectParser``
- ``compressor.parser.LxmlParser`` - ``compressor.parser.LxmlParser``
- ``compressor.parser.HtmlParser`` - ``compressor.parser.HtmlParser``
- ``compressor.parser.BeautifulSoupParser`` - ``compressor.parser.BeautifulSoupParser``
- ``compressor.parser.Html5LibParser`` - ``compressor.parser.Html5LibParser``
See :ref:`dependencies` for more info about the packages you need See :ref:`dependencies` for more info about the packages you need
for each parser. for each parser.
.. _compress_cache_backend: Caching settings
----------------
COMPRESS_CACHE_BACKEND .. attribute:: COMPRESS_CACHE_BACKEND
^^^^^^^^^^^^^^^^^^^^^^
:Default: ``"default"`` or ``CACHE_BACKEND`` :Default: ``"default"`` or ``CACHE_BACKEND``
The backend to use for caching, in case you want to use a different cache The backend to use for caching, in case you want to use a different cache
backend for Django Compressor. backend for Django Compressor.
If you have set the ``CACHES`` setting (new in Django 1.3), If you have set the ``CACHES`` setting (new in Django 1.3),
``COMPRESS_CACHE_BACKEND`` defaults to ``"default"``, which is the alias for ``COMPRESS_CACHE_BACKEND`` defaults to ``"default"``, which is the alias for
the default cache backend. You can set it to a different alias that you have the default cache backend. You can set it to a different alias that you have
configured in your ``CACHES`` setting. configured in your ``CACHES`` setting.
If you have not set ``CACHES`` and are using the old ``CACHE_BACKEND`` If you have not set ``CACHES`` and are using the old ``CACHE_BACKEND``
setting, ``COMPRESS_CACHE_BACKEND`` defaults to the ``CACHE_BACKEND`` setting. setting, ``COMPRESS_CACHE_BACKEND`` defaults to the ``CACHE_BACKEND`` setting.
COMPRESS_REBUILD_TIMEOUT .. attribute:: COMPRESS_REBUILD_TIMEOUT
^^^^^^^^^^^^^^^^^^^^^^^^
:Default: ``2592000`` (30 days in seconds) :Default: ``2592000`` (30 days in seconds)
The period of time after which the compressed files are rebuilt even if The period of time after which the compressed files are rebuilt even if
no file changes are detected. no file changes are detected.
COMPRESS_MINT_DELAY .. attribute:: COMPRESS_MINT_DELAY
^^^^^^^^^^^^^^^^^^^
:Default: ``30`` (seconds) :Default: ``30`` (seconds)
The upper bound on how long any compression should take to run. Prevents The upper bound on how long any compression should take to run. Prevents
dog piling, should be a lot smaller than COMPRESS_REBUILD_TIMEOUT_. dog piling, should be a lot smaller than
:attr:`~django.conf.settings.COMPRESS_REBUILD_TIMEOUT`.
COMPRESS_MTIME_DELAY .. attribute:: COMPRESS_MTIME_DELAY
^^^^^^^^^^^^^^^^^^^^
:Default: ``10`` :Default: ``10``
The amount of time (in seconds) to cache the modification timestamp of a The amount of time (in seconds) to cache the modification timestamp of a
file. Disabled by default. Should be smaller than COMPRESS_REBUILD_TIMEOUT_ file. Disabled by default. Should be smaller than
and COMPRESS_MINT_DELAY_. :attr:`django.conf.settings.COMPRESS_REBUILD_TIMEOUT` and
:attr:`django.conf.settings.COMPRESS_MINT_DELAY`.
COMPRESS_DEBUG_TOGGLE .. attribute:: COMPRESS_DEBUG_TOGGLE
^^^^^^^^^^^^^^^^^^^^^
:Default: None :Default: None
The name of the GET variable that toggles the debug mode and prevents Django The name of the GET variable that toggles the debug mode and prevents Django
Compressor from performing the actual compression. Only useful for debugging. Compressor from performing the actual compression. Only useful for debugging.
.. warning:: .. warning::
Don't use this option in production! Don't use this option in production!
@@ -370,55 +365,46 @@ Compressor from performing the actual compression. Only useful for debugging.
if DEBUG: if DEBUG:
COMPRESS_DEBUG_TOGGLE = 'whatever' COMPRESS_DEBUG_TOGGLE = 'whatever'
.. note:: .. note::
This only works for pages that are rendered using the RequestContext_ This only works for pages that are rendered using the RequestContext_
and the ``django.core.context_processors.request`` context processor. and the ``django.core.context_processors.request`` context processor.
.. _RequestContext: http://docs.djangoproject.com/en/dev/ref/templates/api/#django.template.RequestContext .. _RequestContext: http://docs.djangoproject.com/en/dev/ref/templates/api/#django.template.RequestContext
.. _compress_offline: Offline settings
----------------
COMPRESS_OFFLINE .. attribute:: COMPRESS_OFFLINE
^^^^^^^^^^^^^^^^
:Default: ``False`` :Default: ``False``
Boolean that decides if compression should also be done outside of the Boolean that decides if compression should also be done outside of the
request/response loop -- independent from user requests. This allows to request/response loop -- independent from user requests. This allows to
pre-compress CSS and JavaScript files and works just like the automatic pre-compress CSS and JavaScript files and works just like the automatic
compression with the ``{% compress %}`` tag. compression with the ``{% compress %}`` tag.
.. _compress_offline_timeout: .. attribute:: COMPRESS_OFFLINE_TIMEOUT
COMPRESS_OFFLINE_TIMEOUT :Default: ``31536000`` (1 year in seconds)
^^^^^^^^^^^^^^^^^^^^^^^^
: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.
The period of time with which the ``compress`` management command stores .. attribute:: COMPRESS_OFFLINE_CONTEXT
the pre-compressed the contents of ``{% compress %}`` template tags in
the cache.
.. _compress_offline_context: :Default: ``{'MEDIA_URL': settings.MEDIA_URL}``
COMPRESS_OFFLINE_CONTEXT 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.
:Default: ``{'MEDIA_URL': settings.MEDIA_URL}`` If available, the ``STATIC_URL`` setting is also added to the context.
The context to be used by the ``compress`` management command when rendering .. attribute:: COMPRESS_OFFLINE_MANIFEST
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. :Default: ``manifest.json``
.. _compress_offline_manifest: The name of the file to be used for saving the names of the files compressed
offline.
COMPRESS_OFFLINE_MANIFEST
^^^^^^^^^^^^^^^^^^^^^^^^^
:Default: ``manifest.json``
The name of the file to be used for saving the names of the files compressed
offline.

27
docs/usage.txt
View File

@@ -46,21 +46,24 @@ Which would be rendered something like:
<script type="text/javascript" src="/static/CACHE/js/3f33b9146e12.js" charset="utf-8"></script> <script type="text/javascript" src="/static/CACHE/js/3f33b9146e12.js" charset="utf-8"></script>
Linked files **must** be accessible via :ref:`COMPRESS_URL <compress_url>`. Linked files **must** be accessible via
:attr:`~django.conf.settings.COMPRESS_URL`.
If the :ref:`COMPRESS_ENABLED <compress_enabled>` setting is ``False`` If the :attr:`~django.conf.settings.COMPRESS_ENABLED` setting is ``False``
(defaults to the opposite of DEBUG) the ``compress`` template tag does nothing (defaults to the opposite of DEBUG) the ``compress`` template tag does nothing
and simply returns exactly what it was given. and simply returns exactly what it was given.
.. note:: .. note::
If you've configured any :ref:`precompilers <compress_precompilers>` If you've configured any
setting :ref:`COMPRESS_ENABLED <compress_enabled>` to ``False`` won't :attr:`precompilers <django.conf.settings.COMPRESS_PRECOMPILERS>`
setting :attr:`~django.conf.settings.COMPRESS_ENABLED` to ``False`` won't
affect the processing of those files. Only the affect the processing of those files. Only the
:ref:`CSS <compress_css_filters>` and :attr:`CSS <django.conf.settings.COMPRESS_CSS_FILTERS>` and
:ref:`JavaScript filters <compress_js_filters>` will be disabled. :attr:`JavaScript filters <django.conf.settings.COMPRESS_JS_FILTERS>`
will be disabled.
If both DEBUG and :ref:`COMPRESS_ENABLED <compress_enabled>` are set to If both DEBUG and :attr:`~django.conf.settings.COMPRESS_ENABLED` are set to
``True``, incompressible files (off-site or non existent) will throw an ``True``, incompressible files (off-site or non existent) will throw an
exception. If DEBUG is ``False`` these files will be silently stripped. exception. If DEBUG is ``False`` these files will be silently stripped.
@@ -69,7 +72,7 @@ exception. If DEBUG is ``False`` these files will be silently stripped.
For production sites it is **strongly recommended** to use a real cache For production sites it is **strongly recommended** to use a real cache
backend such as memcached_ to speed up the checks of compressed files. backend such as memcached_ to speed up the checks of compressed files.
Make sure you set your Django cache backend appropriately (also see Make sure you set your Django cache backend appropriately (also see
:ref:`COMPRESS_CACHE_BACKEND <compress_cache_backend>` and :attr:`~django.conf.settings.COMPRESS_CACHE_BACKEND` and
Django's `caching documentation`_). Django's `caching documentation`_).
The compress template tag supports a second argument specifying the output The compress template tag supports a second argument specifying the output
@@ -112,7 +115,7 @@ works just like the automatic compression with the ``{% compress %}`` tag.
To compress the files "offline" and update the offline cache you have To compress the files "offline" and update the offline cache you have
to use the ``compress`` management command, ideally during deployment. to use the ``compress`` management command, ideally during deployment.
Also make sure to enable the :ref:`COMPRESS_OFFLINE <compress_offline>` Also make sure to enable the :attr:`django.conf.settings.COMPRESS_OFFLINE`
setting. In case you don't use the ``compress`` management command, Django setting. In case you don't use the ``compress`` management command, Django
Compressor will automatically fallback to the automatic compression using Compressor will automatically fallback to the automatic compression using
the template tag. the template tag.
@@ -120,7 +123,7 @@ the template tag.
The command parses all templates that can be found with the template The command parses all templates that can be found with the template
loader (as specified in the TEMPLATE_LOADERS_ setting) and looks for loader (as specified in the TEMPLATE_LOADERS_ setting) and looks for
``{% compress %}`` blocks. It then will use the context as defined in ``{% compress %}`` blocks. It then will use the context as defined in
:ref:`COMPRESS_OFFLINE_CONTEXT <compress_offline_context>` to render its :attr:`django.conf.settings.COMPRESS_OFFLINE_CONTEXT` to render its
content. So if you use any variables inside the ``{% compress %}`` blocks, content. So if you use any variables inside the ``{% compress %}`` blocks,
make sure to list all values you require in ``COMPRESS_OFFLINE_CONTEXT``. make sure to list all values you require in ``COMPRESS_OFFLINE_CONTEXT``.
It's similar to a template context and should be used if a variable is used It's similar to a template context and should be used if a variable is used
@@ -146,8 +149,8 @@ the commonly used setting to refer to saved files ``MEDIA_URL`` and
``STATIC_URL`` (if specified in the settings). ``STATIC_URL`` (if specified in the settings).
The result of running the ``compress`` management command will be cached The result of running the ``compress`` management command will be cached
in a file called ``manifest.json`` using the :ref:`configured storage in a file called ``manifest.json`` using the :attr:`configured storage
<compress_storage>` to be able to be transfered from your developement <django.conf.settings.COMPRESS_STORAGE>` to be able to be transfered from your developement
computer to the server easily. computer to the server easily.
.. _TEMPLATE_LOADERS: http://docs.djangoproject.com/en/dev/ref/settings/#template-loaders .. _TEMPLATE_LOADERS: http://docs.djangoproject.com/en/dev/ref/settings/#template-loaders