From ba50d3e05bc9a33aef495a5fbca239afe52237b3 Mon Sep 17 00:00:00 2001 From: Tim Graham Date: Sat, 12 Jan 2013 18:44:53 -0500 Subject: [PATCH] Fixed #14633 - Organized settings reference docs and added a topical index. Thanks Gabriel Hurley for the original idea and adamv for the draft patch. --- docs/ref/contrib/comments/index.txt | 11 +- docs/ref/contrib/comments/settings.txt | 33 - docs/ref/contrib/csrf.txt | 62 +- docs/ref/contrib/messages.txt | 94 +- docs/ref/contrib/staticfiles.txt | 106 +-- docs/ref/settings.txt | 1092 ++++++++++++++++-------- docs/topics/http/sessions.txt | 117 +-- 7 files changed, 784 insertions(+), 731 deletions(-) delete mode 100644 docs/ref/contrib/comments/settings.txt diff --git a/docs/ref/contrib/comments/index.txt b/docs/ref/contrib/comments/index.txt index 8275092d2f..d4e967b4b2 100644 --- a/docs/ref/contrib/comments/index.txt +++ b/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 +`. 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 `. + + More information ================ @@ -342,7 +350,6 @@ More information :maxdepth: 1 models - settings signals custom forms diff --git a/docs/ref/contrib/comments/settings.txt b/docs/ref/contrib/comments/settings.txt deleted file mode 100644 index 1f1aecafd4..0000000000 --- a/docs/ref/contrib/comments/settings.txt +++ /dev/null @@ -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 -`. Use the same dotted-string notation -as in :setting:`INSTALLED_APPS`. Your custom :setting:`COMMENTS_APP` -must also be listed in :setting:`INSTALLED_APPS`. diff --git a/docs/ref/contrib/csrf.txt b/docs/ref/contrib/csrf.txt index 42a41c4bfc..3ad16e2f97 100644 --- a/docs/ref/contrib/csrf.txt +++ b/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` diff --git a/docs/ref/contrib/messages.txt b/docs/ref/contrib/messages.txt index 661d7f2103..40f7d41ceb 100644 --- a/docs/ref/contrib/messages.txt +++ b/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 ` give you control over message +A few :ref:`settings` 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_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 - `. - -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 ` -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` diff --git a/docs/ref/contrib/staticfiles.txt b/docs/ref/contrib/staticfiles.txt index a4a60f239b..a7540388bc 100644 --- a/docs/ref/contrib/staticfiles.txt +++ b/docs/ref/contrib/staticfiles.txt @@ -19,106 +19,14 @@ can easily be served in production. Settings ======== -.. highlight:: python +See :ref:`staticfiles settings ` for details on the +following settings: -.. 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 - - - -.. 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. +* :setting:`STATIC_ROOT` +* :setting:`STATIC_URL` +* :setting:`STATICFILES_DIRS` +* :setting:`STATICFILES_STORAGE` +* :setting:`STATICFILES_FINDERS` Management Commands =================== diff --git a/docs/ref/settings.txt b/docs/ref/settings.txt index ffe8a0fe77..110d5dbdc9 100644 --- a/docs/ref/settings.txt +++ b/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 -` 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 ` for more information. +See the :ref:`cache documentation ` 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 ` 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 ` 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 ` for -more details. - -MESSAGE_STORAGE ---------------- - -Default: ``'django.contrib.messages.storage.fallback.FallbackStorage'`` - -Controls where Django stores message data. See the -:doc:`messages documentation ` 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 ` 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,141 +1479,6 @@ 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 - -SESSION_COOKIE_AGE ------------------- - -Default: ``1209600`` (2 weeks, in seconds) - -The age of session cookies, in seconds. See :doc:`/topics/http/sessions`. - -.. 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"`` for cross-domain cookies, or use ``None`` for a standard -domain cookie. See the :doc:`/topics/http/sessions`. - -.. 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`). -See the :doc:`/topics/http/sessions`. - -.. 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_CACHE_ALIAS - -SESSION_CACHE_ALIAS -------------------- - -Default: ``default`` - -If you're using :ref:`cache-based session storage `, -this selects the cache to use. - -.. 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. -See the :doc:`/topics/http/sessions`. - -.. 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 @@ -1797,71 +1518,6 @@ 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` 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` 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`'s - :setting:`finders`, which by default, are - ``'static/'`` app sub-directories and any directories you include in - :setting:`STATICFILES_DIRS`). - -See :doc:`staticfiles reference` 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` and the -:doc:`staticfiles app`. - -It must end in a slash if set to a non-empty value. - -See :setting:`STATIC_ROOT`. - .. setting:: TEMPLATE_CONTEXT_PROCESSORS TEMPLATE_CONTEXT_PROCESSORS @@ -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 ` 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 +` 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 `. + +.. 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 ` 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 ` 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 +`. 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 ` 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 + `. + +.. 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 ` 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 + `. + +.. _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 `, +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` 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` 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`'s + :setting:`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` and the +:doc:`staticfiles app`. + +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 + + + +.. 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` diff --git a/docs/topics/http/sessions.txt b/docs/topics/http/sessions.txt index 1832a55267..41ae0cafa9 100644 --- a/docs/topics/http/sessions.txt +++ b/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 ` give you control over session +A few :ref:`Django settings ` 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 =================