mirror of
https://github.com/django/django.git
synced 2024-12-23 01:25:58 +00:00
Fixed #14633 - Organized settings reference docs and added a topical index.
Thanks Gabriel Hurley for the original idea and adamv for the draft patch.
This commit is contained in:
Tim Graham
parent
0171ba65db
commit
ba50d3e05b
@ -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
|
||||
|
||||
@ -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`.
|
||||
@ -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`
|
||||
|
||||
@ -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>`
|
||||
|
||||
@ -19,106 +19,14 @@ can easily be served in production.
|
||||
Settings
|
||||
========
|
||||
|
||||
.. highlight:: python
|
||||
See :ref:`staticfiles settings <settings-staticfiles>` 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
|
||||
|
||||
<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.
|
||||
* :setting:`STATIC_ROOT`
|
||||
* :setting:`STATIC_URL`
|
||||
* :setting:`STATICFILES_DIRS`
|
||||
* :setting:`STATICFILES_STORAGE`
|
||||
* :setting:`STATICFILES_FINDERS`
|
||||
|
||||
Management Commands
|
||||
===================
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -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
|
||||
=================
|
||||
|
||||
Loading…
Reference in New Issue
Block a user