mirror of
https://github.com/django/django.git
synced 2024-12-23 09:36:06 +00:00
79e914e496
used by the cache middleware). Refs #1015. git-svn-id: http://code.djangoproject.com/svn/django/trunk@5618 bcc190cf-cafb-0310-a4f2-bffc1f526a37
1120 lines
34 KiB
Plaintext
1120 lines
34 KiB
Plaintext
===============
|
|
Django settings
|
|
===============
|
|
|
|
A Django settings file contains all the configuration of your Django
|
|
installation. This document explains how settings work and which settings are
|
|
available.
|
|
|
|
The basics
|
|
==========
|
|
|
|
A settings file is just a Python module with module-level variables.
|
|
|
|
Here are a couple of example settings::
|
|
|
|
DEBUG = False
|
|
DEFAULT_FROM_EMAIL = 'webmaster@example.com'
|
|
TEMPLATE_DIRS = ('/home/templates/mike', '/home/templates/john')
|
|
|
|
Because a settings file is a Python module, the following apply:
|
|
|
|
* It doesn't allow for Python syntax errors.
|
|
* It can assign settings dynamically using normal Python syntax.
|
|
For example::
|
|
|
|
MY_SETTING = [str(i) for i in range(30)]
|
|
|
|
* It can import values from other settings files.
|
|
|
|
Designating the settings
|
|
========================
|
|
|
|
When you use Django, you have to tell it which settings you're using. Do this
|
|
by using an environment variable, ``DJANGO_SETTINGS_MODULE``.
|
|
|
|
The value of ``DJANGO_SETTINGS_MODULE`` should be in Python path syntax, e.g.
|
|
``mysite.settings``. Note that the settings module should be on the
|
|
Python `import search path`_.
|
|
|
|
.. _import search path: http://diveintopython.org/getting_to_know_python/everything_is_an_object.html
|
|
|
|
The django-admin.py utility
|
|
---------------------------
|
|
|
|
When using `django-admin.py`_, you can either set the environment variable
|
|
once, or explicitly pass in the settings module each time you run the utility.
|
|
|
|
Example (Unix Bash shell)::
|
|
|
|
export DJANGO_SETTINGS_MODULE=mysite.settings
|
|
django-admin.py runserver
|
|
|
|
Example (Windows shell)::
|
|
|
|
set DJANGO_SETTINGS_MODULE=mysite.settings
|
|
django-admin.py runserver
|
|
|
|
Use the ``--settings`` command-line argument to specify the settings manually::
|
|
|
|
django-admin.py runserver --settings=mysite.settings
|
|
|
|
.. _django-admin.py: ../django-admin/
|
|
|
|
On the server (mod_python)
|
|
--------------------------
|
|
|
|
In your live server environment, you'll need to tell Apache/mod_python which
|
|
settings file to use. Do that with ``SetEnv``::
|
|
|
|
<Location "/mysite/">
|
|
SetHandler python-program
|
|
PythonHandler django.core.handlers.modpython
|
|
SetEnv DJANGO_SETTINGS_MODULE mysite.settings
|
|
</Location>
|
|
|
|
Read the `Django mod_python documentation`_ for more information.
|
|
|
|
.. _Django mod_python documentation: ../modpython/
|
|
|
|
Default settings
|
|
================
|
|
|
|
A Django settings file doesn't have to define any settings if it doesn't need
|
|
to. Each setting has a sensible default value. These defaults live in the file
|
|
``django/conf/global_settings.py``.
|
|
|
|
Here's the algorithm Django uses in compiling settings:
|
|
|
|
* Load settings from ``global_settings.py``.
|
|
* Load settings from the specified settings file, overriding the global
|
|
settings as necessary.
|
|
|
|
Note that a settings file should *not* import from ``global_settings``, because
|
|
that's redundant.
|
|
|
|
Seeing which settings you've changed
|
|
------------------------------------
|
|
|
|
There's an easy way to view which of your settings deviate from the default
|
|
settings. The command ``python manage.py diffsettings`` displays differences
|
|
between the current settings file and Django's default settings.
|
|
|
|
For more, see the `diffsettings documentation`_.
|
|
|
|
.. _diffsettings documentation: ../django-admin/#diffsettings
|
|
|
|
Using settings in Python code
|
|
=============================
|
|
|
|
In your Django apps, use settings by importing the object
|
|
``django.conf.settings``. Example::
|
|
|
|
from django.conf import settings
|
|
|
|
if settings.DEBUG:
|
|
# Do something
|
|
|
|
Note that ``django.conf.settings`` isn't a module -- it's an object. So
|
|
importing individual settings is not possible::
|
|
|
|
from django.conf.settings import DEBUG # This won't work.
|
|
|
|
Also note that your code should *not* import from either ``global_settings`` or
|
|
your own settings file. ``django.conf.settings`` abstracts the concepts of
|
|
default settings and site-specific settings; it presents a single interface.
|
|
It also decouples the code that uses settings from the location of your
|
|
settings.
|
|
|
|
Altering settings at runtime
|
|
============================
|
|
|
|
You shouldn't alter settings in your applications at runtime. For example,
|
|
don't do this in a view::
|
|
|
|
from django.conf import settings
|
|
|
|
settings.DEBUG = True # Don't do this!
|
|
|
|
The only place you should assign to settings is in a settings file.
|
|
|
|
Security
|
|
========
|
|
|
|
Because a settings file contains sensitive information, such as the database
|
|
password, you should make every attempt to limit access to it. For example,
|
|
change its file permissions so that only you and your Web server's user can
|
|
read it. This is especially important in a shared-hosting environment.
|
|
|
|
Available settings
|
|
==================
|
|
|
|
Here's a full list of all available settings, in alphabetical order, and their
|
|
default values.
|
|
|
|
ABSOLUTE_URL_OVERRIDES
|
|
----------------------
|
|
|
|
Default: ``{}`` (Empty dictionary)
|
|
|
|
A dictionary mapping ``"app_label.model_name"`` strings to functions that take
|
|
a model object and return its URL. This is a way of overriding
|
|
``get_absolute_url()`` methods on a per-installation basis. Example::
|
|
|
|
ABSOLUTE_URL_OVERRIDES = {
|
|
'blogs.weblog': lambda o: "/blogs/%s/" % o.slug,
|
|
'news.story': lambda o: "/stories/%s/%s/" % (o.pub_year, o.slug),
|
|
}
|
|
|
|
Note that the model name used in this setting should be all lower-case, regardless
|
|
of the case of the actual model class name.
|
|
|
|
ADMIN_FOR
|
|
---------
|
|
|
|
Default: ``()`` (Empty list)
|
|
|
|
Used for admin-site settings modules, this should be a tuple of settings
|
|
modules (in the format ``'foo.bar.baz'``) for which this site is an admin.
|
|
|
|
The admin site uses this in its automatically-introspected documentation of
|
|
models, views and template tags.
|
|
|
|
ADMIN_MEDIA_PREFIX
|
|
------------------
|
|
|
|
Default: ``'/media/'``
|
|
|
|
The URL prefix for admin media -- CSS, JavaScript and images. Make sure to use
|
|
a trailing slash.
|
|
|
|
ADMINS
|
|
------
|
|
|
|
Default: ``()`` (Empty tuple)
|
|
|
|
A tuple that lists people who get code error notifications. When
|
|
``DEBUG=False`` and a view raises an exception, Django will e-mail these people
|
|
with the full exception information. Each member of the tuple should be a tuple
|
|
of (Full name, e-mail address). Example::
|
|
|
|
(('John', 'john@example.com'), ('Mary', 'mary@example.com'))
|
|
|
|
Note that Django will e-mail *all* of these people whenever an error happens. See the
|
|
section on `error reporting via e-mail`_ for more information.
|
|
|
|
ALLOWED_INCLUDE_ROOTS
|
|
---------------------
|
|
|
|
Default: ``()`` (Empty tuple)
|
|
|
|
A tuple of strings representing allowed prefixes for the ``{% ssi %}`` template
|
|
tag. This is a security measure, so that template authors can't access files
|
|
that they shouldn't be accessing.
|
|
|
|
For example, if ``ALLOWED_INCLUDE_ROOTS`` is ``('/home/html', '/var/www')``,
|
|
then ``{% ssi /home/html/foo.txt %}`` would work, but ``{% ssi /etc/passwd %}``
|
|
wouldn't.
|
|
|
|
APPEND_SLASH
|
|
------------
|
|
|
|
Default: ``True``
|
|
|
|
Whether to append trailing slashes to URLs. This is only used if
|
|
``CommonMiddleware`` is installed (see the `middleware docs`_). See also
|
|
``PREPEND_WWW``.
|
|
|
|
CACHE_BACKEND
|
|
-------------
|
|
|
|
Default: ``'simple://'``
|
|
|
|
The cache backend to use. See the `cache docs`_.
|
|
|
|
CACHE_MIDDLEWARE_KEY_PREFIX
|
|
---------------------------
|
|
|
|
Default: ``''`` (Empty string)
|
|
|
|
The cache key prefix that the cache middleware should use. See the
|
|
`cache docs`_.
|
|
|
|
CACHE_MIDDLEWARE_SECONDS
|
|
------------------------
|
|
|
|
Default: ``600``
|
|
|
|
The default number of seconds to cache a page when the caching middleware or
|
|
``cache_page()`` decorator is used.
|
|
|
|
DATABASE_ENGINE
|
|
---------------
|
|
|
|
Default: ``''`` (Empty string)
|
|
|
|
The database backend to use. Either ``'postgresql_psycopg2'``,
|
|
``'postgresql'``, ``'mysql'``, ``'mysql_old'``, ``'sqlite3'``,
|
|
``'oracle'``, or ``'ado_mssql'``.
|
|
|
|
DATABASE_HOST
|
|
-------------
|
|
|
|
Default: ``''`` (Empty string)
|
|
|
|
Which host to use when connecting to the database. An empty string means
|
|
localhost. Not used with SQLite.
|
|
|
|
If this value starts with a forward slash (``'/'``) and you're using MySQL,
|
|
MySQL will connect via a Unix socket to the specified socket. For example::
|
|
|
|
DATABASE_HOST = '/var/run/mysql'
|
|
|
|
If you're using MySQL and this value *doesn't* start with a forward slash, then
|
|
this value is assumed to be the host.
|
|
|
|
If you're using PostgreSQL, an empty string means to use a Unix domain socket
|
|
for the connection, rather than a network connection to localhost. If you
|
|
explictly need to use a TCP/IP connection on the local machine with
|
|
PostgreSQL, specify ``localhost`` here.
|
|
|
|
DATABASE_NAME
|
|
-------------
|
|
|
|
Default: ``''`` (Empty string)
|
|
|
|
The name of the database to use. For SQLite, it's the full path to the database
|
|
file.
|
|
|
|
DATABASE_OPTIONS
|
|
----------------
|
|
|
|
Default: ``{}`` (Empty dictionary)
|
|
|
|
Extra parameters to use when connecting to the database. Consult backend
|
|
module's document for available keywords.
|
|
|
|
DATABASE_PASSWORD
|
|
-----------------
|
|
|
|
Default: ``''`` (Empty string)
|
|
|
|
The password to use when connecting to the database. Not used with SQLite.
|
|
|
|
DATABASE_PORT
|
|
-------------
|
|
|
|
Default: ``''`` (Empty string)
|
|
|
|
The port to use when connecting to the database. An empty string means the
|
|
default port. Not used with SQLite.
|
|
|
|
DATABASE_USER
|
|
-------------
|
|
|
|
Default: ``''`` (Empty string)
|
|
|
|
The username to use when connecting to the database. Not used with SQLite.
|
|
|
|
DATE_FORMAT
|
|
-----------
|
|
|
|
Default: ``'N j, Y'`` (e.g. ``Feb. 4, 2003``)
|
|
|
|
The default formatting to use for date fields on Django admin change-list
|
|
pages -- and, possibly, by other parts of the system. See
|
|
`allowed date format strings`_.
|
|
|
|
See also DATETIME_FORMAT, TIME_FORMAT, YEAR_MONTH_FORMAT and MONTH_DAY_FORMAT.
|
|
|
|
.. _allowed date format strings: ../templates/#now
|
|
|
|
DATETIME_FORMAT
|
|
---------------
|
|
|
|
Default: ``'N j, Y, P'`` (e.g. ``Feb. 4, 2003, 4 p.m.``)
|
|
|
|
The default formatting to use for datetime fields on Django admin change-list
|
|
pages -- and, possibly, by other parts of the system. See
|
|
`allowed date format strings`_.
|
|
|
|
See also DATE_FORMAT, DATETIME_FORMAT, TIME_FORMAT, YEAR_MONTH_FORMAT and MONTH_DAY_FORMAT.
|
|
|
|
.. _allowed date format strings: ../templates/#now
|
|
|
|
DEBUG
|
|
-----
|
|
|
|
Default: ``False``
|
|
|
|
A boolean that turns on/off debug mode.
|
|
|
|
If you define custom settings, django/views/debug.py has a ``HIDDEN_SETTINGS``
|
|
regular expression which will hide from the DEBUG view anything that contins
|
|
``'SECRET``, ``PASSWORD``, or ``PROFANITIES'``. This allows untrusted users to
|
|
be able to give backtraces without seeing sensitive (or offensive) settings.
|
|
|
|
Still, note that there are always going to be sections of your debug output that
|
|
are inapporpriate for public consumption. File paths, configuration options, and
|
|
the like all give attackers extra information about your server. Never deploy a
|
|
site with ``DEBUG`` turned on.
|
|
|
|
DEFAULT_CHARSET
|
|
---------------
|
|
|
|
Default: ``'utf-8'``
|
|
|
|
Default charset to use for all ``HttpResponse`` objects, if a MIME type isn't
|
|
manually specified. Used with ``DEFAULT_CONTENT_TYPE`` to construct the
|
|
``Content-Type`` header.
|
|
|
|
DEFAULT_CONTENT_TYPE
|
|
--------------------
|
|
|
|
Default: ``'text/html'``
|
|
|
|
Default content type to use for all ``HttpResponse`` objects, if a MIME type
|
|
isn't manually specified. Used with ``DEFAULT_CHARSET`` to construct the
|
|
``Content-Type`` header.
|
|
|
|
DEFAULT_FROM_EMAIL
|
|
------------------
|
|
|
|
Default: ``'webmaster@localhost'``
|
|
|
|
Default e-mail address to use for various automated correspondence from the
|
|
site manager(s).
|
|
|
|
DISALLOWED_USER_AGENTS
|
|
----------------------
|
|
|
|
Default: ``()`` (Empty tuple)
|
|
|
|
List of compiled regular expression objects representing User-Agent strings
|
|
that are not allowed to visit any page, systemwide. Use this for bad
|
|
robots/crawlers. This is only used if ``CommonMiddleware`` is installed (see
|
|
the `middleware docs`_).
|
|
|
|
EMAIL_HOST
|
|
----------
|
|
|
|
Default: ``'localhost'``
|
|
|
|
The host to use for sending e-mail.
|
|
|
|
See also ``EMAIL_PORT``.
|
|
|
|
EMAIL_HOST_PASSWORD
|
|
-------------------
|
|
|
|
Default: ``''`` (Empty string)
|
|
|
|
Password to use for the SMTP server defined in ``EMAIL_HOST``. This setting is
|
|
used in conjunction with ``EMAIL_HOST_USER`` when authenticating to the SMTP
|
|
server. If either of these settings is empty, Django won't attempt
|
|
authenticaion.
|
|
|
|
See also ``EMAIL_HOST_USER``.
|
|
|
|
EMAIL_HOST_USER
|
|
---------------
|
|
|
|
Default: ``''`` (Empty string)
|
|
|
|
Username to use for the SMTP server defined in ``EMAIL_HOST``. If empty,
|
|
Django won't attempt authentication.
|
|
|
|
See also ``EMAIL_HOST_PASSWORD``.
|
|
|
|
EMAIL_PORT
|
|
----------
|
|
|
|
Default: ``25``
|
|
|
|
Port to use for the SMTP server defined in ``EMAIL_HOST``.
|
|
|
|
EMAIL_SUBJECT_PREFIX
|
|
--------------------
|
|
|
|
Default: ``'[Django] '``
|
|
|
|
Subject-line prefix for e-mail messages sent with ``django.core.mail.mail_admins``
|
|
or ``django.core.mail.mail_managers``. You'll probably want to include the
|
|
trailing space.
|
|
|
|
EMAIL_USE_TLS
|
|
-------------
|
|
|
|
**New in Django development version**
|
|
|
|
Default: ``False``
|
|
|
|
Whether to use a TLS (secure) connection when talking to the SMTP server.
|
|
|
|
FILE_CHARSET
|
|
------------
|
|
|
|
**New in Django development version**
|
|
|
|
Default: ``'utf-8'``
|
|
|
|
The character encoding used to decode any files read from disk. This includes
|
|
template files and initial SQL data files.
|
|
|
|
FIXTURE_DIRS
|
|
-------------
|
|
|
|
Default: ``()`` (Empty tuple)
|
|
|
|
List of locations of the fixture data files, in search order. Note that
|
|
these paths should use Unix-style forward slashes, even on Windows. See
|
|
`Testing Django Applications`_.
|
|
|
|
.. _Testing Django Applications: ../testing/
|
|
|
|
IGNORABLE_404_ENDS
|
|
------------------
|
|
|
|
Default: ``('mail.pl', 'mailform.pl', 'mail.cgi', 'mailform.cgi', 'favicon.ico', '.php')``
|
|
|
|
See also ``IGNORABLE_404_STARTS`` and ``Error reporting via e-mail``.
|
|
|
|
IGNORABLE_404_STARTS
|
|
--------------------
|
|
|
|
Default: ``('/cgi-bin/', '/_vti_bin', '/_vti_inf')``
|
|
|
|
A tuple of strings that specify beginnings of URLs that should be ignored by
|
|
the 404 e-mailer. See ``SEND_BROKEN_LINK_EMAILS``, ``IGNORABLE_404_ENDS`` and
|
|
the section on `error reporting via e-mail`_.
|
|
|
|
INSTALLED_APPS
|
|
--------------
|
|
|
|
Default: ``()`` (Empty tuple)
|
|
|
|
A tuple of strings designating all applications that are enabled in this Django
|
|
installation. Each string should be a full Python path to a Python package that
|
|
contains a Django application, as created by `django-admin.py startapp`_.
|
|
|
|
.. _django-admin.py startapp: ../django-admin/#startapp-appname
|
|
|
|
INTERNAL_IPS
|
|
------------
|
|
|
|
Default: ``()`` (Empty tuple)
|
|
|
|
A tuple of IP addresses, as strings, that:
|
|
|
|
* See debug comments, when ``DEBUG`` is ``True``
|
|
* Receive X headers if the ``XViewMiddleware`` is installed (see the
|
|
`middleware docs`_)
|
|
|
|
JING_PATH
|
|
---------
|
|
|
|
Default: ``'/usr/bin/jing'``
|
|
|
|
Path to the "Jing" executable. Jing is a RELAX NG validator, and Django uses it
|
|
to validate each ``XMLField`` in your models.
|
|
See http://www.thaiopensource.com/relaxng/jing.html .
|
|
|
|
LANGUAGE_CODE
|
|
-------------
|
|
|
|
Default: ``'en-us'``
|
|
|
|
A string representing the language code for this installation. This should be
|
|
in standard language format. For example, U.S. English is ``"en-us"``. See the
|
|
`internationalization docs`_.
|
|
|
|
.. _internationalization docs: ../i18n/
|
|
|
|
LANGUAGES
|
|
---------
|
|
|
|
Default: A tuple of all available languages. This list is continually growing
|
|
and including a copy here would inevitably become rapidly out of date. You can
|
|
see the current list of translated languages by looking in
|
|
``django/conf/global_settings.py`` (or view the `online source`_).
|
|
|
|
.. _online source: http://code.djangoproject.com/browser/django/trunk/django/conf/global_settings.py
|
|
|
|
The list is a tuple of two-tuples in the format (language code, language
|
|
name) -- for example, ``('ja', 'Japanese')``. This specifies which languages
|
|
are available for language selection. See the `internationalization docs`_ for
|
|
details.
|
|
|
|
Generally, the default value should suffice. Only set this setting if you want
|
|
to restrict language selection to a subset of the Django-provided languages.
|
|
|
|
If you define a custom ``LANGUAGES`` setting, it's OK to mark the languages as
|
|
translation strings (as in the default value displayed above) -- but use a
|
|
"dummy" ``gettext()`` function, not the one in ``django.utils.translation``.
|
|
You should *never* import ``django.utils.translation`` from within your
|
|
settings file, because that module in itself depends on the settings, and that
|
|
would cause a circular import.
|
|
|
|
The solution is to use a "dummy" ``gettext()`` function. Here's a sample
|
|
settings file::
|
|
|
|
gettext = lambda s: s
|
|
|
|
LANGUAGES = (
|
|
('de', gettext('German')),
|
|
('en', gettext('English')),
|
|
)
|
|
|
|
With this arrangement, ``make-messages.py`` will still find and mark these
|
|
strings for translation, but the translation won't happen at runtime -- so
|
|
you'll have to remember to wrap the languages in the *real* ``gettext()`` in
|
|
any code that uses ``LANGUAGES`` at runtime.
|
|
|
|
LOGIN_REDIRECT_URL
|
|
------------------
|
|
|
|
**New in Django development version**
|
|
|
|
Default: ``'/accounts/profile/'``
|
|
|
|
The URL where requests are redirected after login when the
|
|
``contrib.auth.login`` view gets no ``next`` parameter.
|
|
|
|
This is used by the `@login_required`_ decorator, for example.
|
|
|
|
LOGIN_URL
|
|
---------
|
|
|
|
**New in Django development version**
|
|
|
|
Default: ``'/accounts/login/'``
|
|
|
|
The URL where requests are redirected for login, specially when using the
|
|
`@login_required`_ decorator.
|
|
|
|
LOGOUT_URL
|
|
----------
|
|
|
|
**New in Django development version**
|
|
|
|
Default: ``'/accounts/logout/'``
|
|
|
|
LOGIN_URL counterpart.
|
|
|
|
MANAGERS
|
|
--------
|
|
|
|
Default: ``()`` (Empty tuple)
|
|
|
|
A tuple in the same format as ``ADMINS`` that specifies who should get
|
|
broken-link notifications when ``SEND_BROKEN_LINK_EMAILS=True``.
|
|
|
|
MEDIA_ROOT
|
|
----------
|
|
|
|
Default: ``''`` (Empty string)
|
|
|
|
Absolute path to the directory that holds media for this installation.
|
|
Example: ``"/home/media/media.lawrence.com/"`` See also ``MEDIA_URL``.
|
|
|
|
MEDIA_URL
|
|
---------
|
|
|
|
Default: ``''`` (Empty string)
|
|
|
|
URL that handles the media served from ``MEDIA_ROOT``.
|
|
Example: ``"http://media.lawrence.com"``
|
|
|
|
Note that this should have a trailing slash if it has a path component.
|
|
|
|
Good: ``"http://www.example.com/static/"``
|
|
Bad: ``"http://www.example.com/static"``
|
|
|
|
MIDDLEWARE_CLASSES
|
|
------------------
|
|
|
|
Default::
|
|
|
|
("django.contrib.sessions.middleware.SessionMiddleware",
|
|
"django.contrib.auth.middleware.AuthenticationMiddleware",
|
|
"django.middleware.common.CommonMiddleware",
|
|
"django.middleware.doc.XViewMiddleware")
|
|
|
|
A tuple of middleware classes to use. See the `middleware docs`_.
|
|
|
|
MONTH_DAY_FORMAT
|
|
----------------
|
|
|
|
Default: ``'F j'``
|
|
|
|
The default formatting to use for date fields on Django admin change-list
|
|
pages -- and, possibly, by other parts of the system -- in cases when only the
|
|
month and day are displayed.
|
|
|
|
For example, when a Django admin change-list page is being filtered by a date
|
|
drilldown, the header for a given day displays the day and month. Different
|
|
locales have different formats. For example, U.S. English would say
|
|
"January 1," whereas Spanish might say "1 Enero."
|
|
|
|
See `allowed date format strings`_. See also DATE_FORMAT, DATETIME_FORMAT,
|
|
TIME_FORMAT and YEAR_MONTH_FORMAT.
|
|
|
|
PREPEND_WWW
|
|
-----------
|
|
|
|
Default: ``False``
|
|
|
|
Whether to prepend the "www." subdomain to URLs that don't have it. This is
|
|
only used if ``CommonMiddleware`` is installed (see the `middleware docs`_).
|
|
See also ``APPEND_SLASH``.
|
|
|
|
PROFANITIES_LIST
|
|
----------------
|
|
|
|
A tuple of profanities, as strings, that will trigger a validation error when
|
|
the ``hasNoProfanities`` validator is called.
|
|
|
|
We don't list the default values here, because that would be profane. To see
|
|
the default values, see the file ``django/conf/global_settings.py``.
|
|
|
|
ROOT_URLCONF
|
|
------------
|
|
|
|
Default: Not defined
|
|
|
|
A string representing the full Python import path to your root URLconf. For example:
|
|
``"mydjangoapps.urls"``. See `How Django processes a request`_.
|
|
|
|
.. _How Django processes a request: ../url_dispatch/#how-django-processes-a-request
|
|
|
|
SECRET_KEY
|
|
----------
|
|
|
|
Default: ``''`` (Empty string)
|
|
|
|
A secret key for this particular Django installation. Used to provide a seed in
|
|
secret-key hashing algorithms. Set this to a random string -- the longer, the
|
|
better. ``django-admin.py startproject`` creates one automatically.
|
|
|
|
SEND_BROKEN_LINK_EMAILS
|
|
-----------------------
|
|
|
|
Default: ``False``
|
|
|
|
Whether to send an e-mail to the ``MANAGERS`` each time somebody visits a
|
|
Django-powered page that is 404ed with a non-empty referer (i.e., a broken
|
|
link). This is only used if ``CommonMiddleware`` is installed (see the
|
|
`middleware docs`_). See also ``IGNORABLE_404_STARTS``,
|
|
``IGNORABLE_404_ENDS`` and the section on `error reporting via e-mail`_
|
|
|
|
SERIALIZATION_MODULES
|
|
---------------------
|
|
|
|
Default: Not defined.
|
|
|
|
A dictionary of modules containing serializer definitions (provided as
|
|
strings), keyed by a string identifier for that serialization type. For
|
|
example, to define a YAML serializer, use::
|
|
|
|
SERIALIZATION_MODULES = { 'yaml' : 'path.to.yaml_serializer' }
|
|
|
|
SERVER_EMAIL
|
|
------------
|
|
|
|
Default: ``'root@localhost'``
|
|
|
|
The e-mail address that error messages come from, such as those sent to
|
|
``ADMINS`` and ``MANAGERS``.
|
|
|
|
SESSION_COOKIE_AGE
|
|
------------------
|
|
|
|
Default: ``1209600`` (2 weeks, in seconds)
|
|
|
|
The age of session cookies, in seconds. See the `session docs`_.
|
|
|
|
SESSION_COOKIE_DOMAIN
|
|
---------------------
|
|
|
|
Default: ``None``
|
|
|
|
The domain to use for session cookies. Set this to a string such as
|
|
``".lawrence.com"`` for cross-domain cookies, or use ``None`` for a standard
|
|
domain cookie. See the `session docs`_.
|
|
|
|
SESSION_COOKIE_NAME
|
|
-------------------
|
|
|
|
Default: ``'sessionid'``
|
|
|
|
The name of the cookie to use for sessions. This can be whatever you want.
|
|
See the `session docs`_.
|
|
|
|
SESSION_COOKIE_SECURE
|
|
---------------------
|
|
|
|
Default: ``False``
|
|
|
|
Whether to use a secure cookie for the session cookie. If this is set to
|
|
``True``, the cookie will be marked as "secure," which means browsers may
|
|
ensure that the cookie is only sent under an HTTPS connection.
|
|
See the `session docs`_.
|
|
|
|
SESSION_EXPIRE_AT_BROWSER_CLOSE
|
|
-------------------------------
|
|
|
|
Default: ``False``
|
|
|
|
Whether to expire the session when the user closes his or her browser.
|
|
See the `session docs`_.
|
|
|
|
SESSION_SAVE_EVERY_REQUEST
|
|
--------------------------
|
|
|
|
Default: ``False``
|
|
|
|
Whether to save the session data on every request. See the `session docs`_.
|
|
|
|
SITE_ID
|
|
-------
|
|
|
|
Default: Not defined
|
|
|
|
The ID, as an integer, of the current site in the ``django_site`` database
|
|
table. This is used so that application data can hook into specific site(s)
|
|
and a single database can manage content for multiple sites.
|
|
|
|
See the `site framework docs`_.
|
|
|
|
.. _site framework docs: ../sites/
|
|
|
|
TEMPLATE_CONTEXT_PROCESSORS
|
|
---------------------------
|
|
|
|
Default::
|
|
|
|
("django.core.context_processors.auth",
|
|
"django.core.context_processors.debug",
|
|
"django.core.context_processors.i18n",
|
|
"django.core.context_processors.media")
|
|
|
|
A tuple of callables that are used to populate the context in ``RequestContext``.
|
|
These callables take a request object as their argument and return a dictionary
|
|
of items to be merged into the context.
|
|
|
|
TEMPLATE_DEBUG
|
|
--------------
|
|
|
|
Default: ``False``
|
|
|
|
A boolean that turns on/off template debug mode. If this is ``True``, the fancy
|
|
error page will display a detailed report for any ``TemplateSyntaxError``. This
|
|
report contains the relevant snippet of the template, with the appropriate line
|
|
highlighted.
|
|
|
|
Note that Django only displays fancy error pages if ``DEBUG`` is ``True``, so
|
|
you'll want to set that to take advantage of this setting.
|
|
|
|
See also DEBUG.
|
|
|
|
TEMPLATE_DIRS
|
|
-------------
|
|
|
|
Default: ``()`` (Empty tuple)
|
|
|
|
List of locations of the template source files, in search order. Note that
|
|
these paths should use Unix-style forward slashes, even on Windows.
|
|
|
|
See the `template documentation`_.
|
|
|
|
TEMPLATE_LOADERS
|
|
----------------
|
|
|
|
Default: ``('django.template.loaders.filesystem.load_template_source',)``
|
|
|
|
A tuple of callables (as strings) that know how to import templates from
|
|
various sources. See the `template documentation`_.
|
|
|
|
TEMPLATE_STRING_IF_INVALID
|
|
--------------------------
|
|
|
|
Default: ``''`` (Empty string)
|
|
|
|
Output, as a string, that the template system should use for invalid (e.g.
|
|
misspelled) variables. See `How invalid variables are handled`_.
|
|
|
|
.. _How invalid variables are handled: ../templates_python/#how-invalid-variables-are-handled
|
|
|
|
TEST_DATABASE_CHARSET
|
|
---------------------
|
|
|
|
**New in Django development version**
|
|
|
|
Default: ``None``
|
|
|
|
The character set encoding used to create the test database. The value of this
|
|
string is passed directly through to the database, so its format is
|
|
backend-specific.
|
|
|
|
Supported for the PostgreSQL_ (``postgresql``, ``postgresql_psycopg2``) and MySQL_ (``mysql``, ``mysql_old``) backends.
|
|
|
|
.. _PostgreSQL: http://www.postgresql.org/docs/8.2/static/multibyte.html
|
|
.. _MySQL: http://www.mysql.org/doc/refman/5.0/en/charset-database.html
|
|
|
|
TEST_DATABASE_COLLATION
|
|
------------------------
|
|
|
|
**New in Django development version**
|
|
|
|
Default: ``None``
|
|
|
|
The collation order to use when creating the test database. This value is
|
|
passed directly to the backend, so its format is backend-specific.
|
|
|
|
Only supported for ``mysql`` and ``mysql_old`` backends (see `section 10.3.2`_
|
|
of the MySQL manual for details).
|
|
|
|
.. _section 10.3.2: http://www.mysql.org/doc/refman/5.0/en/charset-database.html
|
|
|
|
TEST_DATABASE_NAME
|
|
------------------
|
|
|
|
Default: ``None``
|
|
|
|
The name of database to use when running the test suite. If a value of
|
|
``None`` is specified, the test database will use the name ``'test_' + settings.DATABASE_NAME``. See `Testing Django Applications`_.
|
|
|
|
.. _Testing Django Applications: ../testing/
|
|
|
|
TEST_RUNNER
|
|
-----------
|
|
|
|
Default: ``'django.test.simple.run_tests'``
|
|
|
|
The name of the method to use for starting the test suite. See
|
|
`Testing Django Applications`_.
|
|
|
|
.. _Testing Django Applications: ../testing/
|
|
|
|
TIME_FORMAT
|
|
-----------
|
|
|
|
Default: ``'P'`` (e.g. ``4 p.m.``)
|
|
|
|
The default formatting to use for time fields on Django admin change-list
|
|
pages -- and, possibly, by other parts of the system. See
|
|
`allowed date format strings`_.
|
|
|
|
See also DATE_FORMAT, DATETIME_FORMAT, TIME_FORMAT, YEAR_MONTH_FORMAT and
|
|
MONTH_DAY_FORMAT.
|
|
|
|
.. _allowed date format strings: ../templates/#now
|
|
|
|
TIME_ZONE
|
|
---------
|
|
|
|
Default: ``'America/Chicago'``
|
|
|
|
A string representing the time zone for this installation. `See available choices`_.
|
|
(Note that list of available choices lists more than one on the same line;
|
|
you'll want to use just one of the choices for a given time zone. For instance,
|
|
one line says ``'Europe/London GB GB-Eire'``, but you should use the first bit
|
|
of that -- ``'Europe/London'`` -- as your ``TIME_ZONE`` setting.)
|
|
|
|
Note that this is the time zone to which Django will convert all dates/times --
|
|
not necessarily the timezone of the server. For example, one server may serve
|
|
multiple Django-powered sites, each with a separate time-zone setting.
|
|
|
|
Normally, Django sets the ``os.environ['TZ']`` variable to the time zone you
|
|
specify in the ``TIME_ZONE`` setting. Thus, all your views and models will
|
|
automatically operate in the correct time zone. However, if you're using the
|
|
manual configuration option (see below), Django will *not* touch the ``TZ``
|
|
environment variable, and it'll be up to you to ensure your processes are
|
|
running in the correct environment.
|
|
|
|
.. note::
|
|
Django cannot reliably use alternate time zones in a Windows environment.
|
|
If you're running Django on Windows, this variable must be set to match the
|
|
system timezone.
|
|
|
|
URL_VALIDATOR_USER_AGENT
|
|
------------------------
|
|
|
|
Default: ``Django/<version> (http://www.djangoproject.com/)``
|
|
|
|
The string to use as the ``User-Agent`` header when checking to see if URLs
|
|
exist (see the ``verify_exists`` option on URLField_).
|
|
|
|
.. _URLField: ../model-api/#urlfield
|
|
|
|
USE_ETAGS
|
|
---------
|
|
|
|
Default: ``False``
|
|
|
|
A boolean that specifies whether to output the "Etag" header. This saves
|
|
bandwidth but slows down performance. This is only used if ``CommonMiddleware``
|
|
is installed (see the `middleware docs`_).
|
|
|
|
USE_I18N
|
|
--------
|
|
|
|
Default: ``True``
|
|
|
|
A boolean that specifies whether Django's internationalization system should be
|
|
enabled. This provides an easy way to turn it off, for performance. If this is
|
|
set to ``False``, Django will make some optimizations so as not to load the
|
|
internationalization machinery.
|
|
|
|
YEAR_MONTH_FORMAT
|
|
-----------------
|
|
|
|
Default: ``'F Y'``
|
|
|
|
The default formatting to use for date fields on Django admin change-list
|
|
pages -- and, possibly, by other parts of the system -- in cases when only the
|
|
year and month are displayed.
|
|
|
|
For example, when a Django admin change-list page is being filtered by a date
|
|
drilldown, the header for a given month displays the month and the year.
|
|
Different locales have different formats. For example, U.S. English would say
|
|
"January 2006," whereas another locale might say "2006/January."
|
|
|
|
See `allowed date format strings`_. See also DATE_FORMAT, DATETIME_FORMAT,
|
|
TIME_FORMAT and MONTH_DAY_FORMAT.
|
|
|
|
.. _cache docs: ../cache/
|
|
.. _middleware docs: ../middleware/
|
|
.. _session docs: ../sessions/
|
|
.. _See available choices: http://www.postgresql.org/docs/8.1/static/datetime-keywords.html#DATETIME-TIMEZONE-SET-TABLE
|
|
.. _template documentation: ../templates_python/
|
|
|
|
Creating your own settings
|
|
==========================
|
|
|
|
There's nothing stopping you from creating your own settings, for your own
|
|
Django apps. Just follow these conventions:
|
|
|
|
* Setting names are in all uppercase.
|
|
* For settings that are sequences, use tuples instead of lists. This is
|
|
purely for performance.
|
|
* Don't reinvent an already-existing setting.
|
|
|
|
Using settings without setting DJANGO_SETTINGS_MODULE
|
|
=====================================================
|
|
|
|
In some cases, you might want to bypass the ``DJANGO_SETTINGS_MODULE``
|
|
environment variable. For example, if you're using the template system by
|
|
itself, you likely don't want to have to set up an environment variable
|
|
pointing to a settings module.
|
|
|
|
In these cases, you can configure Django's settings manually. Do this by
|
|
calling ``django.conf.settings.configure()``.
|
|
|
|
Example::
|
|
|
|
from django.conf import settings
|
|
|
|
settings.configure(DEBUG=True, TEMPLATE_DEBUG=True,
|
|
TEMPLATE_DIRS=('/home/web-apps/myapp', '/home/web-apps/base'))
|
|
|
|
Pass ``configure()`` as many keyword arguments as you'd like, with each keyword
|
|
argument representing a setting and its value. Each argument name should be all
|
|
uppercase, with the same name as the settings described above. If a particular
|
|
setting is not passed to ``configure()`` and is needed at some later point,
|
|
Django will use the default setting value.
|
|
|
|
Configuring Django in this fashion is mostly necessary -- and, indeed,
|
|
recommended -- when you're using a piece of the framework inside a larger
|
|
application.
|
|
|
|
Consequently, when configured via ``settings.configure()``, Django will not
|
|
make any modifications to the process environment variables. (See the
|
|
explanation of ``TIME_ZONE``, above, for why this would normally occur.) It's
|
|
assumed that you're already in full control of your environment in these cases.
|
|
|
|
Custom default settings
|
|
-----------------------
|
|
|
|
If you'd like default values to come from somewhere other than
|
|
``django.conf.global_settings``, you can pass in a module or class that
|
|
provides the default settings as the ``default_settings`` argument (or as the
|
|
first positional argument) in the call to ``configure()``.
|
|
|
|
In this example, default settings are taken from ``myapp_defaults``, and the
|
|
``DEBUG`` setting is set to ``True``, regardless of its value in
|
|
``myapp_defaults``::
|
|
|
|
from django.conf import settings
|
|
from myapp import myapp_defaults
|
|
|
|
settings.configure(default_settings=myapp_defaults, DEBUG=True)
|
|
|
|
The following example, which uses ``myapp_defaults`` as a positional argument,
|
|
is equivalent::
|
|
|
|
settings.configure(myapp_defaults, DEBUG = True)
|
|
|
|
Normally, you will not need to override the defaults in this fashion. The
|
|
Django defaults are sufficiently tame that you can safely use them. Be aware
|
|
that if you do pass in a new default module, it entirely *replaces* the Django
|
|
defaults, so you must specify a value for every possible setting that might be
|
|
used in that code you are importing. Check in
|
|
``django.conf.settings.global_settings`` for the full list.
|
|
|
|
Either configure() or DJANGO_SETTINGS_MODULE is required
|
|
--------------------------------------------------------
|
|
|
|
If you're not setting the ``DJANGO_SETTINGS_MODULE`` environment variable, you
|
|
*must* call ``configure()`` at some point before using any code that reads
|
|
settings.
|
|
|
|
If you don't set ``DJANGO_SETTINGS_MODULE`` and don't call ``configure()``,
|
|
Django will raise an ``EnvironmentError`` exception the first time a setting
|
|
is accessed.
|
|
|
|
If you set ``DJANGO_SETTINGS_MODULE``, access settings values somehow, *then*
|
|
call ``configure()``, Django will raise an ``EnvironmentError`` saying settings
|
|
have already been configured.
|
|
|
|
Also, it's an error to call ``configure()`` more than once, or to call
|
|
``configure()`` after any setting has been accessed.
|
|
|
|
It boils down to this: Use exactly one of either ``configure()`` or
|
|
``DJANGO_SETTINGS_MODULE``. Not both, and not neither.
|
|
|
|
.. _@login_required: ../authentication/#the-login-required-decorator
|
|
|
|
Error reporting via e-mail
|
|
==========================
|
|
|
|
Server errors
|
|
-------------
|
|
|
|
When ``DEBUG`` is ``False``, Django will e-mail the users listed in the
|
|
``ADMIN`` setting whenever your code raises an unhandled exception and results
|
|
in an internal server error (HTTP status code 500). This gives the
|
|
administrators immediate notification of any errors.
|
|
|
|
To disable this behavior, just remove all entries from the ``ADMINS`` setting.
|
|
|
|
404 errors
|
|
----------
|
|
|
|
When ``DEBUG`` is ``False`` and your ``MIDDLEWARE_CLASSES`` setting includes
|
|
``CommonMiddleware``, Django will e-mail the users listed in the ``MANAGERS``
|
|
setting whenever your code raises a 404 and the request has a referer.
|
|
(It doesn't bother to e-mail for 404s that don't have a referer.)
|
|
|
|
You can tell Django to stop reporting particular 404s by tweaking the
|
|
``IGNORABLE_404_ENDS`` and ``IGNORABLE_404_STARTS`` settings. Both should be a
|
|
tuple of strings. For example::
|
|
|
|
IGNORABLE_404_ENDS = ('.php', '.cgi')
|
|
IGNORABLE_404_STARTS = ('/phpmyadmin/',)
|
|
|
|
In this example, a 404 to any URL ending with ``.php`` or ``.cgi`` will *not*
|
|
be reported. Neither will any URL starting with ``/phpmyadmin/``.
|
|
|
|
To disable this behavior, just remove all entries from the ``MANAGERS`` setting.
|