p31829507
/
django
mirror of https://github.com/django/django.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Cosmetic edits and minor corrections to docs/ref/settings.txt.

This commit is contained in:
garwoodpr 2015-05-06 22:23:07 -05:00 committed by Tim Graham
parent 655f524915
commit 5edf25bddd
1 changed files with 52 additions and 33 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

85
docs/ref/settings.txt
View File

@ -13,7 +13,7 @@ Settings
and :setting:`STATICFILES_FINDERS`. Make sure you keep the components and :setting:`STATICFILES_FINDERS`. Make sure you keep the components
required by the features of Django you wish to use. required by the features of Django you wish to use.
Core settings Core Settings
============= =============
Here's a list of settings available in Django core and their default values. Here's a list of settings available in Django core and their default values.
@ -66,8 +66,8 @@ Default: ``[]`` (Empty list)
A list of strings representing the host/domain names that this Django site can A list of strings representing the host/domain names that this Django site can
serve. This is a security measure to prevent an attacker from poisoning caches serve. This is a security measure to prevent an attacker from poisoning caches
and password reset emails with links to malicious hosts by submitting requests and triggering password reset emails with links to malicious hosts by submitting
with a fake HTTP ``Host`` header, which is possible even under many requests with a fake HTTP ``Host`` header, which is possible even under many
seemingly-safe web server configurations. seemingly-safe web server configurations.
Values in this list can be fully qualified names (e.g. ``'www.example.com'``), Values in this list can be fully qualified names (e.g. ``'www.example.com'``),
@ -309,7 +309,7 @@ See :doc:`/topics/cache`.
CSRF_COOKIE_AGE CSRF_COOKIE_AGE
--------------- ---------------
Default: ``31449600`` (1 year, in seconds) Default: ``31449600`` (approximately 1 year, in seconds)
The age of CSRF cookies, in seconds. The age of CSRF cookies, in seconds.
@ -320,7 +320,7 @@ would fail in this case.
Some browsers (specifically Internet Explorer) can disallow the use of Some browsers (specifically Internet Explorer) can disallow the use of
persistent cookies or can have the indexes to the cookie jar corrupted on disk, persistent cookies or can have the indexes to the cookie jar corrupted on disk,
thereby causing CSRF protection checks to fail (and sometimes intermittently). thereby causing CSRF protection checks to (sometimes intermittently) fail.
Change this setting to ``None`` to use session-based CSRF cookies, which Change this setting to ``None`` to use session-based CSRF cookies, which
keep the cookies in-memory instead of on persistent storage. keep the cookies in-memory instead of on persistent storage.
@ -365,8 +365,8 @@ CSRF_COOKIE_NAME
Default: ``'csrftoken'`` Default: ``'csrftoken'``
The name of the cookie to use for the CSRF authentication token. This can be whatever you The name of the cookie to use for the CSRF authentication token. This can be
want. See :doc:`/ref/csrf`. whatever you want. See :doc:`/ref/csrf`.
.. setting:: CSRF_COOKIE_PATH .. setting:: CSRF_COOKIE_PATH
@ -391,7 +391,7 @@ Default: ``False``
Whether to use a secure cookie for the CSRF cookie. If this is set to ``True``, Whether to use a secure cookie for the CSRF cookie. If this is set to ``True``,
the cookie will be marked as "secure," which means browsers may ensure that the the cookie will be marked as "secure," which means browsers may ensure that the
cookie is only sent under an HTTPS connection. cookie is only sent with an HTTPS connection.
.. setting:: CSRF_FAILURE_VIEW .. setting:: CSRF_FAILURE_VIEW
@ -403,7 +403,8 @@ Default: ``'django.views.csrf.csrf_failure'``
A dotted path to the view function to be used when an incoming request A dotted path to the view function to be used when an incoming request
is rejected by the CSRF protection. The function should have this signature:: is rejected by the CSRF protection. The function should have this signature::
def csrf_failure(request, reason="") def csrf_failure(request, reason=""):
...
where ``reason`` is a short message (intended for developers or logging, not for where ``reason`` is a short message (intended for developers or logging, not for
end users) indicating the reason the request was rejected. See end users) indicating the reason the request was rejected. See
@ -434,7 +435,7 @@ DATABASES
Default: ``{}`` (Empty dictionary) Default: ``{}`` (Empty dictionary)
A dictionary containing the settings for all databases to be used with A dictionary containing the settings for all databases to be used with
Django. It is a nested dictionary whose contents maps database aliases Django. It is a nested dictionary whose contents map a database alias
to a dictionary containing the options for an individual database. to a dictionary containing the options for an individual database.
The :setting:`DATABASES` setting must configure a ``default`` database; The :setting:`DATABASES` setting must configure a ``default`` database;
@ -739,7 +740,7 @@ Default: ``True``
This is an Oracle-specific setting. This is an Oracle-specific setting.
If it is set to ``False``, the test tablespaces won't be automatically created If it is set to ``False``, the test tablespaces won't be automatically created
at the beginning of the tests and dropped at the end. at the beginning of the tests or dropped at the end.
.. setting:: TEST_USER_CREATE .. setting:: TEST_USER_CREATE
@ -879,7 +880,7 @@ DATABASE_ROUTERS
Default: ``[]`` (Empty list) Default: ``[]`` (Empty list)
The list of routers that will be used to determine which database The list of routers that will be used to determine which database
to use when performing a database queries. to use when performing a database query.
See the documentation on :ref:`automatic database routing in multi See the documentation on :ref:`automatic database routing in multi
database configurations <topics-db-multi-db-routing>`. database configurations <topics-db-multi-db-routing>`.
@ -1019,6 +1020,11 @@ Finally, if :setting:`DEBUG` is ``False``, you also need to properly set
the :setting:`ALLOWED_HOSTS` setting. Failing to do so will result in all the :setting:`ALLOWED_HOSTS` setting. Failing to do so will result in all
requests being returned as "Bad Request (400)". requests being returned as "Bad Request (400)".
.. note::
The default :file:`settings.py` file created by :djadmin:`django-admin
startproject <startproject>` sets ``DEBUG = True`` for convenience.
.. _django/views/debug.py: https://github.com/django/django/blob/master/django/views/debug.py .. _django/views/debug.py: https://github.com/django/django/blob/master/django/views/debug.py
.. setting:: DEBUG_PROPAGATE_EXCEPTIONS .. setting:: DEBUG_PROPAGATE_EXCEPTIONS
@ -1373,7 +1379,7 @@ FILE_UPLOAD_TEMP_DIR
Default: ``None`` Default: ``None``
The directory to store data (typically files larger than The directory to store data to (typically files larger than
:setting:`FILE_UPLOAD_MAX_MEMORY_SIZE`) temporarily while uploading files. :setting:`FILE_UPLOAD_MAX_MEMORY_SIZE`) temporarily while uploading files.
If ``None``, Django will use the standard temporary directory for the operating If ``None``, Django will use the standard temporary directory for the operating
system. For example, this will default to ``/tmp`` on \*nix-style operating system. For example, this will default to ``/tmp`` on \*nix-style operating
@ -1388,7 +1394,7 @@ FIRST_DAY_OF_WEEK
Default: ``0`` (Sunday) Default: ``0`` (Sunday)
Number representing the first day of the week. This is especially useful A number representing the first day of the week. This is especially useful
when displaying a calendar. This value is only used when not using when displaying a calendar. This value is only used when not using
format internationalization, or when a format cannot be found for the format internationalization, or when a format cannot be found for the
current locale. current locale.
@ -1432,7 +1438,7 @@ Default: ``None``
A full Python path to a Python package that contains format definitions for A full Python path to a Python package that contains format definitions for
project locales. If not ``None``, Django will check for a ``formats.py`` project locales. If not ``None``, Django will check for a ``formats.py``
file, under the directory named as the current locale, and will use the file, under the directory named as the current locale, and will use the
formats defined on this file. formats defined in this file.
For example, if :setting:`FORMAT_MODULE_PATH` is set to ``mysite.formats``, For example, if :setting:`FORMAT_MODULE_PATH` is set to ``mysite.formats``,
and current language is ``en`` (English), Django will expect a directory tree and current language is ``en`` (English), Django will expect a directory tree
@ -1496,7 +1502,7 @@ A list of strings designating all applications that are enabled in this
Django installation. Each string should be a dotted Python path to: Django installation. Each string should be a dotted Python path to:
* an application configuration class, or * an application configuration class, or
* a package containing a application. * a package containing an application.
:doc:`Learn more about application configurations </ref/applications>`. :doc:`Learn more about application configurations </ref/applications>`.
@ -1520,7 +1526,7 @@ Django installation. Each string should be a dotted Python path to:
different :attr:`~django.apps.AppConfig.label`. different :attr:`~django.apps.AppConfig.label`.
These rules apply regardless of whether :setting:`INSTALLED_APPS` These rules apply regardless of whether :setting:`INSTALLED_APPS`
references application configuration classes on application packages. references application configuration classes or application packages.
When several applications provide different versions of the same resource When several applications provide different versions of the same resource
(template, static file, management command, translation), the application (template, static file, management command, translation), the application
@ -1767,7 +1773,8 @@ Default: ``''`` (Empty string)
URL that handles the media served from :setting:`MEDIA_ROOT`, used URL that handles the media served from :setting:`MEDIA_ROOT`, used
for :doc:`managing stored files </topics/files>`. It must end in a slash if set for :doc:`managing stored files </topics/files>`. It must end in a slash if set
to a non-empty value. You will need to :ref:`configure these files to be served to a non-empty value. You will need to :ref:`configure these files to be served
<serving-uploaded-files-in-development>` in both development and production. <serving-uploaded-files-in-development>` in both development and production
environments.
If you want to use ``{{ MEDIA_URL }}`` in your templates, add If you want to use ``{{ MEDIA_URL }}`` in your templates, add
``'django.template.context_processors.media'`` in the ``'context_processors'`` ``'django.template.context_processors.media'`` in the ``'context_processors'``
@ -1928,6 +1935,12 @@ If you rotate your secret key, all of the above will be invalidated.
Secret keys are not used for passwords of users and key rotation will not Secret keys are not used for passwords of users and key rotation will not
affect them. affect them.
.. note::
The default :file:`settings.py` file created by :djadmin:`django-admin
startproject <startproject>` creates a unique ``SECRET_KEY`` for
convenience.
.. setting:: SECURE_BROWSER_XSS_FILTER .. setting:: SECURE_BROWSER_XSS_FILTER
SECURE_BROWSER_XSS_FILTER SECURE_BROWSER_XSS_FILTER
@ -1968,8 +1981,9 @@ header. It has no effect unless :setting:`SECURE_HSTS_SECONDS` is set to a
non-zero value. non-zero value.
.. warning:: .. warning::
Setting this incorrectly can irreversibly (for some time) break your site. Setting this incorrectly can irreversibly (for the value of
Read the :ref:`http-strict-transport-security` documentation first. :setting:`SECURE_HSTS_SECONDS`) break your site. Read the
:ref:`http-strict-transport-security` documentation first.
.. setting:: SECURE_HSTS_SECONDS .. setting:: SECURE_HSTS_SECONDS
@ -2057,7 +2071,7 @@ SECURE_REDIRECT_EXEMPT
.. versionadded:: 1.8 .. versionadded:: 1.8
Default: ``[]`` Default: ``[]`` (Empty list)
If a URL path matches a regular expression in this list, the request will not be If a URL path matches a regular expression in this list, the request will not be
redirected to HTTPS. If :setting:`SECURE_SSL_REDIRECT` is ``False``, this redirected to HTTPS. If :setting:`SECURE_SSL_REDIRECT` is ``False``, this
@ -2172,7 +2186,7 @@ See also the :doc:`/topics/signing` documentation.
SILENCED_SYSTEM_CHECKS SILENCED_SYSTEM_CHECKS
---------------------- ----------------------
Default: ``[]`` Default: ``[]`` (Empty list)
A list of identifiers of messages generated by the system check framework A list of identifiers of messages generated by the system check framework
(i.e. ``["models.W001"]``) that you wish to permanently acknowledge and ignore. (i.e. ``["models.W001"]``) that you wish to permanently acknowledge and ignore.
@ -2188,14 +2202,14 @@ TEMPLATES
.. versionadded:: 1.8 .. versionadded:: 1.8
Default:: ``[]`` (Empty list) Default: ``[]`` (Empty list)
A list containing the settings for all template engines to be used with A list containing the settings for all template engines to be used with
Django. Each item of the list is a dictionary containing the options for an Django. Each item of the list is a dictionary containing the options for an
individual engine. individual engine.
Here's a simple setup that tells the Django template engine to load templates Here's a simple setup that tells the Django template engine to load templates
from the ``templates`` subdirectories inside installed applications:: from the ``templates`` subdirectory inside each installed application::
TEMPLATES = [ TEMPLATES = [
{ {
@ -2242,7 +2256,7 @@ its default name is ``'whatever'``.
DIRS DIRS
~~~~ ~~~~
Default:: ``[]`` (Empty list) Default: ``[]`` (Empty list)
Directories where the engine should look for template source files, in search Directories where the engine should look for template source files, in search
order. order.
@ -2252,7 +2266,7 @@ order.
APP_DIRS APP_DIRS
~~~~~~~~ ~~~~~~~~
Default:: ``False`` Default: ``False``
Whether the engine should look for template source files inside installed Whether the engine should look for template source files inside installed
applications. applications.
@ -2262,7 +2276,7 @@ applications.
OPTIONS OPTIONS
~~~~~~~ ~~~~~~~
Default:: ``{}`` (Empty dict) Default: ``{}`` (Empty dict)
Extra parameters to pass to the template backend. Available parameters vary Extra parameters to pass to the template backend. Available parameters vary
depending on the template backend. depending on the template backend.
@ -2389,13 +2403,13 @@ The name of the class to use for starting the test suite. See
TEST_NON_SERIALIZED_APPS TEST_NON_SERIALIZED_APPS
------------------------ ------------------------
Default: ``[]`` Default: ``[]`` (Empty list)
In order to restore the database state between tests for In order to restore the database state between tests for
``TransactionTestCase``\s and database backends without transactions, Django ``TransactionTestCase``\s and database backends without transactions, Django
will :ref:`serialize the contents of all apps <test-case-serialized-rollback>` will :ref:`serialize the contents of all apps <test-case-serialized-rollback>`
when it starts the test run so it can then reload from that copy before tests when it starts the test run so it can then reload from that copy before running
that need it. tests that need it.
This slows down the startup time of the test runner; if you have apps that This slows down the startup time of the test runner; if you have apps that
you know don't need this feature, you can add their full names in here (e.g. you know don't need this feature, you can add their full names in here (e.g.
@ -2533,6 +2547,11 @@ translation machinery.
See also :setting:`LANGUAGE_CODE`, :setting:`USE_L10N` and :setting:`USE_TZ`. See also :setting:`LANGUAGE_CODE`, :setting:`USE_L10N` and :setting:`USE_TZ`.
.. note::
The default :file:`settings.py` file created by :djadmin:`django-admin
startproject <startproject>` includes ``USE_I18N = True`` for convenience.
.. setting:: USE_L10N .. setting:: USE_L10N
USE_L10N USE_L10N
@ -3027,7 +3046,7 @@ and a single database can manage content for multiple sites.
.. _settings-staticfiles: .. _settings-staticfiles:
Static files Static Files
============ ============
Settings for :mod:`django.contrib.staticfiles`. Settings for :mod:`django.contrib.staticfiles`.
@ -3051,7 +3070,7 @@ files</howto/static-files/index>` for more details about usage.
.. warning:: .. warning::
This should be an (initially empty) destination directory for collecting This should be an initially empty destination directory for collecting
your static files from their permanent locations into one directory for your static files from their permanent locations into one directory for
ease of deployment; it is **not** a place to store your static files ease of deployment; it is **not** a place to store your static files
permanently. You should do that in directories that will be found by permanently. You should do that in directories that will be found by
@ -3306,7 +3325,7 @@ Models
Security Security
-------- --------
* Cross Site Request Forgery protection * Cross Site Request Forgery Protection
* :setting:`CSRF_COOKIE_DOMAIN` * :setting:`CSRF_COOKIE_DOMAIN`
* :setting:`CSRF_COOKIE_NAME` * :setting:`CSRF_COOKIE_NAME`