-
Notifications
You must be signed in to change notification settings - Fork 600
/
settings.txt
481 lines (296 loc) · 15 KB
/
settings.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
.. _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/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_CSS_FILTERS
:default: ``['compressor.filters.css_default.CssAbsoluteFilter']``
A list of filters that will be applied to CSS.
Possible options are (including their settings):
- ``compressor.filters.css_default.CssAbsoluteFilter``
A filter that normalizes the URLs used in ``url()`` CSS statements.
.. attribute:: COMPRESS_CSS_HASHING_METHOD
The method to use when calculating the suffix to append to URLs in
your processed CSS files. 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.csstidy.CSSTidyFilter``
A filter that passes the CSS content to the CSSTidy_ tool.
.. attribute:: COMPRESS_CSSTIDY_BINARY
The CSSTidy binary filesystem path.
.. attribute:: COMPRESS_CSSTIDY_ARGUMENTS
The arguments passed to CSSTidy.
- ``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.
- ``compressor.filters.cssmin.CSSMinFilter``
A filter that uses Zachary Voase's Python port of the YUI CSS compression
algorithm cssmin_.
- ``compressor.filters.cleancss.CleanCSSFilter``
A filter that passes the CSS content to the `clean-css`_ tool.
.. attribute:: CLEAN_CSS_BINARY
The clean-css binary filesystem path.
.. attribute:: CLEAN_CSS_ARGUMENTS
The arguments passed to clean-css.
.. _CSSTidy: http://csstidy.sourceforge.net/
.. _`data: URIs`: http://en.wikipedia.org/wiki/Data_URI_scheme
.. _cssmin: http://pypi.python.org/pypi/cssmin/
.. _`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.
.. _compress_js_filters:
.. attribute:: COMPRESS_JS_FILTERS
:Default: ``['compressor.filters.jsmin.JSMinFilter']``
A list of filters that will be applied to javascript.
Possible options are:
- ``compressor.filters.jsmin.JSMinFilter``
A filter that uses the jsmin implementation rJSmin_ to compress
JavaScript code.
.. _slimit_filter:
- ``compressor.filters.jsmin.SlimItFilter``
A filter that uses the jsmin implementation `Slim It`_ 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
.. 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/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/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 one additional storage backend:
* ``'compressor.storage.GzipCompressorFileStorage'``
A subclass of the default storage backend, which will additionally
create ``*.gz`` files of each of the compressed files.
.. 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: ``CACHES["default"]`` or ``CACHE_BACKEND``
The backend to use for caching, in case you want to use a different cache
backend for Django Compressor.
If you have set the ``CACHES`` setting (new in Django 1.3),
``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
configured in your ``CACHES`` setting.
If you have not set ``CACHES`` and are using the old ``CACHE_BACKEND``
setting, ``COMPRESS_CACHE_BACKEND`` defaults to the ``CACHE_BACKEND`` 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_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 also be done outside of the
request/response loop -- independent from user requests. This allows to
pre-compress CSS and JavaScript files and works just like the automatic
compression with the ``{% compress %}`` tag.
.. 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.
.. attribute:: COMPRESS_OFFLINE_MANIFEST
:Default: ``manifest.json``
The name of the file to be used for saving the names of the files
compressed offline.