diff options
Diffstat (limited to 'docs/settings.txt')
| -rw-r--r-- | docs/settings.txt | 201 |
1 files changed, 169 insertions, 32 deletions
diff --git a/docs/settings.txt b/docs/settings.txt index 67e0498e1a..b41281ee49 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,10 @@ 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'``, ``'sqlite3'`` or ``'ado_mssql'``. DATABASE_HOST ------------- @@ -265,6 +271,14 @@ 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 ----------------- @@ -298,7 +312,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 --------------- @@ -311,7 +325,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 ----- @@ -320,6 +334,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 --------------- @@ -401,21 +425,25 @@ 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. -ENABLE_PSYCO ------------- +FIXTURE_DIRS +------------- -Default: ``False`` +**New in Django development version** + +Default: ``()`` (Empty tuple) -Whether to enable Psyco, which optimizes Python code. Requires Psyco_. +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`_. -.. _Psyco: http://psyco.sourceforge.net/ +.. _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 -------------------- @@ -423,7 +451,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 -------------- @@ -434,7 +463,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 ------------ @@ -465,7 +494,7 @@ 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 --------- @@ -473,25 +502,36 @@ LANGUAGES Default: A tuple of all available languages. Currently, this is:: 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')), ) A tuple of two-tuples in the format (language code, language name). This @@ -526,7 +566,7 @@ any code that uses ``LANGUAGES`` at runtime. MANAGERS -------- -Default: ``ADMINS`` (Whatever ``ADMINS`` is set to) +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``. @@ -547,6 +587,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 ------------------ @@ -585,6 +630,15 @@ 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 ------------ @@ -593,7 +647,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 ---------- @@ -612,8 +666,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 ------------ @@ -685,7 +750,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 --------------------------- @@ -741,7 +806,31 @@ 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 +----------- + +**New in Django development version** + +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/ + +TEST_DATABASE_NAME +------------------ + +**New in Django development version** + +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/ TIME_FORMAT ----------- @@ -755,7 +844,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 --------- @@ -779,6 +868,21 @@ 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 --------- @@ -815,11 +919,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/ -.. _See available choices: http://www.postgresql.org/docs/current/static/datetime-keywords.html#DATETIME-TIMEZONE-SET-TABLE -.. _template documentation: http://www.djangoproject.com/documentation/templates_python/ +.. _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 ========================== @@ -914,3 +1018,36 @@ 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. + +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. |