|
1 =============== |
|
2 Django settings |
|
3 =============== |
|
4 |
|
5 A Django settings file contains all the configuration of your Django |
|
6 installation. This document explains how settings work and which settings are |
|
7 available. |
|
8 |
|
9 The basics |
|
10 ========== |
|
11 |
|
12 A settings file is just a Python module with module-level variables. |
|
13 |
|
14 Here are a couple of example settings:: |
|
15 |
|
16 DEBUG = False |
|
17 DEFAULT_FROM_EMAIL = 'webmaster@example.com' |
|
18 TEMPLATE_DIRS = ('/home/templates/mike', '/home/templates/john') |
|
19 |
|
20 Because a settings file is a Python module, the following apply: |
|
21 |
|
22 * It doesn't allow for Python syntax errors. |
|
23 * It can assign settings dynamically using normal Python syntax. |
|
24 For example:: |
|
25 |
|
26 MY_SETTING = [str(i) for i in range(30)] |
|
27 |
|
28 * It can import values from other settings files. |
|
29 |
|
30 Designating the settings |
|
31 ======================== |
|
32 |
|
33 When you use Django, you have to tell it which settings you're using. Do this |
|
34 by using an environment variable, ``DJANGO_SETTINGS_MODULE``. |
|
35 |
|
36 The value of ``DJANGO_SETTINGS_MODULE`` should be in Python path syntax, e.g. |
|
37 ``mysite.settings``. Note that the settings module should be on the |
|
38 Python `import search path`_. |
|
39 |
|
40 .. _import search path: http://diveintopython.org/getting_to_know_python/everything_is_an_object.html |
|
41 |
|
42 The django-admin.py utility |
|
43 --------------------------- |
|
44 |
|
45 When using `django-admin.py`_, you can either set the environment variable |
|
46 once, or explicitly pass in the settings module each time you run the utility. |
|
47 |
|
48 Example (Unix Bash shell):: |
|
49 |
|
50 export DJANGO_SETTINGS_MODULE=mysite.settings |
|
51 django-admin.py runserver |
|
52 |
|
53 Example (Windows shell):: |
|
54 |
|
55 set DJANGO_SETTINGS_MODULE=mysite.settings |
|
56 django-admin.py runserver |
|
57 |
|
58 Use the ``--settings`` command-line argument to specify the settings manually:: |
|
59 |
|
60 django-admin.py runserver --settings=mysite.settings |
|
61 |
|
62 .. _django-admin.py: ../django_admin/ |
|
63 |
|
64 On the server (mod_python) |
|
65 -------------------------- |
|
66 |
|
67 In your live server environment, you'll need to tell Apache/mod_python which |
|
68 settings file to use. Do that with ``SetEnv``:: |
|
69 |
|
70 <Location "/mysite/"> |
|
71 SetHandler python-program |
|
72 PythonHandler django.core.handlers.modpython |
|
73 SetEnv DJANGO_SETTINGS_MODULE mysite.settings |
|
74 </Location> |
|
75 |
|
76 Read the `Django mod_python documentation`_ for more information. |
|
77 |
|
78 .. _Django mod_python documentation: ../modpython/ |
|
79 |
|
80 Default settings |
|
81 ================ |
|
82 |
|
83 A Django settings file doesn't have to define any settings if it doesn't need |
|
84 to. Each setting has a sensible default value. These defaults live in the file |
|
85 ``django/conf/global_settings.py``. |
|
86 |
|
87 Here's the algorithm Django uses in compiling settings: |
|
88 |
|
89 * Load settings from ``global_settings.py``. |
|
90 * Load settings from the specified settings file, overriding the global |
|
91 settings as necessary. |
|
92 |
|
93 Note that a settings file should *not* import from ``global_settings``, because |
|
94 that's redundant. |
|
95 |
|
96 Seeing which settings you've changed |
|
97 ------------------------------------ |
|
98 |
|
99 There's an easy way to view which of your settings deviate from the default |
|
100 settings. The command ``python manage.py diffsettings`` displays differences |
|
101 between the current settings file and Django's default settings. |
|
102 |
|
103 For more, see the `diffsettings documentation`_. |
|
104 |
|
105 .. _diffsettings documentation: ../django_admin/#diffsettings |
|
106 |
|
107 Using settings in Python code |
|
108 ============================= |
|
109 |
|
110 In your Django apps, use settings by importing the object |
|
111 ``django.conf.settings``. Example:: |
|
112 |
|
113 from django.conf import settings |
|
114 |
|
115 if settings.DEBUG: |
|
116 # Do something |
|
117 |
|
118 Note that ``django.conf.settings`` isn't a module -- it's an object. So |
|
119 importing individual settings is not possible:: |
|
120 |
|
121 from django.conf.settings import DEBUG # This won't work. |
|
122 |
|
123 Also note that your code should *not* import from either ``global_settings`` or |
|
124 your own settings file. ``django.conf.settings`` abstracts the concepts of |
|
125 default settings and site-specific settings; it presents a single interface. |
|
126 It also decouples the code that uses settings from the location of your |
|
127 settings. |
|
128 |
|
129 Altering settings at runtime |
|
130 ============================ |
|
131 |
|
132 You shouldn't alter settings in your applications at runtime. For example, |
|
133 don't do this in a view:: |
|
134 |
|
135 from django.conf import settings |
|
136 |
|
137 settings.DEBUG = True # Don't do this! |
|
138 |
|
139 The only place you should assign to settings is in a settings file. |
|
140 |
|
141 Security |
|
142 ======== |
|
143 |
|
144 Because a settings file contains sensitive information, such as the database |
|
145 password, you should make every attempt to limit access to it. For example, |
|
146 change its file permissions so that only you and your Web server's user can |
|
147 read it. This is especially important in a shared-hosting environment. |
|
148 |
|
149 Available settings |
|
150 ================== |
|
151 |
|
152 Here's a full list of all available settings, in alphabetical order, and their |
|
153 default values. |
|
154 |
|
155 ABSOLUTE_URL_OVERRIDES |
|
156 ---------------------- |
|
157 |
|
158 Default: ``{}`` (Empty dictionary) |
|
159 |
|
160 A dictionary mapping ``"app_label.model_name"`` strings to functions that take |
|
161 a model object and return its URL. This is a way of overriding |
|
162 ``get_absolute_url()`` methods on a per-installation basis. Example:: |
|
163 |
|
164 ABSOLUTE_URL_OVERRIDES = { |
|
165 'blogs.weblog': lambda o: "/blogs/%s/" % o.slug, |
|
166 'news.story': lambda o: "/stories/%s/%s/" % (o.pub_year, o.slug), |
|
167 } |
|
168 |
|
169 Note that the model name used in this setting should be all lower-case, regardless |
|
170 of the case of the actual model class name. |
|
171 |
|
172 ADMIN_FOR |
|
173 --------- |
|
174 |
|
175 Default: ``()`` (Empty list) |
|
176 |
|
177 Used for admin-site settings modules, this should be a tuple of settings |
|
178 modules (in the format ``'foo.bar.baz'``) for which this site is an admin. |
|
179 |
|
180 The admin site uses this in its automatically-introspected documentation of |
|
181 models, views and template tags. |
|
182 |
|
183 ADMIN_MEDIA_PREFIX |
|
184 ------------------ |
|
185 |
|
186 Default: ``'/media/'`` |
|
187 |
|
188 The URL prefix for admin media -- CSS, JavaScript and images. Make sure to use |
|
189 a trailing slash. |
|
190 |
|
191 ADMINS |
|
192 ------ |
|
193 |
|
194 Default: ``()`` (Empty tuple) |
|
195 |
|
196 A tuple that lists people who get code error notifications. When |
|
197 ``DEBUG=False`` and a view raises an exception, Django will e-mail these people |
|
198 with the full exception information. Each member of the tuple should be a tuple |
|
199 of (Full name, e-mail address). Example:: |
|
200 |
|
201 (('John', 'john@example.com'), ('Mary', 'mary@example.com')) |
|
202 |
|
203 Note that Django will e-mail *all* of these people whenever an error happens. See the |
|
204 section on `error reporting via e-mail`_ for more information. |
|
205 |
|
206 ALLOWED_INCLUDE_ROOTS |
|
207 --------------------- |
|
208 |
|
209 Default: ``()`` (Empty tuple) |
|
210 |
|
211 A tuple of strings representing allowed prefixes for the ``{% ssi %}`` template |
|
212 tag. This is a security measure, so that template authors can't access files |
|
213 that they shouldn't be accessing. |
|
214 |
|
215 For example, if ``ALLOWED_INCLUDE_ROOTS`` is ``('/home/html', '/var/www')``, |
|
216 then ``{% ssi /home/html/foo.txt %}`` would work, but ``{% ssi /etc/passwd %}`` |
|
217 wouldn't. |
|
218 |
|
219 APPEND_SLASH |
|
220 ------------ |
|
221 |
|
222 Default: ``True`` |
|
223 |
|
224 Whether to append trailing slashes to URLs. This is only used if |
|
225 ``CommonMiddleware`` is installed (see the `middleware docs`_). See also |
|
226 ``PREPEND_WWW``. |
|
227 |
|
228 CACHE_BACKEND |
|
229 ------------- |
|
230 |
|
231 Default: ``'simple://'`` |
|
232 |
|
233 The cache backend to use. See the `cache docs`_. |
|
234 |
|
235 CACHE_MIDDLEWARE_KEY_PREFIX |
|
236 |
|
237 Default: ``''`` (Empty string) |
|
238 |
|
239 The cache key prefix that the cache middleware should use. See the |
|
240 `cache docs`_. |
|
241 |
|
242 DATABASE_ENGINE |
|
243 --------------- |
|
244 |
|
245 Default: ``''`` (Empty string) |
|
246 |
|
247 Which database backend to use. Either ``'postgresql_psycopg2'``, |
|
248 ``'postgresql'``, ``'mysql'``, ``'mysql_old'``, ``'sqlite3'`` or |
|
249 ``'ado_mssql'``. |
|
250 |
|
251 DATABASE_HOST |
|
252 ------------- |
|
253 |
|
254 Default: ``''`` (Empty string) |
|
255 |
|
256 Which host to use when connecting to the database. An empty string means |
|
257 localhost. Not used with SQLite. |
|
258 |
|
259 If this value starts with a forward slash (``'/'``) and you're using MySQL, |
|
260 MySQL will connect via a Unix socket to the specified socket. For example:: |
|
261 |
|
262 DATABASE_HOST = '/var/run/mysql' |
|
263 |
|
264 If you're using MySQL and this value *doesn't* start with a forward slash, then |
|
265 this value is assumed to be the host. |
|
266 |
|
267 DATABASE_NAME |
|
268 ------------- |
|
269 |
|
270 Default: ``''`` (Empty string) |
|
271 |
|
272 The name of the database to use. For SQLite, it's the full path to the database |
|
273 file. |
|
274 |
|
275 DATABASE_OPTIONS |
|
276 ---------------- |
|
277 |
|
278 Default: ``{}`` (Empty dictionary) |
|
279 |
|
280 Extra parameters to use when connecting to the database. Consult backend |
|
281 module's document for available keywords. |
|
282 |
|
283 DATABASE_PASSWORD |
|
284 ----------------- |
|
285 |
|
286 Default: ``''`` (Empty string) |
|
287 |
|
288 The password to use when connecting to the database. Not used with SQLite. |
|
289 |
|
290 DATABASE_PORT |
|
291 ------------- |
|
292 |
|
293 Default: ``''`` (Empty string) |
|
294 |
|
295 The port to use when connecting to the database. An empty string means the |
|
296 default port. Not used with SQLite. |
|
297 |
|
298 DATABASE_USER |
|
299 ------------- |
|
300 |
|
301 Default: ``''`` (Empty string) |
|
302 |
|
303 The username to use when connecting to the database. Not used with SQLite. |
|
304 |
|
305 DATE_FORMAT |
|
306 ----------- |
|
307 |
|
308 Default: ``'N j, Y'`` (e.g. ``Feb. 4, 2003``) |
|
309 |
|
310 The default formatting to use for date fields on Django admin change-list |
|
311 pages -- and, possibly, by other parts of the system. See |
|
312 `allowed date format strings`_. |
|
313 |
|
314 See also DATETIME_FORMAT, TIME_FORMAT, YEAR_MONTH_FORMAT and MONTH_DAY_FORMAT. |
|
315 |
|
316 .. _allowed date format strings: ../templates/#now |
|
317 |
|
318 DATETIME_FORMAT |
|
319 --------------- |
|
320 |
|
321 Default: ``'N j, Y, P'`` (e.g. ``Feb. 4, 2003, 4 p.m.``) |
|
322 |
|
323 The default formatting to use for datetime fields on Django admin change-list |
|
324 pages -- and, possibly, by other parts of the system. See |
|
325 `allowed date format strings`_. |
|
326 |
|
327 See also DATE_FORMAT, DATETIME_FORMAT, TIME_FORMAT, YEAR_MONTH_FORMAT and MONTH_DAY_FORMAT. |
|
328 |
|
329 .. _allowed date format strings: ../templates/#now |
|
330 |
|
331 DEBUG |
|
332 ----- |
|
333 |
|
334 Default: ``False`` |
|
335 |
|
336 A boolean that turns on/off debug mode. |
|
337 |
|
338 If you define custom settings, django/views/debug.py has a ``HIDDEN_SETTINGS`` |
|
339 regular expression which will hide from the DEBUG view anything that contins |
|
340 ``'SECRET``, ``PASSWORD``, or ``PROFANITIES'``. This allows untrusted users to |
|
341 be able to give backtraces without seeing sensitive (or offensive) settings. |
|
342 |
|
343 Still, note that there are always going to be sections of your debug output that |
|
344 are inapporpriate for public consumption. File paths, configuration options, and |
|
345 the like all give attackers extra information about your server. Never deploy a |
|
346 site with ``DEBUG`` turned on. |
|
347 |
|
348 DEFAULT_CHARSET |
|
349 --------------- |
|
350 |
|
351 Default: ``'utf-8'`` |
|
352 |
|
353 Default charset to use for all ``HttpResponse`` objects, if a MIME type isn't |
|
354 manually specified. Used with ``DEFAULT_CONTENT_TYPE`` to construct the |
|
355 ``Content-Type`` header. |
|
356 |
|
357 DEFAULT_CONTENT_TYPE |
|
358 -------------------- |
|
359 |
|
360 Default: ``'text/html'`` |
|
361 |
|
362 Default content type to use for all ``HttpResponse`` objects, if a MIME type |
|
363 isn't manually specified. Used with ``DEFAULT_CHARSET`` to construct the |
|
364 ``Content-Type`` header. |
|
365 |
|
366 DEFAULT_FROM_EMAIL |
|
367 ------------------ |
|
368 |
|
369 Default: ``'webmaster@localhost'`` |
|
370 |
|
371 Default e-mail address to use for various automated correspondence from the |
|
372 site manager(s). |
|
373 |
|
374 DISALLOWED_USER_AGENTS |
|
375 ---------------------- |
|
376 |
|
377 Default: ``()`` (Empty tuple) |
|
378 |
|
379 List of compiled regular expression objects representing User-Agent strings |
|
380 that are not allowed to visit any page, systemwide. Use this for bad |
|
381 robots/crawlers. This is only used if ``CommonMiddleware`` is installed (see |
|
382 the `middleware docs`_). |
|
383 |
|
384 EMAIL_HOST |
|
385 ---------- |
|
386 |
|
387 Default: ``'localhost'`` |
|
388 |
|
389 The host to use for sending e-mail. |
|
390 |
|
391 See also ``EMAIL_PORT``. |
|
392 |
|
393 EMAIL_HOST_PASSWORD |
|
394 ------------------- |
|
395 |
|
396 Default: ``''`` (Empty string) |
|
397 |
|
398 Username to use for the SMTP server defined in ``EMAIL_HOST``. If empty, |
|
399 Django won't attempt authentication. |
|
400 |
|
401 See also ``EMAIL_HOST_USER``. |
|
402 |
|
403 EMAIL_HOST_USER |
|
404 --------------- |
|
405 |
|
406 Default: ``''`` (Empty string) |
|
407 |
|
408 Username to use for the SMTP server defined in ``EMAIL_HOST``. If empty, |
|
409 Django won't attempt authentication. |
|
410 |
|
411 See also ``EMAIL_HOST_PASSWORD``. |
|
412 |
|
413 EMAIL_PORT |
|
414 ---------- |
|
415 |
|
416 Default: ``25`` |
|
417 |
|
418 Port to use for the SMTP server defined in ``EMAIL_HOST``. |
|
419 |
|
420 EMAIL_SUBJECT_PREFIX |
|
421 -------------------- |
|
422 |
|
423 Default: ``'[Django] '`` |
|
424 |
|
425 Subject-line prefix for e-mail messages sent with ``django.core.mail.mail_admins`` |
|
426 or ``django.core.mail.mail_managers``. You'll probably want to include the |
|
427 trailing space. |
|
428 |
|
429 FIXTURE_DIRS |
|
430 ------------- |
|
431 |
|
432 Default: ``()`` (Empty tuple) |
|
433 |
|
434 List of locations of the fixture data files, in search order. Note that |
|
435 these paths should use Unix-style forward slashes, even on Windows. See |
|
436 `Testing Django Applications`_. |
|
437 |
|
438 .. _Testing Django Applications: ../testing/ |
|
439 |
|
440 IGNORABLE_404_ENDS |
|
441 ------------------ |
|
442 |
|
443 Default: ``('mail.pl', 'mailform.pl', 'mail.cgi', 'mailform.cgi', 'favicon.ico', '.php')`` |
|
444 |
|
445 See also ``IGNORABLE_404_STARTS`` and ``Error reporting via e-mail``. |
|
446 |
|
447 IGNORABLE_404_STARTS |
|
448 -------------------- |
|
449 |
|
450 Default: ``('/cgi-bin/', '/_vti_bin', '/_vti_inf')`` |
|
451 |
|
452 A tuple of strings that specify beginnings of URLs that should be ignored by |
|
453 the 404 e-mailer. See ``SEND_BROKEN_LINK_EMAILS``, ``IGNORABLE_404_ENDS`` and |
|
454 the section on `error reporting via e-mail`_. |
|
455 |
|
456 INSTALLED_APPS |
|
457 -------------- |
|
458 |
|
459 Default: ``()`` (Empty tuple) |
|
460 |
|
461 A tuple of strings designating all applications that are enabled in this Django |
|
462 installation. Each string should be a full Python path to a Python package that |
|
463 contains a Django application, as created by `django-admin.py startapp`_. |
|
464 |
|
465 .. _django-admin.py startapp: ../django_admin/#startapp-appname |
|
466 |
|
467 INTERNAL_IPS |
|
468 ------------ |
|
469 |
|
470 Default: ``()`` (Empty tuple) |
|
471 |
|
472 A tuple of IP addresses, as strings, that: |
|
473 |
|
474 * See debug comments, when ``DEBUG`` is ``True`` |
|
475 * Receive X headers if the ``XViewMiddleware`` is installed (see the |
|
476 `middleware docs`_) |
|
477 |
|
478 JING_PATH |
|
479 --------- |
|
480 |
|
481 Default: ``'/usr/bin/jing'`` |
|
482 |
|
483 Path to the "Jing" executable. Jing is a RELAX NG validator, and Django uses it |
|
484 to validate each ``XMLField`` in your models. |
|
485 See http://www.thaiopensource.com/relaxng/jing.html . |
|
486 |
|
487 LANGUAGE_CODE |
|
488 ------------- |
|
489 |
|
490 Default: ``'en-us'`` |
|
491 |
|
492 A string representing the language code for this installation. This should be |
|
493 in standard language format. For example, U.S. English is ``"en-us"``. See the |
|
494 `internationalization docs`_. |
|
495 |
|
496 .. _internationalization docs: ../i18n/ |
|
497 |
|
498 LANGUAGES |
|
499 --------- |
|
500 |
|
501 Default: A tuple of all available languages. Currently, this is:: |
|
502 |
|
503 LANGUAGES = ( |
|
504 ('ar', _('Arabic')), |
|
505 ('bn', _('Bengali')), |
|
506 ('cs', _('Czech')), |
|
507 ('cy', _('Welsh')), |
|
508 ('da', _('Danish')), |
|
509 ('de', _('German')), |
|
510 ('el', _('Greek')), |
|
511 ('en', _('English')), |
|
512 ('es', _('Spanish')), |
|
513 ('es_AR', _('Argentinean Spanish')), |
|
514 ('fr', _('French')), |
|
515 ('gl', _('Galician')), |
|
516 ('hu', _('Hungarian')), |
|
517 ('he', _('Hebrew')), |
|
518 ('is', _('Icelandic')), |
|
519 ('it', _('Italian')), |
|
520 ('ja', _('Japanese')), |
|
521 ('nl', _('Dutch')), |
|
522 ('no', _('Norwegian')), |
|
523 ('pt-br', _('Brazilian')), |
|
524 ('ro', _('Romanian')), |
|
525 ('ru', _('Russian')), |
|
526 ('sk', _('Slovak')), |
|
527 ('sl', _('Slovenian')), |
|
528 ('sr', _('Serbian')), |
|
529 ('sv', _('Swedish')), |
|
530 ('ta', _('Tamil')), |
|
531 ('uk', _('Ukrainian')), |
|
532 ('zh-cn', _('Simplified Chinese')), |
|
533 ('zh-tw', _('Traditional Chinese')), |
|
534 ) |
|
535 |
|
536 A tuple of two-tuples in the format (language code, language name). This |
|
537 specifies which languages are available for language selection. See the |
|
538 `internationalization docs`_ for details. |
|
539 |
|
540 Generally, the default value should suffice. Only set this setting if you want |
|
541 to restrict language selection to a subset of the Django-provided languages. |
|
542 |
|
543 If you define a custom ``LANGUAGES`` setting, it's OK to mark the languages as |
|
544 translation strings (as in the default value displayed above) -- but use a |
|
545 "dummy" ``gettext()`` function, not the one in ``django.utils.translation``. |
|
546 You should *never* import ``django.utils.translation`` from within your |
|
547 settings file, because that module in itself depends on the settings, and that |
|
548 would cause a circular import. |
|
549 |
|
550 The solution is to use a "dummy" ``gettext()`` function. Here's a sample |
|
551 settings file:: |
|
552 |
|
553 gettext = lambda s: s |
|
554 |
|
555 LANGUAGES = ( |
|
556 ('de', gettext('German')), |
|
557 ('en', gettext('English')), |
|
558 ) |
|
559 |
|
560 With this arrangement, ``make-messages.py`` will still find and mark these |
|
561 strings for translation, but the translation won't happen at runtime -- so |
|
562 you'll have to remember to wrap the languages in the *real* ``gettext()`` in |
|
563 any code that uses ``LANGUAGES`` at runtime. |
|
564 |
|
565 MANAGERS |
|
566 -------- |
|
567 |
|
568 Default: ``()`` (Empty tuple) |
|
569 |
|
570 A tuple in the same format as ``ADMINS`` that specifies who should get |
|
571 broken-link notifications when ``SEND_BROKEN_LINK_EMAILS=True``. |
|
572 |
|
573 MEDIA_ROOT |
|
574 ---------- |
|
575 |
|
576 Default: ``''`` (Empty string) |
|
577 |
|
578 Absolute path to the directory that holds media for this installation. |
|
579 Example: ``"/home/media/media.lawrence.com/"`` See also ``MEDIA_URL``. |
|
580 |
|
581 MEDIA_URL |
|
582 --------- |
|
583 |
|
584 Default: ``''`` (Empty string) |
|
585 |
|
586 URL that handles the media served from ``MEDIA_ROOT``. |
|
587 Example: ``"http://media.lawrence.com"`` |
|
588 |
|
589 Note that this should have a trailing slash if it has a path component. |
|
590 |
|
591 Good: ``"http://www.example.com/static/"`` |
|
592 Bad: ``"http://www.example.com/static"`` |
|
593 |
|
594 MIDDLEWARE_CLASSES |
|
595 ------------------ |
|
596 |
|
597 Default:: |
|
598 |
|
599 ("django.contrib.sessions.middleware.SessionMiddleware", |
|
600 "django.contrib.auth.middleware.AuthenticationMiddleware", |
|
601 "django.middleware.common.CommonMiddleware", |
|
602 "django.middleware.doc.XViewMiddleware") |
|
603 |
|
604 A tuple of middleware classes to use. See the `middleware docs`_. |
|
605 |
|
606 MONTH_DAY_FORMAT |
|
607 ---------------- |
|
608 |
|
609 Default: ``'F j'`` |
|
610 |
|
611 The default formatting to use for date fields on Django admin change-list |
|
612 pages -- and, possibly, by other parts of the system -- in cases when only the |
|
613 month and day are displayed. |
|
614 |
|
615 For example, when a Django admin change-list page is being filtered by a date |
|
616 drilldown, the header for a given day displays the day and month. Different |
|
617 locales have different formats. For example, U.S. English would say |
|
618 "January 1," whereas Spanish might say "1 Enero." |
|
619 |
|
620 See `allowed date format strings`_. See also DATE_FORMAT, DATETIME_FORMAT, |
|
621 TIME_FORMAT and YEAR_MONTH_FORMAT. |
|
622 |
|
623 PREPEND_WWW |
|
624 ----------- |
|
625 |
|
626 Default: ``False`` |
|
627 |
|
628 Whether to prepend the "www." subdomain to URLs that don't have it. This is |
|
629 only used if ``CommonMiddleware`` is installed (see the `middleware docs`_). |
|
630 See also ``APPEND_SLASH``. |
|
631 |
|
632 PROFANITIES_LIST |
|
633 ---------------- |
|
634 |
|
635 A tuple of profanities, as strings, that will trigger a validation error when |
|
636 the ``hasNoProfanities`` validator is called. |
|
637 |
|
638 We don't list the default values here, because that would be profane. To see |
|
639 the default values, see the file ``django/conf/global_settings.py``. |
|
640 |
|
641 ROOT_URLCONF |
|
642 ------------ |
|
643 |
|
644 Default: Not defined |
|
645 |
|
646 A string representing the full Python import path to your root URLconf. For example: |
|
647 ``"mydjangoapps.urls"``. See `How Django processes a request`_. |
|
648 |
|
649 .. _How Django processes a request: ../url_dispatch/#how-django-processes-a-request |
|
650 |
|
651 SECRET_KEY |
|
652 ---------- |
|
653 |
|
654 Default: ``''`` (Empty string) |
|
655 |
|
656 A secret key for this particular Django installation. Used to provide a seed in |
|
657 secret-key hashing algorithms. Set this to a random string -- the longer, the |
|
658 better. ``django-admin.py startproject`` creates one automatically. |
|
659 |
|
660 SEND_BROKEN_LINK_EMAILS |
|
661 ----------------------- |
|
662 |
|
663 Default: ``False`` |
|
664 |
|
665 Whether to send an e-mail to the ``MANAGERS`` each time somebody visits a |
|
666 Django-powered page that is 404ed with a non-empty referer (i.e., a broken |
|
667 link). This is only used if ``CommonMiddleware`` is installed (see the |
|
668 `middleware docs`_). See also ``IGNORABLE_404_STARTS``, |
|
669 ``IGNORABLE_404_ENDS`` and the section on `error reporting via e-mail`_ |
|
670 |
|
671 SERIALIZATION_MODULES |
|
672 --------------------- |
|
673 |
|
674 Default: Not defined. |
|
675 |
|
676 A dictionary of modules containing serializer definitions (provided as |
|
677 strings), keyed by a string identifier for that serialization type. For |
|
678 example, to define a YAML serializer, use:: |
|
679 |
|
680 SERIALIZATION_MODULES = { 'yaml' : 'path.to.yaml_serializer' } |
|
681 |
|
682 SERVER_EMAIL |
|
683 ------------ |
|
684 |
|
685 Default: ``'root@localhost'`` |
|
686 |
|
687 The e-mail address that error messages come from, such as those sent to |
|
688 ``ADMINS`` and ``MANAGERS``. |
|
689 |
|
690 SESSION_COOKIE_AGE |
|
691 ------------------ |
|
692 |
|
693 Default: ``1209600`` (2 weeks, in seconds) |
|
694 |
|
695 The age of session cookies, in seconds. See the `session docs`_. |
|
696 |
|
697 SESSION_COOKIE_DOMAIN |
|
698 --------------------- |
|
699 |
|
700 Default: ``None`` |
|
701 |
|
702 The domain to use for session cookies. Set this to a string such as |
|
703 ``".lawrence.com"`` for cross-domain cookies, or use ``None`` for a standard |
|
704 domain cookie. See the `session docs`_. |
|
705 |
|
706 SESSION_COOKIE_NAME |
|
707 ------------------- |
|
708 |
|
709 Default: ``'sessionid'`` |
|
710 |
|
711 The name of the cookie to use for sessions. This can be whatever you want. |
|
712 See the `session docs`_. |
|
713 |
|
714 SESSION_COOKIE_SECURE |
|
715 --------------------- |
|
716 |
|
717 Default: ``False`` |
|
718 |
|
719 Whether to use a secure cookie for the session cookie. If this is set to |
|
720 ``True``, the cookie will be marked as "secure," which means browsers may |
|
721 ensure that the cookie is only sent under an HTTPS connection. |
|
722 See the `session docs`_. |
|
723 |
|
724 SESSION_EXPIRE_AT_BROWSER_CLOSE |
|
725 ------------------------------- |
|
726 |
|
727 Default: ``False`` |
|
728 |
|
729 Whether to expire the session when the user closes his or her browser. |
|
730 See the `session docs`_. |
|
731 |
|
732 SESSION_SAVE_EVERY_REQUEST |
|
733 -------------------------- |
|
734 |
|
735 Default: ``False`` |
|
736 |
|
737 Whether to save the session data on every request. See the `session docs`_. |
|
738 |
|
739 SITE_ID |
|
740 ------- |
|
741 |
|
742 Default: Not defined |
|
743 |
|
744 The ID, as an integer, of the current site in the ``django_site`` database |
|
745 table. This is used so that application data can hook into specific site(s) |
|
746 and a single database can manage content for multiple sites. |
|
747 |
|
748 See the `site framework docs`_. |
|
749 |
|
750 .. _site framework docs: ../sites/ |
|
751 |
|
752 TEMPLATE_CONTEXT_PROCESSORS |
|
753 --------------------------- |
|
754 |
|
755 Default:: |
|
756 |
|
757 ("django.core.context_processors.auth", |
|
758 "django.core.context_processors.debug", |
|
759 "django.core.context_processors.i18n") |
|
760 |
|
761 A tuple of callables that are used to populate the context in ``RequestContext``. |
|
762 These callables take a request object as their argument and return a dictionary |
|
763 of items to be merged into the context. |
|
764 |
|
765 TEMPLATE_DEBUG |
|
766 -------------- |
|
767 |
|
768 Default: ``False`` |
|
769 |
|
770 A boolean that turns on/off template debug mode. If this is ``True``, the fancy |
|
771 error page will display a detailed report for any ``TemplateSyntaxError``. This |
|
772 report contains the relevant snippet of the template, with the appropriate line |
|
773 highlighted. |
|
774 |
|
775 Note that Django only displays fancy error pages if ``DEBUG`` is ``True``, so |
|
776 you'll want to set that to take advantage of this setting. |
|
777 |
|
778 See also DEBUG. |
|
779 |
|
780 TEMPLATE_DIRS |
|
781 ------------- |
|
782 |
|
783 Default: ``()`` (Empty tuple) |
|
784 |
|
785 List of locations of the template source files, in search order. Note that |
|
786 these paths should use Unix-style forward slashes, even on Windows. |
|
787 |
|
788 See the `template documentation`_. |
|
789 |
|
790 TEMPLATE_LOADERS |
|
791 ---------------- |
|
792 |
|
793 Default: ``('django.template.loaders.filesystem.load_template_source',)`` |
|
794 |
|
795 A tuple of callables (as strings) that know how to import templates from |
|
796 various sources. See the `template documentation`_. |
|
797 |
|
798 TEMPLATE_STRING_IF_INVALID |
|
799 -------------------------- |
|
800 |
|
801 Default: ``''`` (Empty string) |
|
802 |
|
803 Output, as a string, that the template system should use for invalid (e.g. |
|
804 misspelled) variables. See `How invalid variables are handled`_. |
|
805 |
|
806 .. _How invalid variables are handled: ../templates_python/#how-invalid-variables-are-handled |
|
807 |
|
808 TEST_RUNNER |
|
809 ----------- |
|
810 |
|
811 Default: ``'django.test.simple.run_tests'`` |
|
812 |
|
813 The name of the method to use for starting the test suite. See |
|
814 `Testing Django Applications`_. |
|
815 |
|
816 .. _Testing Django Applications: ../testing/ |
|
817 |
|
818 TEST_DATABASE_NAME |
|
819 ------------------ |
|
820 |
|
821 Default: ``None`` |
|
822 |
|
823 The name of database to use when running the test suite. If a value of |
|
824 ``None`` is specified, the test database will use the name ``'test_' + settings.DATABASE_NAME``. See `Testing Django Applications`_. |
|
825 |
|
826 .. _Testing Django Applications: ../testing/ |
|
827 |
|
828 TIME_FORMAT |
|
829 ----------- |
|
830 |
|
831 Default: ``'P'`` (e.g. ``4 p.m.``) |
|
832 |
|
833 The default formatting to use for time fields on Django admin change-list |
|
834 pages -- and, possibly, by other parts of the system. See |
|
835 `allowed date format strings`_. |
|
836 |
|
837 See also DATE_FORMAT, DATETIME_FORMAT, TIME_FORMAT, YEAR_MONTH_FORMAT and |
|
838 MONTH_DAY_FORMAT. |
|
839 |
|
840 .. _allowed date format strings: ../templates/#now |
|
841 |
|
842 TIME_ZONE |
|
843 --------- |
|
844 |
|
845 Default: ``'America/Chicago'`` |
|
846 |
|
847 A string representing the time zone for this installation. `See available choices`_. |
|
848 (Note that list of available choices lists more than one on the same line; |
|
849 you'll want to use just one of the choices for a given time zone. For instance, |
|
850 one line says ``'Europe/London GB GB-Eire'``, but you should use the first bit |
|
851 of that -- ``'Europe/London'`` -- as your ``TIME_ZONE`` setting.) |
|
852 |
|
853 Note that this is the time zone to which Django will convert all dates/times -- |
|
854 not necessarily the timezone of the server. For example, one server may serve |
|
855 multiple Django-powered sites, each with a separate time-zone setting. |
|
856 |
|
857 Normally, Django sets the ``os.environ['TZ']`` variable to the time zone you |
|
858 specify in the ``TIME_ZONE`` setting. Thus, all your views and models will |
|
859 automatically operate in the correct time zone. However, if you're using the |
|
860 manual configuration option (see below), Django will *not* touch the ``TZ`` |
|
861 environment variable, and it'll be up to you to ensure your processes are |
|
862 running in the correct environment. |
|
863 |
|
864 .. note:: |
|
865 Django cannot reliably use alternate time zones in a Windows environment. |
|
866 If you're running Django on Windows, this variable must be set to match the |
|
867 system timezone. |
|
868 |
|
869 URL_VALIDATOR_USER_AGENT |
|
870 ------------------------ |
|
871 |
|
872 Default: ``Django/<version> (http://www.djangoproject.com/)`` |
|
873 |
|
874 The string to use as the ``User-Agent`` header when checking to see if URLs |
|
875 exist (see the ``verify_exists`` option on URLField_). |
|
876 |
|
877 .. _URLField: ../model_api/#urlfield |
|
878 |
|
879 USE_ETAGS |
|
880 --------- |
|
881 |
|
882 Default: ``False`` |
|
883 |
|
884 A boolean that specifies whether to output the "Etag" header. This saves |
|
885 bandwidth but slows down performance. This is only used if ``CommonMiddleware`` |
|
886 is installed (see the `middleware docs`_). |
|
887 |
|
888 USE_I18N |
|
889 -------- |
|
890 |
|
891 Default: ``True`` |
|
892 |
|
893 A boolean that specifies whether Django's internationalization system should be |
|
894 enabled. This provides an easy way to turn it off, for performance. If this is |
|
895 set to ``False``, Django will make some optimizations so as not to load the |
|
896 internationalization machinery. |
|
897 |
|
898 YEAR_MONTH_FORMAT |
|
899 ----------------- |
|
900 |
|
901 Default: ``'F Y'`` |
|
902 |
|
903 The default formatting to use for date fields on Django admin change-list |
|
904 pages -- and, possibly, by other parts of the system -- in cases when only the |
|
905 year and month are displayed. |
|
906 |
|
907 For example, when a Django admin change-list page is being filtered by a date |
|
908 drilldown, the header for a given month displays the month and the year. |
|
909 Different locales have different formats. For example, U.S. English would say |
|
910 "January 2006," whereas another locale might say "2006/January." |
|
911 |
|
912 See `allowed date format strings`_. See also DATE_FORMAT, DATETIME_FORMAT, |
|
913 TIME_FORMAT and MONTH_DAY_FORMAT. |
|
914 |
|
915 .. _cache docs: ../cache/ |
|
916 .. _middleware docs: ../middleware/ |
|
917 .. _session docs: ../sessions/ |
|
918 .. _See available choices: http://www.postgresql.org/docs/8.1/static/datetime-keywords.html#DATETIME-TIMEZONE-SET-TABLE |
|
919 .. _template documentation: ../templates_python/ |
|
920 |
|
921 Creating your own settings |
|
922 ========================== |
|
923 |
|
924 There's nothing stopping you from creating your own settings, for your own |
|
925 Django apps. Just follow these conventions: |
|
926 |
|
927 * Setting names are in all uppercase. |
|
928 * For settings that are sequences, use tuples instead of lists. This is |
|
929 purely for performance. |
|
930 * Don't reinvent an already-existing setting. |
|
931 |
|
932 Using settings without setting DJANGO_SETTINGS_MODULE |
|
933 ===================================================== |
|
934 |
|
935 In some cases, you might want to bypass the ``DJANGO_SETTINGS_MODULE`` |
|
936 environment variable. For example, if you're using the template system by |
|
937 itself, you likely don't want to have to set up an environment variable |
|
938 pointing to a settings module. |
|
939 |
|
940 In these cases, you can configure Django's settings manually. Do this by |
|
941 calling ``django.conf.settings.configure()``. |
|
942 |
|
943 Example:: |
|
944 |
|
945 from django.conf import settings |
|
946 |
|
947 settings.configure(DEBUG=True, TEMPLATE_DEBUG=True, |
|
948 TEMPLATE_DIRS=('/home/web-apps/myapp', '/home/web-apps/base')) |
|
949 |
|
950 Pass ``configure()`` as many keyword arguments as you'd like, with each keyword |
|
951 argument representing a setting and its value. Each argument name should be all |
|
952 uppercase, with the same name as the settings described above. If a particular |
|
953 setting is not passed to ``configure()`` and is needed at some later point, |
|
954 Django will use the default setting value. |
|
955 |
|
956 Configuring Django in this fashion is mostly necessary -- and, indeed, |
|
957 recommended -- when you're using a piece of the framework inside a larger |
|
958 application. |
|
959 |
|
960 Consequently, when configured via ``settings.configure()``, Django will not |
|
961 make any modifications to the process environment variables. (See the |
|
962 explanation of ``TIME_ZONE``, above, for why this would normally occur.) It's |
|
963 assumed that you're already in full control of your environment in these cases. |
|
964 |
|
965 Custom default settings |
|
966 ----------------------- |
|
967 |
|
968 If you'd like default values to come from somewhere other than |
|
969 ``django.conf.global_settings``, you can pass in a module or class that |
|
970 provides the default settings as the ``default_settings`` argument (or as the |
|
971 first positional argument) in the call to ``configure()``. |
|
972 |
|
973 In this example, default settings are taken from ``myapp_defaults``, and the |
|
974 ``DEBUG`` setting is set to ``True``, regardless of its value in |
|
975 ``myapp_defaults``:: |
|
976 |
|
977 from django.conf import settings |
|
978 from myapp import myapp_defaults |
|
979 |
|
980 settings.configure(default_settings=myapp_defaults, DEBUG=True) |
|
981 |
|
982 The following example, which uses ``myapp_defaults`` as a positional argument, |
|
983 is equivalent:: |
|
984 |
|
985 settings.configure(myapp_defaults, DEBUG = True) |
|
986 |
|
987 Normally, you will not need to override the defaults in this fashion. The |
|
988 Django defaults are sufficiently tame that you can safely use them. Be aware |
|
989 that if you do pass in a new default module, it entirely *replaces* the Django |
|
990 defaults, so you must specify a value for every possible setting that might be |
|
991 used in that code you are importing. Check in |
|
992 ``django.conf.settings.global_settings`` for the full list. |
|
993 |
|
994 Either configure() or DJANGO_SETTINGS_MODULE is required |
|
995 -------------------------------------------------------- |
|
996 |
|
997 If you're not setting the ``DJANGO_SETTINGS_MODULE`` environment variable, you |
|
998 *must* call ``configure()`` at some point before using any code that reads |
|
999 settings. |
|
1000 |
|
1001 If you don't set ``DJANGO_SETTINGS_MODULE`` and don't call ``configure()``, |
|
1002 Django will raise an ``EnvironmentError`` exception the first time a setting |
|
1003 is accessed. |
|
1004 |
|
1005 If you set ``DJANGO_SETTINGS_MODULE``, access settings values somehow, *then* |
|
1006 call ``configure()``, Django will raise an ``EnvironmentError`` saying settings |
|
1007 have already been configured. |
|
1008 |
|
1009 Also, it's an error to call ``configure()`` more than once, or to call |
|
1010 ``configure()`` after any setting has been accessed. |
|
1011 |
|
1012 It boils down to this: Use exactly one of either ``configure()`` or |
|
1013 ``DJANGO_SETTINGS_MODULE``. Not both, and not neither. |
|
1014 |
|
1015 Error reporting via e-mail |
|
1016 ========================== |
|
1017 |
|
1018 Server errors |
|
1019 ------------- |
|
1020 |
|
1021 When ``DEBUG`` is ``False``, Django will e-mail the users listed in the |
|
1022 ``ADMIN`` setting whenever your code raises an unhandled exception and results |
|
1023 in an internal server error (HTTP status code 500). This gives the |
|
1024 administrators immediate notification of any errors. |
|
1025 |
|
1026 To disable this behavior, just remove all entries from the ``ADMINS`` setting. |
|
1027 |
|
1028 404 errors |
|
1029 ---------- |
|
1030 |
|
1031 When ``DEBUG`` is ``False`` and your ``MIDDLEWARE_CLASSES`` setting includes |
|
1032 ``CommonMiddleware``, Django will e-mail the users listed in the ``MANAGERS`` |
|
1033 setting whenever your code raises a 404 and the request has a referer. |
|
1034 (It doesn't bother to e-mail for 404s that don't have a referer.) |
|
1035 |
|
1036 You can tell Django to stop reporting particular 404s by tweaking the |
|
1037 ``IGNORABLE_404_ENDS`` and ``IGNORABLE_404_STARTS`` settings. Both should be a |
|
1038 tuple of strings. For example:: |
|
1039 |
|
1040 IGNORABLE_404_ENDS = ('.php', '.cgi') |
|
1041 IGNORABLE_404_STARTS = ('/phpmyadmin/') |
|
1042 |
|
1043 In this example, a 404 to any URL ending with ``.php`` or ``.cgi`` will *not* |
|
1044 be reported. Neither will any URL starting with ``/phpmyadmin/``. |
|
1045 |
|
1046 To disable this behavior, just remove all entries from the ``MANAGERS`` setting. |