Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Fixed #14633 - Organized settings reference docs and added a topical …

…index.

Thanks Gabriel Hurley for the original idea
and adamv for the draft patch.
  • Loading branch information...
commit ba50d3e05bc9a33aef495a5fbca239afe52237b3 1 parent 0171ba6
@timgraham timgraham authored
View
11 docs/ref/contrib/comments/index.txt
@@ -34,7 +34,8 @@ To get started using the ``comments`` app, follow these steps:
#. Use the `comment template tags`_ below to embed comments in your
templates.
-You might also want to examine :doc:`/ref/contrib/comments/settings`.
+You might also want to examine :ref:`the available settings
+<settings-comments>`.
Comment template tags
=====================
@@ -335,6 +336,13 @@ output the CSRF token and cookie.
.. _honeypot: http://en.wikipedia.org/wiki/Honeypot_(computing)
+
+Configuration
+=============
+
+See :ref:`comment settings <settings-comments>`.
+
+
More information
================
@@ -342,7 +350,6 @@ More information
:maxdepth: 1
models
- settings
signals
custom
forms
View
33 docs/ref/contrib/comments/settings.txt
@@ -1,33 +0,0 @@
-================
-Comment settings
-================
-
-These settings configure the behavior of the comments framework:
-
-.. setting:: COMMENTS_HIDE_REMOVED
-
-COMMENTS_HIDE_REMOVED
----------------------
-
-If ``True`` (default), removed comments will be excluded from comment
-lists/counts (as taken from template tags). Otherwise, the template author is
-responsible for some sort of a "this comment has been removed by the site staff"
-message.
-
-.. setting:: COMMENT_MAX_LENGTH
-
-COMMENT_MAX_LENGTH
-------------------
-
-The maximum length of the comment field, in characters. Comments longer than
-this will be rejected. Defaults to 3000.
-
-.. setting:: COMMENTS_APP
-
-COMMENTS_APP
-------------
-
-An app which provides :doc:`customization of the comments framework
-</ref/contrib/comments/custom>`. Use the same dotted-string notation
-as in :setting:`INSTALLED_APPS`. Your custom :setting:`COMMENTS_APP`
-must also be listed in :setting:`INSTALLED_APPS`.
View
62 docs/ref/contrib/csrf.txt
@@ -488,60 +488,10 @@ developers of other reusable apps that want the same guarantees also use the
Settings
========
-A number of settings can be used to control Django's CSRF behavior.
+A number of settings can be used to control Django's CSRF behavior:
-CSRF_COOKIE_DOMAIN
-------------------
-
-Default: ``None``
-
-The domain to be used when setting the CSRF cookie. This can be useful for
-easily allowing cross-subdomain requests to be excluded from the normal cross
-site request forgery protection. It should be set to a string such as
-``".example.com"`` to allow a POST request from a form on one subdomain to be
-accepted by a view served from another subdomain.
-
-Please note that, with or without use of this setting, this CSRF protection
-mechanism is not safe against cross-subdomain attacks -- see `Limitations`_.
-
-CSRF_COOKIE_NAME
-----------------
-
-Default: ``'csrftoken'``
-
-The name of the cookie to use for the CSRF authentication token. This can be
-whatever you want.
-
-CSRF_COOKIE_PATH
-----------------
-
-Default: ``'/'``
-
-The path set on the CSRF cookie. This should either match the URL path of your
-Django installation or be a parent of that path.
-
-This is useful if you have multiple Django instances running under the same
-hostname. They can use different cookie paths, and each instance will only see
-its own CSRF cookie.
-
-CSRF_COOKIE_SECURE
-------------------
-
-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.
-
-CSRF_FAILURE_VIEW
------------------
-
-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="")
-
-where ``reason`` is a short message (intended for developers or logging, not for
-end users) indicating the reason the request was rejected.
+* :setting:`CSRF_COOKIE_DOMAIN`
+* :setting:`CSRF_COOKIE_NAME`
+* :setting:`CSRF_COOKIE_PATH`
+* :setting:`CSRF_COOKIE_SECURE`
+* :setting:`CSRF_FAILURE_VIEW`
View
94 docs/ref/contrib/messages.txt
@@ -78,8 +78,8 @@ Django provides three built-in storage classes:
:class:`~django.contrib.messages.storage.fallback.FallbackStorage` is the
default storage class. If it isn't suitable to your needs, you can select
-another storage class by setting `MESSAGE_STORAGE`_ to its full import path,
-for example::
+another storage class by setting setting:`MESSAGE_STORAGE` to its full import
+path, for example::
MESSAGE_STORAGE = 'django.contrib.messages.storage.cookie.CookieStorage'
@@ -87,6 +87,8 @@ To write your own storage class, subclass the ``BaseStorage`` class in
``django.contrib.messages.storage.base`` and implement the ``_get`` and
``_store`` methods.
+.. _message-level:
+
Message levels
--------------
@@ -108,7 +110,7 @@ Constant Purpose
``ERROR`` An action was **not** successful or some other failure occurred
=========== ========
-The `MESSAGE_LEVEL`_ setting can be used to change the minimum recorded level
+The :setting:`MESSAGE_LEVEL` setting can be used to change the minimum recorded level
(or it can be `changed per request`_). Attempts to add messages of a level less
than this will be ignored.
@@ -136,7 +138,7 @@ Level Constant Tag
============== ===========
To change the default tags for a message level (either built-in or custom),
-set the `MESSAGE_TAGS`_ setting to a dictionary containing the levels
+set the :setting:`MESSAGE_TAGS` setting to a dictionary containing the levels
you wish to change. As this extends the default tags, you only need to provide
tags for the levels you wish to override::
@@ -168,6 +170,8 @@ used tags (which are usually represented as HTML classes for the message)::
messages.warning(request, 'Your account expires in three days.')
messages.error(request, 'Document deleted.')
+.. _message-displaying:
+
Displaying messages
-------------------
@@ -216,7 +220,7 @@ Level Constant Value
============== =====
If you need to identify the custom levels in your HTML or CSS, you need to
-provide a mapping via the `MESSAGE_TAGS`_ setting.
+provide a mapping via the :setting:`MESSAGE_TAGS` setting.
.. note::
If you are creating a reusable application, it is recommended to use
@@ -316,80 +320,10 @@ window/tab will have its own browsing context.
Settings
========
-A few :doc:`Django settings </ref/settings>` give you control over message
+A few :ref:`settings<settings-messages>` give you control over message
behavior:
-MESSAGE_LEVEL
--------------
-
-Default: ``messages.INFO``
-
-This sets the minimum message that will be saved in the message storage. See
-`Message levels`_ above for more details.
-
-.. admonition:: Important
-
- If you override ``MESSAGE_LEVEL`` in your settings file and rely on any of
- the built-in constants, you must import the constants module directly to
- avoid the potential for circular imports, e.g.::
-
- from django.contrib.messages import constants as message_constants
- MESSAGE_LEVEL = message_constants.DEBUG
-
- If desired, you may specify the numeric values for the constants directly
- according to the values in the above :ref:`constants table
- <message-level-constants>`.
-
-MESSAGE_STORAGE
----------------
-
-Default: ``'django.contrib.messages.storage.fallback.FallbackStorage'``
-
-Controls where Django stores message data. Valid values are:
-
-* ``'django.contrib.messages.storage.fallback.FallbackStorage'``
-* ``'django.contrib.messages.storage.session.SessionStorage'``
-* ``'django.contrib.messages.storage.cookie.CookieStorage'``
-
-See `Storage backends`_ for more details.
-
-MESSAGE_TAGS
-------------
-
-Default::
-
- {messages.DEBUG: 'debug',
- messages.INFO: 'info',
- messages.SUCCESS: 'success',
- messages.WARNING: 'warning',
- messages.ERROR: 'error',}
-
-This sets the mapping of message level to message tag, which is typically
-rendered as a CSS class in HTML. If you specify a value, it will extend
-the default. This means you only have to specify those values which you need
-to override. See `Displaying messages`_ above for more details.
-
-.. admonition:: Important
-
- If you override ``MESSAGE_TAGS`` in your settings file and rely on any of
- the built-in constants, you must import the ``constants`` module directly to
- avoid the potential for circular imports, e.g.::
-
- from django.contrib.messages import constants as message_constants
- MESSAGE_TAGS = {message_constants.INFO: ''}
-
- If desired, you may specify the numeric values for the constants directly
- according to the values in the above :ref:`constants table
- <message-level-constants>`.
-
-SESSION_COOKIE_DOMAIN
----------------------
-
-Default: ``None``
-
-The storage backends that use cookies -- ``CookieStorage`` and
-``FallbackStorage`` -- use the value of :setting:`SESSION_COOKIE_DOMAIN` in
-setting their cookies. See the :doc:`settings documentation </ref/settings>`
-for more information on how this works and why you might need to set it.
-
-.. _Django settings: ../settings/
+* :setting:`MESSAGE_LEVEL`
+* :setting:`MESSAGE_STORAGE`
+* :setting:`MESSAGE_TAGS`
+* :ref:`SESSION_COOKIE_DOMAIN<messages-session_cookie_domain>`
View
108 docs/ref/contrib/staticfiles.txt
@@ -19,106 +19,14 @@ can easily be served in production.
Settings
========
-.. highlight:: python
-
-.. note::
-
- The following settings control the behavior of the staticfiles app.
-
-.. setting:: STATICFILES_DIRS
-
-STATICFILES_DIRS
-----------------
-
-Default: ``[]``
-
-This setting defines the additional locations the staticfiles app will traverse
-if the ``FileSystemFinder`` finder is enabled, e.g. if you use the
-:djadmin:`collectstatic` or :djadmin:`findstatic` management command or use the
-static file serving view.
-
-This should be set to a list or tuple of strings that contain full paths to
-your additional files directory(ies) e.g.::
-
- STATICFILES_DIRS = (
- "/home/special.polls.com/polls/static",
- "/home/polls.com/polls/static",
- "/opt/webfiles/common",
- )
-
-Prefixes (optional)
-"""""""""""""""""""
-
-In case you want to refer to files in one of the locations with an additional
-namespace, you can **optionally** provide a prefix as ``(prefix, path)``
-tuples, e.g.::
-
- STATICFILES_DIRS = (
- # ...
- ("downloads", "/opt/webfiles/stats"),
- )
-
-Example:
-
-Assuming you have :setting:`STATIC_URL` set ``'/static/'``, the
-:djadmin:`collectstatic` management command would collect the "stats" files
-in a ``'downloads'`` subdirectory of :setting:`STATIC_ROOT`.
-
-This would allow you to refer to the local file
-``'/opt/webfiles/stats/polls_20101022.tar.gz'`` with
-``'/static/downloads/polls_20101022.tar.gz'`` in your templates, e.g.:
-
-.. code-block:: html+django
-
- <a href="{{ STATIC_URL }}downloads/polls_20101022.tar.gz">
-
-.. setting:: STATICFILES_STORAGE
-
-STATICFILES_STORAGE
--------------------
-
-Default: ``'django.contrib.staticfiles.storage.StaticFilesStorage'``
-
-The file storage engine to use when collecting static files with the
-:djadmin:`collectstatic` management command.
-
-A ready-to-use instance of the storage backend defined in this setting
-can be found at ``django.contrib.staticfiles.storage.staticfiles_storage``.
-
-For an example, see :ref:`staticfiles-from-cdn`.
-
-.. setting:: STATICFILES_FINDERS
-
-STATICFILES_FINDERS
--------------------
-
-Default::
-
- ("django.contrib.staticfiles.finders.FileSystemFinder",
- "django.contrib.staticfiles.finders.AppDirectoriesFinder")
-
-The list of finder backends that know how to find static files in
-various locations.
-
-The default will find files stored in the :setting:`STATICFILES_DIRS` setting
-(using ``django.contrib.staticfiles.finders.FileSystemFinder``) and in a
-``static`` subdirectory of each app (using
-``django.contrib.staticfiles.finders.AppDirectoriesFinder``)
-
-One finder is disabled by default:
-``django.contrib.staticfiles.finders.DefaultStorageFinder``. If added to
-your :setting:`STATICFILES_FINDERS` setting, it will look for static files in
-the default file storage as defined by the :setting:`DEFAULT_FILE_STORAGE`
-setting.
-
-.. note::
-
- When using the ``AppDirectoriesFinder`` finder, make sure your apps
- can be found by staticfiles. Simply add the app to the
- :setting:`INSTALLED_APPS` setting of your site.
-
-Static file finders are currently considered a private interface, and this
-interface is thus undocumented.
+See :ref:`staticfiles settings <settings-staticfiles>` for details on the
+following settings:
+
+* :setting:`STATIC_ROOT`
+* :setting:`STATIC_URL`
+* :setting:`STATICFILES_DIRS`
+* :setting:`STATICFILES_STORAGE`
+* :setting:`STATICFILES_FINDERS`
Management Commands
===================
View
1,208 docs/ref/settings.txt
@@ -13,11 +13,12 @@ Settings
and :setting:`TEMPLATE_CONTEXT_PROCESSORS`. Make sure you keep the
components required by the features of Django you wish to use.
-Available settings
-==================
+Core settings
+=============
-Here's a full list of all available settings, in alphabetical order, and their
-default values.
+Here's a list of settings available in Django core and their default values.
+Settings provided by contrib apps are listed below, followed by a topical index
+of the core settings.
.. setting:: ABSOLUTE_URL_OVERRIDES
@@ -38,19 +39,6 @@ a model object and return its URL. This is a way of overriding
Note that the model name used in this setting should be all lower-case, regardless
of the case of the actual model class name.
-.. setting:: ADMIN_FOR
-
-ADMIN_FOR
----------
-
-Default: ``()`` (Empty tuple)
-
-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.
-
.. setting:: ADMINS
ADMINS
@@ -99,26 +87,6 @@ The :setting:`APPEND_SLASH` setting is only used if
:class:`~django.middleware.common.CommonMiddleware` is installed
(see :doc:`/topics/http/middleware`). See also :setting:`PREPEND_WWW`.
-.. setting:: AUTHENTICATION_BACKENDS
-
-AUTHENTICATION_BACKENDS
------------------------
-
-Default: ``('django.contrib.auth.backends.ModelBackend',)``
-
-A tuple of authentication backend classes (as strings) to use when attempting to
-authenticate a user. See the :ref:`authentication backends documentation
-<authentication-backends>` for details.
-
-.. setting:: AUTH_USER_MODEL
-
-AUTH_USER_MODEL
----------------
-
-Default: 'auth.User'
-
-The model to use to represent a User. See :ref:`auth-custom-user`.
-
.. setting:: CACHES
CACHES
@@ -179,7 +147,8 @@ implementation is equivalent to the function::
You may use any key function you want, as long as it has the same
argument signature.
-See the :ref:`cache documentation <cache_key_transformation>` for more information.
+See the :ref:`cache documentation <cache_key_transformation>` for more
+information.
.. setting:: CACHES-KEY_PREFIX
@@ -293,6 +262,8 @@ The default number of seconds to cache a page when the caching middleware or
See :doc:`/topics/cache`.
+.. _settings-csrf:
+
.. setting:: CSRF_COOKIE_DOMAIN
CSRF_COOKIE_DOMAIN
@@ -304,7 +275,7 @@ The domain to be used when setting the CSRF cookie. This can be useful for
easily allowing cross-subdomain requests to be excluded from the normal cross
site request forgery protection. It should be set to a string such as
``".example.com"`` to allow a POST request from a form on one subdomain to be
-accepted by accepted by a view served from another subdomain.
+accepted by a view served from another subdomain.
Please note that the presence of this setting does not imply that Django's CSRF
protection is safe from cross-subdomain attacks by default - please see the
@@ -361,7 +332,6 @@ where ``reason`` is a short message (intended for developers or logging, not for
end users) indicating the reason the request was rejected. See
:doc:`/ref/contrib/csrf`.
-
.. setting:: DATABASES
DATABASES
@@ -765,6 +735,8 @@ when you're debugging, but it'll rapidly consume memory on a production server.
.. _django/views/debug.py: https://github.com/django/django/blob/master/django/views/debug.py
+.. setting:: DEBUG_PROPAGATE_EXCEPTIONS
+
DEBUG_PROPAGATE_EXCEPTIONS
--------------------------
@@ -1270,54 +1242,6 @@ configuration process will be skipped.
.. _dictConfig: http://docs.python.org/library/logging.config.html#configuration-dictionary-schema
-.. setting:: LOGIN_REDIRECT_URL
-
-LOGIN_REDIRECT_URL
-------------------
-
-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 :func:`~django.contrib.auth.decorators.login_required`
-decorator, for example.
-
-.. versionchanged:: 1.5
-
-This setting now also accepts view function names and
-:ref:`named URL patterns <naming-url-patterns>` which can be used to reduce
-configuration duplication since you no longer have to define the URL in two
-places (``settings`` and URLconf).
-For backward compatibility reasons the default remains unchanged.
-
-.. setting:: LOGIN_URL
-
-LOGIN_URL
----------
-
-Default: ``'/accounts/login/'``
-
-The URL where requests are redirected for login, especially when using the
-:func:`~django.contrib.auth.decorators.login_required` decorator.
-
-.. versionchanged:: 1.5
-
-This setting now also accepts view function names and
-:ref:`named URL patterns <naming-url-patterns>` which can be used to reduce
-configuration duplication since you no longer have to define the URL in two
-places (``settings`` and URLconf).
-For backward compatibility reasons the default remains unchanged.
-
-.. setting:: LOGOUT_URL
-
-LOGOUT_URL
-----------
-
-Default: ``'/accounts/logout/'``
-
-LOGIN_URL counterpart.
-
.. setting:: MANAGERS
MANAGERS
@@ -1355,37 +1279,6 @@ to a non-empty value.
Example: ``"http://media.example.com/"``
-MESSAGE_LEVEL
--------------
-
-Default: `messages.INFO`
-
-Sets the minimum message level that will be recorded by the messages
-framework. See the :doc:`messages documentation </ref/contrib/messages>` for
-more details.
-
-MESSAGE_STORAGE
----------------
-
-Default: ``'django.contrib.messages.storage.fallback.FallbackStorage'``
-
-Controls where Django stores message data. See the
-:doc:`messages documentation </ref/contrib/messages>` for more details.
-
-MESSAGE_TAGS
-------------
-
-Default::
-
- {messages.DEBUG: 'debug',
- messages.INFO: 'info',
- messages.SUCCESS: 'success',
- messages.WARNING: 'warning',
- messages.ERROR: 'error',}
-
-Sets the mapping of message levels to message tags. See the
-:doc:`messages documentation </ref/contrib/messages>` for more details.
-
.. setting:: MIDDLEWARE_CLASSES
MIDDLEWARE_CLASSES
@@ -1441,33 +1334,6 @@ format has higher precedence and will be applied instead.
See also :setting:`DECIMAL_SEPARATOR`, :setting:`THOUSAND_SEPARATOR` and
:setting:`USE_THOUSAND_SEPARATOR`.
-.. setting:: PASSWORD_HASHERS
-
-PASSWORD_HASHERS
-----------------
-
-See :ref:`auth_password_storage`.
-
-Default::
-
- ('django.contrib.auth.hashers.PBKDF2PasswordHasher',
- 'django.contrib.auth.hashers.PBKDF2SHA1PasswordHasher',
- 'django.contrib.auth.hashers.BCryptPasswordHasher',
- 'django.contrib.auth.hashers.SHA1PasswordHasher',
- 'django.contrib.auth.hashers.MD5PasswordHasher',
- 'django.contrib.auth.hashers.UnsaltedMD5PasswordHasher',
- 'django.contrib.auth.hashers.CryptPasswordHasher',)
-
-.. setting:: PASSWORD_RESET_TIMEOUT_DAYS
-
-PASSWORD_RESET_TIMEOUT_DAYS
----------------------------
-
-Default: ``3``
-
-The number of days a password reset link is valid for. Used by the
-:mod:`django.contrib.auth` password reset mechanism.
-
.. setting:: PREPEND_WWW
PREPEND_WWW
@@ -1479,16 +1345,6 @@ Whether to prepend the "www." subdomain to URLs that don't have it. This is only
used if :class:`~django.middleware.common.CommonMiddleware` is installed
(see :doc:`/topics/http/middleware`). See also :setting:`APPEND_SLASH`.
-.. setting:: PROFANITIES_LIST
-
-PROFANITIES_LIST
-----------------
-
-Default: ``()`` (Empty tuple)
-
-A tuple of profanities, as strings, that will be forbidden in comments when
-``COMMENTS_ALLOW_PROFANITIES`` is ``False``.
-
.. setting:: ROOT_URLCONF
ROOT_URLCONF
@@ -1623,296 +1479,96 @@ Default: ``'root@localhost'``
The email address that error messages come from, such as those sent to
:setting:`ADMINS` and :setting:`MANAGERS`.
-.. setting:: SESSION_COOKIE_AGE
+.. setting:: SHORT_DATE_FORMAT
-SESSION_COOKIE_AGE
-------------------
+SHORT_DATE_FORMAT
+-----------------
-Default: ``1209600`` (2 weeks, in seconds)
+Default: ``m/d/Y`` (e.g. ``12/31/2003``)
-The age of session cookies, in seconds. See :doc:`/topics/http/sessions`.
+An available formatting that can be used for displaying date fields on
+templates. Note that if :setting:`USE_L10N` is set to ``True``, then the
+corresponding locale-dictated format has higher precedence and will be applied.
+See :tfilter:`allowed date format strings <date>`.
-.. setting:: SESSION_COOKIE_DOMAIN
+See also :setting:`DATE_FORMAT` and :setting:`SHORT_DATETIME_FORMAT`.
-SESSION_COOKIE_DOMAIN
+.. setting:: SHORT_DATETIME_FORMAT
+
+SHORT_DATETIME_FORMAT
---------------------
-Default: ``None``
+Default: ``m/d/Y P`` (e.g. ``12/31/2003 4 p.m.``)
-The domain to use for session cookies. Set this to a string such as
-``".example.com"`` for cross-domain cookies, or use ``None`` for a standard
-domain cookie. See the :doc:`/topics/http/sessions`.
+An available formatting that can be used for displaying datetime fields on
+templates. Note that if :setting:`USE_L10N` is set to ``True``, then the
+corresponding locale-dictated format has higher precedence and will be applied.
+See :tfilter:`allowed date format strings <date>`.
-.. setting:: SESSION_COOKIE_HTTPONLY
+See also :setting:`DATE_FORMAT` and :setting:`SHORT_DATE_FORMAT`.
-SESSION_COOKIE_HTTPONLY
------------------------
+.. setting:: SIGNING_BACKEND
-Default: ``True``
+SIGNING_BACKEND
+---------------
-Whether to use HTTPOnly flag on the session cookie. If this is set to
-``True``, client-side JavaScript will not to be able to access the
-session cookie.
+Default: 'django.core.signing.TimestampSigner'
-HTTPOnly_ is a flag included in a Set-Cookie HTTP response header. It
-is not part of the :rfc:`2109` standard for cookies, and it isn't honored
-consistently by all browsers. However, when it is honored, it can be a
-useful way to mitigate the risk of client side script accessing the
-protected cookie data.
+The backend used for signing cookies and other data.
-.. _HTTPOnly: https://www.owasp.org/index.php/HTTPOnly
+See also the :doc:`/topics/signing` documentation.
-.. setting:: SESSION_COOKIE_NAME
+.. setting:: TEMPLATE_CONTEXT_PROCESSORS
-SESSION_COOKIE_NAME
--------------------
+TEMPLATE_CONTEXT_PROCESSORS
+---------------------------
-Default: ``'sessionid'``
+Default::
-The name of the cookie to use for sessions. This can be whatever you want (but
-should be different from :setting:`LANGUAGE_COOKIE_NAME`).
-See the :doc:`/topics/http/sessions`.
+ ("django.contrib.auth.context_processors.auth",
+ "django.core.context_processors.debug",
+ "django.core.context_processors.i18n",
+ "django.core.context_processors.media",
+ "django.core.context_processors.static",
+ "django.core.context_processors.tz",
+ "django.contrib.messages.context_processors.messages")
-.. setting:: SESSION_COOKIE_PATH
+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.
-SESSION_COOKIE_PATH
--------------------
+.. setting:: TEMPLATE_DEBUG
-Default: ``'/'``
+TEMPLATE_DEBUG
+--------------
-The path set on the session cookie. This should either match the URL path of your
-Django installation or be parent of that path.
+Default: ``False``
-This is useful if you have multiple Django instances running under the same
-hostname. They can use different cookie paths, and each instance will only see
-its own session cookie.
+A boolean that turns on/off template debug mode. If this is ``True``, the fancy
+error page will display a detailed report for any exception raised during
+template rendering. This report contains the relevant snippet of the template,
+with the appropriate line highlighted.
-.. setting:: SESSION_CACHE_ALIAS
+Note that Django only displays fancy error pages if :setting:`DEBUG` is ``True``, so
+you'll want to set that to take advantage of this setting.
-SESSION_CACHE_ALIAS
--------------------
+See also :setting:`DEBUG`.
-Default: ``default``
+.. setting:: TEMPLATE_DIRS
-If you're using :ref:`cache-based session storage <cached-sessions-backend>`,
-this selects the cache to use.
+TEMPLATE_DIRS
+-------------
-.. setting:: SESSION_COOKIE_SECURE
+Default: ``()`` (Empty tuple)
-SESSION_COOKIE_SECURE
----------------------
+List of locations of the template source files searched by
+:class:`django.template.loaders.filesystem.Loader`, in search order.
-Default: ``False``
+Note that these paths should use Unix-style forward slashes, even on Windows.
-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 :doc:`/topics/http/sessions`.
+See :doc:`/topics/templates`.
-.. setting:: SESSION_ENGINE
-
-SESSION_ENGINE
---------------
-
-Default: ``django.contrib.sessions.backends.db``
-
-Controls where Django stores session data. Valid values are:
-
-* ``'django.contrib.sessions.backends.db'``
-* ``'django.contrib.sessions.backends.file'``
-* ``'django.contrib.sessions.backends.cache'``
-* ``'django.contrib.sessions.backends.cached_db'``
-* ``'django.contrib.sessions.backends.signed_cookies'``
-
-See :doc:`/topics/http/sessions`.
-
-.. setting:: SESSION_EXPIRE_AT_BROWSER_CLOSE
-
-SESSION_EXPIRE_AT_BROWSER_CLOSE
--------------------------------
-
-Default: ``False``
-
-Whether to expire the session when the user closes his or her browser.
-See the :doc:`/topics/http/sessions`.
-
-.. setting:: SESSION_FILE_PATH
-
-SESSION_FILE_PATH
------------------
-
-Default: ``None``
-
-If you're using file-based session storage, this sets the directory in
-which Django will store session data. See :doc:`/topics/http/sessions`. When
-the default value (``None``) is used, Django will use the standard temporary
-directory for the system.
-
-.. setting:: SESSION_SAVE_EVERY_REQUEST
-
-SESSION_SAVE_EVERY_REQUEST
---------------------------
-
-Default: ``False``
-
-Whether to save the session data on every request. See
-:doc:`/topics/http/sessions`.
-
-.. setting:: SHORT_DATE_FORMAT
-
-SHORT_DATE_FORMAT
------------------
-
-Default: ``m/d/Y`` (e.g. ``12/31/2003``)
-
-An available formatting that can be used for displaying date fields on
-templates. Note that if :setting:`USE_L10N` is set to ``True``, then the
-corresponding locale-dictated format has higher precedence and will be applied.
-See :tfilter:`allowed date format strings <date>`.
-
-See also :setting:`DATE_FORMAT` and :setting:`SHORT_DATETIME_FORMAT`.
-
-.. setting:: SHORT_DATETIME_FORMAT
-
-SHORT_DATETIME_FORMAT
----------------------
-
-Default: ``m/d/Y P`` (e.g. ``12/31/2003 4 p.m.``)
-
-An available formatting that can be used for displaying datetime fields on
-templates. Note that if :setting:`USE_L10N` is set to ``True``, then the
-corresponding locale-dictated format has higher precedence and will be applied.
-See :tfilter:`allowed date format strings <date>`.
-
-See also :setting:`DATE_FORMAT` and :setting:`SHORT_DATE_FORMAT`.
-
-.. setting:: SIGNING_BACKEND
-
-SIGNING_BACKEND
----------------
-
-Default: 'django.core.signing.TimestampSigner'
-
-The backend used for signing cookies and other data.
-
-See also the :doc:`/topics/signing` documentation.
-
-.. setting:: SITE_ID
-
-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 :doc:`/ref/contrib/sites`.
-
-.. _site framework docs: ../sites/
-
-.. setting:: STATIC_ROOT
-
-STATIC_ROOT
------------
-
-Default: ``''`` (Empty string)
-
-The absolute path to the directory where :djadmin:`collectstatic` will collect
-static files for deployment.
-
-Example: ``"/var/www/example.com/static/"``
-
-If the :doc:`staticfiles</ref/contrib/staticfiles>` contrib app is enabled
-(default) the :djadmin:`collectstatic` management command will collect static
-files into this directory. See the howto on :doc:`managing static
-files</howto/static-files>` for more details about usage.
-
-.. warning::
-
- 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
- :doc:`staticfiles</ref/contrib/staticfiles>`'s
- :setting:`finders<STATICFILES_FINDERS>`, which by default, are
- ``'static/'`` app sub-directories and any directories you include in
- :setting:`STATICFILES_DIRS`).
-
-See :doc:`staticfiles reference</ref/contrib/staticfiles>` and
-:setting:`STATIC_URL`.
-
-.. setting:: STATIC_URL
-
-STATIC_URL
-----------
-
-Default: ``None``
-
-URL to use when referring to static files located in :setting:`STATIC_ROOT`.
-
-Example: ``"/static/"`` or ``"http://static.example.com/"``
-
-If not ``None``, this will be used as the base path for
-:ref:`media definitions<form-media-paths>` and the
-:doc:`staticfiles app</ref/contrib/staticfiles>`.
-
-It must end in a slash if set to a non-empty value.
-
-See :setting:`STATIC_ROOT`.
-
-.. setting:: TEMPLATE_CONTEXT_PROCESSORS
-
-TEMPLATE_CONTEXT_PROCESSORS
----------------------------
-
-Default::
-
- ("django.contrib.auth.context_processors.auth",
- "django.core.context_processors.debug",
- "django.core.context_processors.i18n",
- "django.core.context_processors.media",
- "django.core.context_processors.static",
- "django.core.context_processors.tz",
- "django.contrib.messages.context_processors.messages")
-
-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.
-
-.. setting:: TEMPLATE_DEBUG
-
-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 exception raised during
-template rendering. This report contains the relevant snippet of the template,
-with the appropriate line highlighted.
-
-Note that Django only displays fancy error pages if :setting:`DEBUG` is ``True``, so
-you'll want to set that to take advantage of this setting.
-
-See also :setting:`DEBUG`.
-
-.. setting:: TEMPLATE_DIRS
-
-TEMPLATE_DIRS
--------------
-
-Default: ``()`` (Empty tuple)
-
-List of locations of the template source files searched by
-:class:`django.template.loaders.filesystem.Loader`, in search order.
-
-Note that these paths should use Unix-style forward slashes, even on Windows.
-
-See :doc:`/topics/templates`.
-
-.. setting:: TEMPLATE_LOADERS
+.. setting:: TEMPLATE_LOADERS
TEMPLATE_LOADERS
----------------
@@ -2194,8 +1850,41 @@ The default value for the X-Frame-Options header used by
:class:`~django.middleware.clickjacking.XFrameOptionsMiddleware`. See the
:doc:`clickjacking protection </ref/clickjacking/>` documentation.
-Deprecated settings
-===================
+
+Admindocs
+=========
+
+Settings for :mod:`django.contrib.admindocs`.
+
+.. setting:: ADMIN_FOR
+
+ADMIN_FOR
+---------
+
+Default: ``()`` (Empty tuple)
+
+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.
+
+
+Auth
+====
+
+Settings for :mod:`django.contrib.auth`.
+
+.. setting:: AUTHENTICATION_BACKENDS
+
+AUTHENTICATION_BACKENDS
+-----------------------
+
+Default: ``('django.contrib.auth.backends.ModelBackend',)``
+
+A tuple of authentication backend classes (as strings) to use when attempting to
+authenticate a user. See the :ref:`authentication backends documentation
+<authentication-backends>` for details.
.. setting:: AUTH_PROFILE_MODULE
@@ -2212,3 +1901,690 @@ Default: Not defined
The site-specific user profile model used by this site. See
:ref:`User profiles <auth-profiles>`.
+
+.. setting:: AUTH_USER_MODEL
+
+AUTH_USER_MODEL
+---------------
+
+Default: 'auth.User'
+
+The model to use to represent a User. See :ref:`auth-custom-user`.
+
+.. setting:: LOGIN_REDIRECT_URL
+
+LOGIN_REDIRECT_URL
+------------------
+
+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 :func:`~django.contrib.auth.decorators.login_required`
+decorator, for example.
+
+.. versionchanged:: 1.5
+
+This setting now also accepts view function names and
+:ref:`named URL patterns <naming-url-patterns>` which can be used to reduce
+configuration duplication since you no longer have to define the URL in two
+places (``settings`` and URLconf).
+For backward compatibility reasons the default remains unchanged.
+
+.. setting:: LOGIN_URL
+
+LOGIN_URL
+---------
+
+Default: ``'/accounts/login/'``
+
+The URL where requests are redirected for login, especially when using the
+:func:`~django.contrib.auth.decorators.login_required` decorator.
+
+.. versionchanged:: 1.5
+
+This setting now also accepts view function names and
+:ref:`named URL patterns <naming-url-patterns>` which can be used to reduce
+configuration duplication since you no longer have to define the URL in two
+places (``settings`` and URLconf).
+For backward compatibility reasons the default remains unchanged.
+
+.. setting:: LOGOUT_URL
+
+LOGOUT_URL
+----------
+
+Default: ``'/accounts/logout/'``
+
+LOGIN_URL counterpart.
+
+.. setting:: PASSWORD_RESET_TIMEOUT_DAYS
+
+PASSWORD_RESET_TIMEOUT_DAYS
+---------------------------
+
+Default: ``3``
+
+The number of days a password reset link is valid for. Used by the
+:mod:`django.contrib.auth` password reset mechanism.
+
+.. setting:: PASSWORD_HASHERS
+
+PASSWORD_HASHERS
+----------------
+
+See :ref:`auth_password_storage`.
+
+Default::
+
+ ('django.contrib.auth.hashers.PBKDF2PasswordHasher',
+ 'django.contrib.auth.hashers.PBKDF2SHA1PasswordHasher',
+ 'django.contrib.auth.hashers.BCryptPasswordHasher',
+ 'django.contrib.auth.hashers.SHA1PasswordHasher',
+ 'django.contrib.auth.hashers.MD5PasswordHasher',
+ 'django.contrib.auth.hashers.UnsaltedMD5PasswordHasher',
+ 'django.contrib.auth.hashers.CryptPasswordHasher',)
+
+
+.. _settings-comments:
+
+Comments
+========
+
+Settings for :mod:`django.contrib.comments`.
+
+.. setting:: COMMENTS_HIDE_REMOVED
+
+COMMENTS_HIDE_REMOVED
+---------------------
+
+If ``True`` (default), removed comments will be excluded from comment
+lists/counts (as taken from template tags). Otherwise, the template author is
+responsible for some sort of a "this comment has been removed by the site staff"
+message.
+
+.. setting:: COMMENT_MAX_LENGTH
+
+COMMENT_MAX_LENGTH
+------------------
+
+The maximum length of the comment field, in characters. Comments longer than
+this will be rejected. Defaults to 3000.
+
+.. setting:: COMMENTS_APP
+
+COMMENTS_APP
+------------
+
+An app which provides :doc:`customization of the comments framework
+</ref/contrib/comments/custom>`. Use the same dotted-string notation
+as in :setting:`INSTALLED_APPS`. Your custom :setting:`COMMENTS_APP`
+must also be listed in :setting:`INSTALLED_APPS`.
+
+.. setting:: PROFANITIES_LIST
+
+PROFANITIES_LIST
+----------------
+
+Default: ``()`` (Empty tuple)
+
+A tuple of profanities, as strings, that will be forbidden in comments when
+``COMMENTS_ALLOW_PROFANITIES`` is ``False``.
+
+
+.. _settings-messages:
+
+Messages
+========
+
+Settings for :mod:`django.contrib.messages`.
+
+.. setting:: MESSAGE_LEVEL
+
+MESSAGE_LEVEL
+-------------
+
+Default: `messages.INFO`
+
+Sets the minimum message level that will be recorded by the messages
+framework. See :ref:`message levels <message-level>` for more details.
+
+.. admonition:: Important
+
+ If you override ``MESSAGE_LEVEL`` in your settings file and rely on any of
+ the built-in constants, you must import the constants module directly to
+ avoid the potential for circular imports, e.g.::
+
+ from django.contrib.messages import constants as message_constants
+ MESSAGE_LEVEL = message_constants.DEBUG
+
+ If desired, you may specify the numeric values for the constants directly
+ according to the values in the above :ref:`constants table
+ <message-level-constants>`.
+
+.. setting:: MESSAGE_STORAGE
+
+MESSAGE_STORAGE
+---------------
+
+Default: ``'django.contrib.messages.storage.fallback.FallbackStorage'``
+
+Controls where Django stores message data. Valid values are:
+
+* ``'django.contrib.messages.storage.fallback.FallbackStorage'``
+* ``'django.contrib.messages.storage.session.SessionStorage'``
+* ``'django.contrib.messages.storage.cookie.CookieStorage'``
+
+See :ref:`message storage backends <message-storage-backends>` for more details.
+
+.. setting:: MESSAGE_TAGS
+
+MESSAGE_TAGS
+------------
+
+Default::
+
+ {messages.DEBUG: 'debug',
+ messages.INFO: 'info',
+ messages.SUCCESS: 'success',
+ messages.WARNING: 'warning',
+ messages.ERROR: 'error',}
+
+This sets the mapping of message level to message tag, which is typically
+rendered as a CSS class in HTML. If you specify a value, it will extend
+the default. This means you only have to specify those values which you need
+to override. See :ref:`message-displaying` above for more details.
+
+.. admonition:: Important
+
+ If you override ``MESSAGE_TAGS`` in your settings file and rely on any of
+ the built-in constants, you must import the ``constants`` module directly to
+ avoid the potential for circular imports, e.g.::
+
+ from django.contrib.messages import constants as message_constants
+ MESSAGE_TAGS = {message_constants.INFO: ''}
+
+ If desired, you may specify the numeric values for the constants directly
+ according to the values in the above :ref:`constants table
+ <message-level-constants>`.
+
+.. _messages-session_cookie_domain:
+
+SESSION_COOKIE_DOMAIN
+---------------------
+
+Default: ``None``
+
+The storage backends that use cookies -- ``CookieStorage`` and
+``FallbackStorage`` -- use the value of :setting:`SESSION_COOKIE_DOMAIN` in
+setting their cookies.
+
+
+.. _settings-sessions:
+
+Sessions
+========
+
+Settings for :mod:`django.contrib.sessions`.
+
+.. setting:: SESSION_CACHE_ALIAS
+
+SESSION_CACHE_ALIAS
+-------------------
+
+Default: ``default``
+
+If you're using :ref:`cache-based session storage <cached-sessions-backend>`,
+this selects the cache to use.
+
+.. setting:: SESSION_COOKIE_AGE
+
+SESSION_COOKIE_AGE
+------------------
+
+Default: ``1209600`` (2 weeks, in seconds)
+
+The age of session cookies, in seconds.
+
+.. setting:: SESSION_COOKIE_DOMAIN
+
+SESSION_COOKIE_DOMAIN
+---------------------
+
+Default: ``None``
+
+The domain to use for session cookies. Set this to a string such as
+``".example.com"`` (note the leading dot!) for cross-domain cookies, or use
+``None`` for a standard domain cookie.
+
+.. setting:: SESSION_COOKIE_HTTPONLY
+
+SESSION_COOKIE_HTTPONLY
+-----------------------
+
+Default: ``True``
+
+Whether to use HTTPOnly flag on the session cookie. If this is set to
+``True``, client-side JavaScript will not to be able to access the
+session cookie.
+
+HTTPOnly_ is a flag included in a Set-Cookie HTTP response header. It
+is not part of the :rfc:`2109` standard for cookies, and it isn't honored
+consistently by all browsers. However, when it is honored, it can be a
+useful way to mitigate the risk of client side script accessing the
+protected cookie data.
+
+.. _HTTPOnly: https://www.owasp.org/index.php/HTTPOnly
+
+.. setting:: SESSION_COOKIE_NAME
+
+SESSION_COOKIE_NAME
+-------------------
+
+Default: ``'sessionid'``
+
+The name of the cookie to use for sessions. This can be whatever you want (but
+should be different from :setting:`LANGUAGE_COOKIE_NAME`).
+
+.. setting:: SESSION_COOKIE_PATH
+
+SESSION_COOKIE_PATH
+-------------------
+
+Default: ``'/'``
+
+The path set on the session cookie. This should either match the URL path of your
+Django installation or be parent of that path.
+
+This is useful if you have multiple Django instances running under the same
+hostname. They can use different cookie paths, and each instance will only see
+its own session cookie.
+
+.. setting:: SESSION_COOKIE_SECURE
+
+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.
+
+.. setting:: SESSION_ENGINE
+
+SESSION_ENGINE
+--------------
+
+Default: ``django.contrib.sessions.backends.db``
+
+Controls where Django stores session data. Valid values are:
+
+* ``'django.contrib.sessions.backends.db'``
+* ``'django.contrib.sessions.backends.file'``
+* ``'django.contrib.sessions.backends.cache'``
+* ``'django.contrib.sessions.backends.cached_db'``
+* ``'django.contrib.sessions.backends.signed_cookies'``
+
+See :ref:`configuring-sessions` for more details.
+
+.. setting:: SESSION_EXPIRE_AT_BROWSER_CLOSE
+
+SESSION_EXPIRE_AT_BROWSER_CLOSE
+-------------------------------
+
+Default: ``False``
+
+Whether to expire the session when the user closes his or her browser. See
+"Browser-length sessions vs. persistent sessions" above.
+
+.. setting:: SESSION_FILE_PATH
+
+SESSION_FILE_PATH
+-----------------
+
+Default: ``None``
+
+If you're using file-based session storage, this sets the directory in
+which Django will store session data. When the default value (``None``) is
+used, Django will use the standard temporary directory for the system.
+
+
+.. setting:: SESSION_SAVE_EVERY_REQUEST
+
+SESSION_SAVE_EVERY_REQUEST
+--------------------------
+
+Default: ``False``
+
+Whether to save the session data on every request. If this is ``False``
+(default), then the session data will only be saved if it has been modified --
+that is, if any of its dictionary values have been assigned or deleted.
+
+
+Sites
+=====
+
+Settings for :mod:`django.contrib.sites`.
+
+.. setting:: SITE_ID
+
+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 sites
+and a single database can manage content for multiple sites.
+
+
+.. _settings-staticfiles:
+
+Static files
+============
+
+Settings for :mod:`django.contrib.staticfiles`.
+
+.. setting:: STATIC_ROOT
+
+STATIC_ROOT
+-----------
+
+Default: ``''`` (Empty string)
+
+The absolute path to the directory where :djadmin:`collectstatic` will collect
+static files for deployment.
+
+Example: ``"/var/www/example.com/static/"``
+
+If the :doc:`staticfiles</ref/contrib/staticfiles>` contrib app is enabled
+(default) the :djadmin:`collectstatic` management command will collect static
+files into this directory. See the howto on :doc:`managing static
+files</howto/static-files>` for more details about usage.
+
+.. warning::
+
+ 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
+ :doc:`staticfiles</ref/contrib/staticfiles>`'s
+ :setting:`finders<STATICFILES_FINDERS>`, which by default, are
+ ``'static/'`` app sub-directories and any directories you include in
+ :setting:`STATICFILES_DIRS`).
+
+.. setting:: STATIC_URL
+
+STATIC_URL
+----------
+
+Default: ``None``
+
+URL to use when referring to static files located in :setting:`STATIC_ROOT`.
+
+Example: ``"/static/"`` or ``"http://static.example.com/"``
+
+If not ``None``, this will be used as the base path for
+:ref:`media definitions<form-media-paths>` and the
+:doc:`staticfiles app</ref/contrib/staticfiles>`.
+
+It must end in a slash if set to a non-empty value.
+
+.. setting:: STATICFILES_DIRS
+
+STATICFILES_DIRS
+----------------
+
+Default: ``[]``
+
+This setting defines the additional locations the staticfiles app will traverse
+if the ``FileSystemFinder`` finder is enabled, e.g. if you use the
+:djadmin:`collectstatic` or :djadmin:`findstatic` management command or use the
+static file serving view.
+
+This should be set to a list or tuple of strings that contain full paths to
+your additional files directory(ies) e.g.::
+
+ STATICFILES_DIRS = (
+ "/home/special.polls.com/polls/static",
+ "/home/polls.com/polls/static",
+ "/opt/webfiles/common",
+ )
+
+Prefixes (optional)
+~~~~~~~~~~~~~~~~~~~
+
+In case you want to refer to files in one of the locations with an additional
+namespace, you can **optionally** provide a prefix as ``(prefix, path)``
+tuples, e.g.::
+
+ STATICFILES_DIRS = (
+ # ...
+ ("downloads", "/opt/webfiles/stats"),
+ )
+
+Example:
+
+Assuming you have :setting:`STATIC_URL` set ``'/static/'``, the
+:djadmin:`collectstatic` management command would collect the "stats" files
+in a ``'downloads'`` subdirectory of :setting:`STATIC_ROOT`.
+
+This would allow you to refer to the local file
+``'/opt/webfiles/stats/polls_20101022.tar.gz'`` with
+``'/static/downloads/polls_20101022.tar.gz'`` in your templates, e.g.:
+
+.. code-block:: html+django
+
+ <a href="{{ STATIC_URL }}downloads/polls_20101022.tar.gz">
+
+.. setting:: STATICFILES_STORAGE
+
+STATICFILES_STORAGE
+-------------------
+
+Default: ``'django.contrib.staticfiles.storage.StaticFilesStorage'``
+
+The file storage engine to use when collecting static files with the
+:djadmin:`collectstatic` management command.
+
+A ready-to-use instance of the storage backend defined in this setting
+can be found at ``django.contrib.staticfiles.storage.staticfiles_storage``.
+
+For an example, see :ref:`staticfiles-from-cdn`.
+
+.. setting:: STATICFILES_FINDERS
+
+STATICFILES_FINDERS
+-------------------
+
+Default::
+
+ ("django.contrib.staticfiles.finders.FileSystemFinder",
+ "django.contrib.staticfiles.finders.AppDirectoriesFinder")
+
+The list of finder backends that know how to find static files in
+various locations.
+
+The default will find files stored in the :setting:`STATICFILES_DIRS` setting
+(using ``django.contrib.staticfiles.finders.FileSystemFinder``) and in a
+``static`` subdirectory of each app (using
+``django.contrib.staticfiles.finders.AppDirectoriesFinder``)
+
+One finder is disabled by default:
+``django.contrib.staticfiles.finders.DefaultStorageFinder``. If added to
+your :setting:`STATICFILES_FINDERS` setting, it will look for static files in
+the default file storage as defined by the :setting:`DEFAULT_FILE_STORAGE`
+setting.
+
+.. note::
+
+ When using the ``AppDirectoriesFinder`` finder, make sure your apps
+ can be found by staticfiles. Simply add the app to the
+ :setting:`INSTALLED_APPS` setting of your site.
+
+Static file finders are currently considered a private interface, and this
+interface is thus undocumented.
+
+Core Settings Topical Index
+===========================
+
+Cache
+-----
+* :setting:`CACHES`
+* :setting:`CACHE_MIDDLEWARE_ALIAS`
+* :setting:`CACHE_MIDDLEWARE_ANONYMOUS_ONLY`
+* :setting:`CACHE_MIDDLEWARE_KEY_PREFIX`
+* :setting:`CACHE_MIDDLEWARE_SECONDS`
+
+Database
+--------
+* :setting:`DATABASES`
+* :setting:`DATABASE_ROUTERS`
+* :setting:`DEFAULT_INDEX_TABLESPACE`
+* :setting:`DEFAULT_TABLESPACE`
+* :setting:`TRANSACTIONS_MANAGED`
+
+Debugging
+---------
+* :setting:`DEBUG`
+* :setting:`DEBUG_PROPAGATE_EXCEPTIONS`
+
+Email
+-----
+* :setting:`ADMINS`
+* :setting:`DEFAULT_CHARSET`
+* :setting:`DEFAULT_FROM_EMAIL`
+* :setting:`EMAIL_BACKEND`
+* :setting:`EMAIL_FILE_PATH`
+* :setting:`EMAIL_HOST`
+* :setting:`EMAIL_HOST_PASSWORD`
+* :setting:`EMAIL_HOST_USER`
+* :setting:`EMAIL_PORT`
+* :setting:`EMAIL_SUBJECT_PREFIX`
+* :setting:`EMAIL_USE_TLS`
+* :setting:`MANAGERS`
+* :setting:`SEND_BROKEN_LINK_EMAILS`
+* :setting:`SERVER_EMAIL`
+
+Error reporting
+---------------
+* :setting:`DEFAULT_EXCEPTION_REPORTER_FILTER`
+* :setting:`IGNORABLE_404_URLS`
+* :setting:`MANAGERS`
+* :setting:`SEND_BROKEN_LINK_EMAILS`
+
+File uploads
+------------
+* :setting:`DEFAULT_FILE_STORAGE`
+* :setting:`FILE_CHARSET`
+* :setting:`FILE_UPLOAD_HANDLERS`
+* :setting:`FILE_UPLOAD_MAX_MEMORY_SIZE`
+* :setting:`FILE_UPLOAD_PERMISSIONS`
+* :setting:`FILE_UPLOAD_TEMP_DIR`
+* :setting:`MEDIA_ROOT`
+* :setting:`MEDIA_URL`
+
+Globalization (i18n/l10n)
+-------------------------
+* :setting:`DATE_FORMAT`
+* :setting:`DATE_INPUT_FORMATS`
+* :setting:`DATETIME_FORMAT`
+* :setting:`DATETIME_INPUT_FORMATS`
+* :setting:`DECIMAL_SEPARATOR`
+* :setting:`FIRST_DAY_OF_WEEK`
+* :setting:`FORMAT_MODULE_PATH`
+* :setting:`LANGUAGE_CODE`
+* :setting:`LANGUAGE_COOKIE_NAME`
+* :setting:`LANGUAGES`
+* :setting:`LOCALE_PATHS`
+* :setting:`MONTH_DAY_FORMAT`
+* :setting:`NUMBER_GROUPING`
+* :setting:`SHORT_DATE_FORMAT`
+* :setting:`SHORT_DATETIME_FORMAT`
+* :setting:`THOUSAND_SEPARATOR`
+* :setting:`TIME_FORMAT`
+* :setting:`TIME_INPUT_FORMATS`
+* :setting:`TIME_ZONE`
+* :setting:`USE_I18N`
+* :setting:`USE_L10N`
+* :setting:`USE_THOUSAND_SEPARATOR`
+* :setting:`USE_TZ`
+* :setting:`YEAR_MONTH_FORMAT`
+
+HTTP
+----
+* :setting:`DEFAULT_CHARSET`
+* :setting:`DEFAULT_CONTENT_TYPE`
+* :setting:`DISALLOWED_USER_AGENTS`
+* :setting:`FORCE_SCRIPT_NAME`
+* :setting:`INTERNAL_IPS`
+* :setting:`MIDDLEWARE_CLASSES`
+* :setting:`SECURE_PROXY_SSL_HEADER`
+* :setting:`SIGNING_BACKEND`
+* :setting:`USE_ETAGS`
+* :setting:`USE_X_FORWARDED_HOST`
+* :setting:`WSGI_APPLICATION`
+
+Logging
+-------
+* :setting:`LOGGING`
+* :setting:`LOGGING_CONFIG`
+
+Models
+------
+* :setting:`ABSOLUTE_URL_OVERRIDES`
+* :setting:`FIXTURE_DIRS`
+* :setting:`INSTALLED_APPS`
+
+Security
+--------
+* Cross Site Request Forgery protection
+
+ * :setting:`CSRF_COOKIE_DOMAIN`
+ * :setting:`CSRF_COOKIE_NAME`
+ * :setting:`CSRF_COOKIE_PATH`
+ * :setting:`CSRF_COOKIE_SECURE`
+ * :setting:`CSRF_FAILURE_VIEW`
+
+* :setting:`SECRET_KEY`
+* :setting:`X_FRAME_OPTIONS`
+
+Serialization
+-------------
+* :setting:`DEFAULT_CHARSET`
+* :setting:`SERIALIZATION_MODULES`
+
+Templates
+---------
+* :setting:`ALLOWED_INCLUDE_ROOTS`
+* :setting:`TEMPLATE_CONTEXT_PROCESSORS`
+* :setting:`TEMPLATE_DEBUG`
+* :setting:`TEMPLATE_DIRS`
+* :setting:`TEMPLATE_LOADERS`
+* :setting:`TEMPLATE_STRING_IF_INVALID`
+
+Testing
+-------
+* Database
+
+ * :setting:`TEST_CHARSET`
+ * :setting:`TEST_COLLATION`
+ * :setting:`TEST_DEPENDENCIES`
+ * :setting:`TEST_MIRROR`
+ * :setting:`TEST_NAME`
+ * :setting:`TEST_CREATE`
+ * :setting:`TEST_USER`
+ * :setting:`TEST_USER_CREATE`
+ * :setting:`TEST_PASSWD`
+ * :setting:`TEST_TBLSPACE`
+ * :setting:`TEST_TBLSPACE_TMP`
+
+* :setting:`TEST_RUNNER`
+
+URLs
+----
+* :setting:`APPEND_SLASH`
+* :setting:`PREPEND_WWW`
+* :setting:`ROOT_URLCONF`
View
117 docs/topics/http/sessions.txt
@@ -28,6 +28,8 @@ If you don't want to use sessions, you might as well remove the
``'django.contrib.sessions'`` from your :setting:`INSTALLED_APPS`.
It'll save you a small bit of overhead.
+.. _configuring-sessions:
+
Configuring the session engine
==============================
@@ -499,111 +501,20 @@ session data is stored by the users' browsers.
Settings
========
-A few :doc:`Django settings </ref/settings>` give you control over session
+A few :ref:`Django settings <settings-sessions>` give you control over session
behavior:
-SESSION_ENGINE
---------------
-
-Default: ``django.contrib.sessions.backends.db``
-
-Controls where Django stores session data. Valid values are:
-
-* ``'django.contrib.sessions.backends.db'``
-* ``'django.contrib.sessions.backends.file'``
-* ``'django.contrib.sessions.backends.cache'``
-* ``'django.contrib.sessions.backends.cached_db'``
-* ``'django.contrib.sessions.backends.signed_cookies'``
-
-See `configuring the session engine`_ for more details.
-
-SESSION_FILE_PATH
------------------
-
-Default: ``/tmp/``
-
-If you're using file-based session storage, this sets the directory in
-which Django will store session data.
-
-SESSION_COOKIE_AGE
-------------------
-
-Default: ``1209600`` (2 weeks, in seconds)
-
-The age of session cookies, in seconds.
-
-SESSION_COOKIE_DOMAIN
----------------------
-
-Default: ``None``
-
-The domain to use for session cookies. Set this to a string such as
-``".example.com"`` (note the leading dot!) for cross-domain cookies, or use
-``None`` for a standard domain cookie.
-
-SESSION_COOKIE_HTTPONLY
------------------------
-
-Default: ``True``
-
-Whether to use HTTPOnly flag on the session cookie. If this is set to
-``True``, client-side JavaScript will not to be able to access the
-session cookie.
-
-HTTPOnly_ is a flag included in a Set-Cookie HTTP response header. It
-is not part of the :rfc:`2109` standard for cookies, and it isn't honored
-consistently by all browsers. However, when it is honored, it can be a
-useful way to mitigate the risk of client side script accessing the
-protected cookie data.
-
-.. _HTTPOnly: https://www.owasp.org/index.php/HTTPOnly
-
-SESSION_COOKIE_NAME
--------------------
-
-Default: ``'sessionid'``
-
-The name of the cookie to use for sessions. This can be whatever you want.
-
-SESSION_COOKIE_PATH
--------------------
-
-Default: ``'/'``
-
-The path set on the session cookie. This should either match the URL path of
-your Django installation or be parent of that path.
-
-This is useful if you have multiple Django instances running under the same
-hostname. They can use different cookie paths, and each instance will only see
-its own session cookie.
-
-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.
-
-SESSION_EXPIRE_AT_BROWSER_CLOSE
--------------------------------
-
-Default: ``False``
-
-Whether to expire the session when the user closes his or her browser. See
-"Browser-length sessions vs. persistent sessions" above.
-
-SESSION_SAVE_EVERY_REQUEST
---------------------------
-
-Default: ``False``
-
-Whether to save the session data on every request. If this is ``False``
-(default), then the session data will only be saved if it has been modified --
-that is, if any of its dictionary values have been assigned or deleted.
-
-.. _Django settings: ../settings/
+* :setting:`SESSION_CACHE_ALIAS`
+* :setting:`SESSION_COOKIE_AGE`
+* :setting:`SESSION_COOKIE_DOMAIN`
+* :setting:`SESSION_COOKIE_HTTPONLY`
+* :setting:`SESSION_COOKIE_NAME`
+* :setting:`SESSION_COOKIE_PATH`
+* :setting:`SESSION_COOKIE_SECURE`
+* :setting:`SESSION_ENGINE`
+* :setting:`SESSION_EXPIRE_AT_BROWSER_CLOSE`
+* :setting:`SESSION_FILE_PATH`
+* :setting:`SESSION_SAVE_EVERY_REQUEST`
Technical details
=================
Please sign in to comment.
Something went wrong with that request. Please try again.