diff options
Diffstat (limited to 'docs/settings.txt')
| -rw-r--r-- | docs/settings.txt | 283 |
1 files changed, 207 insertions, 76 deletions
diff --git a/docs/settings.txt b/docs/settings.txt index ba1e8eafea..12e6dab4bc 100644 --- a/docs/settings.txt +++ b/docs/settings.txt @@ -59,7 +59,7 @@ Use the ``--settings`` command-line argument to specify the settings manually:: django-admin.py runserver --settings=mysite.settings -.. _django-admin.py: http://www.djangoproject.com/documentation/django_admin/ +.. _django-admin.py: ../django-admin/ On the server (mod_python) -------------------------- @@ -75,7 +75,7 @@ settings file to use. Do that with ``SetEnv``:: Read the `Django mod_python documentation`_ for more information. -.. _Django mod_python documentation: http://www.djangoproject.com/documentation/modpython/ +.. _Django mod_python documentation: ../modpython/ Default settings ================ @@ -102,7 +102,7 @@ between the current settings file and Django's default settings. For more, see the `diffsettings documentation`_. -.. _diffsettings documentation: http://www.djangoproject.com/documentation/django_admin/#diffsettings +.. _diffsettings documentation: ../django-admin/#diffsettings Using settings in Python code ============================= @@ -157,15 +157,18 @@ ABSOLUTE_URL_OVERRIDES Default: ``{}`` (Empty dictionary) -A dictionary mapping ``"app_label.module_name"`` strings to functions that take +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.blogs': lambda o: "/blogs/%s/" % o.slug, - 'news.stories': lambda o: "/stories/%s/%s/" % (o.pub_year, o.slug), + '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 --------- @@ -197,6 +200,9 @@ 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 --------------------- @@ -236,10 +242,11 @@ The cache key prefix that the cache middleware should use. See the DATABASE_ENGINE --------------- -Default: ``'postgresql'`` +Default: ``''`` (Empty string) -Which database backend to use. Either ``'postgresql'``, ``'mysql'``, -``'sqlite3'`` or ``'ado_mssql'``. +Which database backend to use. Either ``'postgresql_psycopg2'``, +``'postgresql'``, ``'mysql'``, ``'mysql_old'``, ``'sqlite3'`` or +``'ado_mssql'``. DATABASE_HOST ------------- @@ -257,6 +264,11 @@ MySQL will connect via a Unix socket to the specified socket. For example:: 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 ------------- @@ -306,7 +318,7 @@ pages -- and, possibly, by other parts of the system. See See also DATETIME_FORMAT, TIME_FORMAT, YEAR_MONTH_FORMAT and MONTH_DAY_FORMAT. -.. _allowed date format strings: http://www.djangoproject.com/documentation/templates/#now +.. _allowed date format strings: ../templates/#now DATETIME_FORMAT --------------- @@ -319,7 +331,7 @@ pages -- and, possibly, by other parts of the system. See See also DATE_FORMAT, DATETIME_FORMAT, TIME_FORMAT, YEAR_MONTH_FORMAT and MONTH_DAY_FORMAT. -.. _allowed date format strings: http://www.djangoproject.com/documentation/templates/#now +.. _allowed date format strings: ../templates/#now DEBUG ----- @@ -328,6 +340,16 @@ 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 --------------- @@ -378,8 +400,10 @@ EMAIL_HOST_PASSWORD Default: ``''`` (Empty string) -Username to use for the SMTP server defined in ``EMAIL_HOST``. If empty, -Django won't attempt authentication. +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``. @@ -409,12 +433,32 @@ 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. + +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``. +See also ``IGNORABLE_404_STARTS`` and ``Error reporting via e-mail``. IGNORABLE_404_STARTS -------------------- @@ -422,7 +466,8 @@ 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`` and ``IGNORABLE_404_ENDS``. +the 404 e-mailer. See ``SEND_BROKEN_LINK_EMAILS``, ``IGNORABLE_404_ENDS`` and +the section on `error reporting via e-mail`_. INSTALLED_APPS -------------- @@ -433,7 +478,7 @@ 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: http://www.djangoproject.com/documentation/django_admin/#startapp-appname +.. _django-admin.py startapp: ../django-admin/#startapp-appname INTERNAL_IPS ------------ @@ -464,49 +509,22 @@ 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: http://www.djangoproject.com/documentation/i18n/ +.. _internationalization docs: ../i18n/ LANGUAGES --------- -Default: A tuple of all available languages. Currently, this is:: +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`_). - LANGUAGES = ( - ('ar', _('Arabic')), - ('bn', _('Bengali')), - ('cs', _('Czech')), - ('cy', _('Welsh')), - ('da', _('Danish')), - ('de', _('German')), - ('el', _('Greek')), - ('en', _('English')), - ('es', _('Spanish')), - ('es_AR', _('Argentinean Spanish')), - ('fr', _('French')), - ('gl', _('Galician')), - ('hu', _('Hungarian')), - ('he', _('Hebrew')), - ('is', _('Icelandic')), - ('it', _('Italian')), - ('ja', _('Japanese')), - ('nl', _('Dutch')), - ('no', _('Norwegian')), - ('pt-br', _('Brazilian')), - ('ro', _('Romanian')), - ('ru', _('Russian')), - ('sk', _('Slovak')), - ('sl', _('Slovenian')), - ('sr', _('Serbian')), - ('sv', _('Swedish')), - ('ta', _('Tamil')), - ('uk', _('Ukrainian')), - ('zh-cn', _('Simplified Chinese')), - ('zh-tw', _('Traditional Chinese')), - ) +.. _online source: http://code.djangoproject.com/browser/django/trunk/django/conf/global_settings.py -A tuple of two-tuples in the format (language code, language name). This -specifies which languages are available for language selection. See the -`internationalization docs`_ for details. +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. @@ -533,6 +551,37 @@ 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 -------- @@ -557,6 +606,11 @@ 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 ------------------ @@ -612,7 +666,7 @@ 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: http://www.djangoproject.com/documentation/url_dispatch/#how-django-processes-a-request +.. _How Django processes a request: ../url_dispatch/#how-django-processes-a-request SECRET_KEY ---------- @@ -631,8 +685,19 @@ 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`` and -``IGNORABLE_404_ENDS``. +`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 ------------ @@ -669,8 +734,6 @@ See the `session docs`_. SESSION_COOKIE_SECURE --------------------- -**New in Django development version** - Default: ``False`` Whether to use a secure cookie for the session cookie. If this is set to @@ -704,7 +767,7 @@ and a single database can manage content for multiple sites. See the `site framework docs`_. -.. _site framework docs: http://www.djangoproject.com/documentation/sites/ +.. _site framework docs: ../sites/ TEMPLATE_CONTEXT_PROCESSORS --------------------------- @@ -713,7 +776,8 @@ Default:: ("django.core.context_processors.auth", "django.core.context_processors.debug", - "django.core.context_processors.i18n") + "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 @@ -760,32 +824,59 @@ 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: http://www.djangoproject.com/documentation/templates_python/#how-invalid-variables-are-handled +.. _How invalid variables are handled: ../templates_python/#how-invalid-variables-are-handled -TEST_RUNNER ------------ +TEST_DATABASE_CHARSET +--------------------- **New in Django development version** -Default: ``'django.test.simple.run_tests'`` +Default: ``None`` -The name of the method to use for starting the test suite. See -`Testing Django Applications`_. +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. -.. _Testing Django Applications: ../testing/ +Supported for the PostgreSQL_ (``postgresql``, ``postgresql_psycopg2``) and MySQL_ (``mysql``, ``mysql_old``) backends. -TEST_DATABASE_NAME ------------------- +.. _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 name of database to use when running the test suite. If a value of +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 ----------- @@ -798,7 +889,7 @@ pages -- and, possibly, by other parts of the system. See See also DATE_FORMAT, DATETIME_FORMAT, TIME_FORMAT, YEAR_MONTH_FORMAT and MONTH_DAY_FORMAT. -.. _allowed date format strings: http://www.djangoproject.com/documentation/templates/#now +.. _allowed date format strings: ../templates/#now TIME_ZONE --------- @@ -822,6 +913,11 @@ 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 ------------------------ @@ -830,7 +926,7 @@ 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 +.. _URLField: ../model-api/#urlfield USE_ETAGS --------- @@ -868,11 +964,11 @@ Different locales have different formats. For example, U.S. English would say See `allowed date format strings`_. See also DATE_FORMAT, DATETIME_FORMAT, TIME_FORMAT and MONTH_DAY_FORMAT. -.. _cache docs: http://www.djangoproject.com/documentation/cache/ -.. _middleware docs: http://www.djangoproject.com/documentation/middleware/ -.. _session docs: http://www.djangoproject.com/documentation/sessions/ +.. _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: http://www.djangoproject.com/documentation/templates_python/ +.. _template documentation: ../templates_python/ Creating your own settings ========================== @@ -967,3 +1063,38 @@ Also, it's an error to call ``configure()`` more than once, or to call 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. |