diff --git a/docs/ref/settings.txt b/docs/ref/settings.txt index 58f4049542..c745ad519b 100644 --- a/docs/ref/settings.txt +++ b/docs/ref/settings.txt @@ -13,7 +13,7 @@ Settings and :setting:`STATICFILES_FINDERS`. Make sure you keep the components 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. @@ -66,8 +66,8 @@ Default: ``[]`` (Empty list) 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 -and password reset emails with links to malicious hosts by submitting requests -with a fake HTTP ``Host`` header, which is possible even under many +and triggering password reset emails with links to malicious hosts by submitting +requests with a fake HTTP ``Host`` header, which is possible even under many seemingly-safe web server configurations. 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 --------------- -Default: ``31449600`` (1 year, in seconds) +Default: ``31449600`` (approximately 1 year, 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 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 keep the cookies in-memory instead of on persistent storage. @@ -365,8 +365,8 @@ CSRF_COOKIE_NAME Default: ``'csrftoken'`` -The name of the cookie to use for the CSRF authentication token. This can be whatever you -want. See :doc:`/ref/csrf`. +The name of the cookie to use for the CSRF authentication token. This can be +whatever you want. See :doc:`/ref/csrf`. .. 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``, 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 @@ -403,7 +403,8 @@ Default: ``'django.views.csrf.csrf_failure'`` 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:: - def csrf_failure(request, reason="") + def csrf_failure(request, reason=""): + ... where ``reason`` is a short message (intended for developers or logging, not for end users) indicating the reason the request was rejected. See @@ -434,7 +435,7 @@ DATABASES Default: ``{}`` (Empty dictionary) 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. The :setting:`DATABASES` setting must configure a ``default`` database; @@ -739,7 +740,7 @@ Default: ``True`` This is an Oracle-specific setting. 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 @@ -879,7 +880,7 @@ DATABASE_ROUTERS Default: ``[]`` (Empty list) 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 database configurations `. @@ -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 requests being returned as "Bad Request (400)". +.. note:: + + The default :file:`settings.py` file created by :djadmin:`django-admin + startproject ` sets ``DEBUG = True`` for convenience. + .. _django/views/debug.py: https://github.com/django/django/blob/master/django/views/debug.py .. setting:: DEBUG_PROPAGATE_EXCEPTIONS @@ -1373,7 +1379,7 @@ FILE_UPLOAD_TEMP_DIR 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. If ``None``, Django will use the standard temporary directory for the operating system. For example, this will default to ``/tmp`` on \*nix-style operating @@ -1388,7 +1394,7 @@ FIRST_DAY_OF_WEEK 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 format internationalization, or when a format cannot be found for the current locale. @@ -1432,7 +1438,7 @@ Default: ``None`` 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`` 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``, 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: * an application configuration class, or -* a package containing a application. +* a package containing an application. :doc:`Learn more about application configurations `. @@ -1520,7 +1526,7 @@ Django installation. Each string should be a dotted Python path to: different :attr:`~django.apps.AppConfig.label`. 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 (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 for :doc:`managing stored 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 -` in both development and production. +` in both development and production +environments. If you want to use ``{{ MEDIA_URL }}`` in your templates, add ``'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 affect them. +.. note:: + + The default :file:`settings.py` file created by :djadmin:`django-admin + startproject ` creates a unique ``SECRET_KEY`` for + convenience. + .. setting:: 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. .. warning:: - Setting this incorrectly can irreversibly (for some time) break your site. - Read the :ref:`http-strict-transport-security` documentation first. + Setting this incorrectly can irreversibly (for the value of + :setting:`SECURE_HSTS_SECONDS`) break your site. Read the + :ref:`http-strict-transport-security` documentation first. .. setting:: SECURE_HSTS_SECONDS @@ -2057,7 +2071,7 @@ SECURE_REDIRECT_EXEMPT .. versionadded:: 1.8 -Default: ``[]`` +Default: ``[]`` (Empty list) 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 @@ -2172,7 +2186,7 @@ See also the :doc:`/topics/signing` documentation. SILENCED_SYSTEM_CHECKS ---------------------- -Default: ``[]`` +Default: ``[]`` (Empty list) A list of identifiers of messages generated by the system check framework (i.e. ``["models.W001"]``) that you wish to permanently acknowledge and ignore. @@ -2188,14 +2202,14 @@ TEMPLATES .. versionadded:: 1.8 -Default:: ``[]`` (Empty list) +Default: ``[]`` (Empty list) 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 individual engine. 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 = [ { @@ -2242,7 +2256,7 @@ its default name is ``'whatever'``. DIRS ~~~~ -Default:: ``[]`` (Empty list) +Default: ``[]`` (Empty list) Directories where the engine should look for template source files, in search order. @@ -2252,7 +2266,7 @@ order. APP_DIRS ~~~~~~~~ -Default:: ``False`` +Default: ``False`` Whether the engine should look for template source files inside installed applications. @@ -2262,7 +2276,7 @@ applications. OPTIONS ~~~~~~~ -Default:: ``{}`` (Empty dict) +Default: ``{}`` (Empty dict) Extra parameters to pass to the template backend. Available parameters vary 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 ------------------------ -Default: ``[]`` +Default: ``[]`` (Empty list) In order to restore the database state between tests for ``TransactionTestCase``\s and database backends without transactions, Django will :ref:`serialize the contents of all apps ` -when it starts the test run so it can then reload from that copy before tests -that need it. +when it starts the test run so it can then reload from that copy before running +tests that need it. 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. @@ -2533,6 +2547,11 @@ translation machinery. 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 ` includes ``USE_I18N = True`` for convenience. + .. setting:: USE_L10N USE_L10N @@ -3027,7 +3046,7 @@ and a single database can manage content for multiple sites. .. _settings-staticfiles: -Static files +Static Files ============ Settings for :mod:`django.contrib.staticfiles`. @@ -3051,7 +3070,7 @@ files` for more details about usage. .. 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 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 @@ -3306,7 +3325,7 @@ Models Security -------- -* Cross Site Request Forgery protection +* Cross Site Request Forgery Protection * :setting:`CSRF_COOKIE_DOMAIN` * :setting:`CSRF_COOKIE_NAME`