diff options
Diffstat (limited to 'docs/ref/settings.txt')
| -rw-r--r-- | docs/ref/settings.txt | 291 |
1 files changed, 167 insertions, 124 deletions
diff --git a/docs/ref/settings.txt b/docs/ref/settings.txt index 58f87b9cf4..b5556deac8 100644 --- a/docs/ref/settings.txt +++ b/docs/ref/settings.txt @@ -1,5 +1,3 @@ -.. _ref-settings: - ======== Settings ======== @@ -74,7 +72,7 @@ of (Full name, e-mail address). Example:: (('John', 'john@example.com'), ('Mary', 'mary@example.com')) Note that Django will e-mail *all* of these people whenever an error happens. -See :ref:`howto-error-reporting` for more information. +See :doc:`/howto/error-reporting` for more information. .. setting:: ALLOWED_INCLUDE_ROOTS @@ -99,7 +97,7 @@ APPEND_SLASH Default: ``True`` Whether to append trailing slashes to URLs. This is only used if -``CommonMiddleware`` is installed (see :ref:`topics-http-middleware`). See also +``CommonMiddleware`` is installed (see :doc:`/topics/http/middleware`). See also ``PREPEND_WWW``. .. setting:: AUTHENTICATION_BACKENDS @@ -110,8 +108,8 @@ 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. +authenticate a user. See the :doc:`authentication backends documentation +</ref/authbackends>` for details. .. setting:: AUTH_PROFILE_MODULE @@ -130,7 +128,23 @@ CACHE_BACKEND Default: ``'locmem://'`` -The cache backend to use. See :ref:`topics-cache`. +The cache backend to use. See :doc:`/topics/cache`. + +.. setting:: CACHE_MIDDLEWARE_ANONYMOUS_ONLY + +CACHE_MIDDLEWARE_ANONYMOUS_ONLY +------------------------------- + +Default: ``False`` + +If the value of this setting is ``True``, only anonymous requests (i.e., not +those made by a logged-in user) will be cached. Otherwise, the middleware +caches every page that doesn't have GET or POST parameters. + +If you set the value of this setting to ``True``, you should make sure you've +activated ``AuthenticationMiddleware``. + +See the :doc:`cache documentation </topics/cache>` for more information. .. setting:: CACHE_MIDDLEWARE_KEY_PREFIX @@ -140,7 +154,7 @@ CACHE_MIDDLEWARE_KEY_PREFIX Default: ``''`` (Empty string) The cache key prefix that the cache middleware should use. See -:ref:`topics-cache`. +:doc:`/topics/cache`. .. setting:: CACHE_MIDDLEWARE_SECONDS @@ -152,18 +166,6 @@ Default: ``600`` The default number of seconds to cache a page when the caching middleware or ``cache_page()`` decorator is used. -.. setting:: CSRF_COOKIE_NAME - -CSRF_COOKIE_NAME ----------------- - -.. versionadded:: 1.2 - -Default: ``'csrftoken'`` - -The name of the cookie to use for the CSRF authentication token. This can be whatever you -want. See :ref:`ref-contrib-csrf`. - .. setting:: CSRF_COOKIE_DOMAIN CSRF_COOKIE_DOMAIN @@ -179,6 +181,18 @@ request forgery protection. It should be set to a string such as ``".lawrence.com"`` to allow a POST request from a form on one subdomain to be accepted by accepted by a view served from another subdomain. +.. setting:: CSRF_COOKIE_NAME + +CSRF_COOKIE_NAME +---------------- + +.. versionadded:: 1.2 + +Default: ``'csrftoken'`` + +The name of the cookie to use for the CSRF authentication token. This can be whatever you +want. See :doc:`/ref/contrib/csrf`. + .. setting:: CSRF_FAILURE_VIEW CSRF_FAILURE_VIEW @@ -195,7 +209,7 @@ is rejected by the CSRF protection. The function should have this signature:: where ``reason`` is a short message (intended for developers or logging, not for end users) indicating the reason the request was rejected. See -:ref:`ref-contrib-csrf`. +:doc:`/ref/contrib/csrf`. .. setting:: DATABASES @@ -208,7 +222,7 @@ DATABASES Default: ``{}`` (Empty dictionary) A dictionary containing the settings for all databases to be used with -Django. It is a nested dictionary who's contents maps database aliases +Django. It is a nested dictionary whose contents maps database aliases to a dictionary containing the options for an individual database. The :setting:`DATABASES` setting must configure a ``default`` database; @@ -385,8 +399,19 @@ If the default value (``None``) is used with the SQLite database engine, the tests will use a memory resident database. For all other database engines the test database will use the name ``'test_' + DATABASE_NAME``. -See :ref:`topics-testing`. +See :doc:`/topics/testing`. +.. setting:: TEST_USER + +TEST_USER +~~~~~~~~~ + +Default: ``None`` + +This is an Oracle-specific setting. + +The username to use when connecting to the Oracle database that will be used +when running tests. .. setting:: DATABASE_ROUTERS @@ -441,7 +466,7 @@ to be displayed. See also ``DATETIME_INPUT_FORMATS`` and ``TIME_INPUT_FORMATS``. -.. _datetime: http://docs.python.org/library/datetime.html#strftime-behavior +.. _datetime: http://docs.python.org/library/datetime.html#strftime-strptime-behavior .. setting:: DATETIME_FORMAT @@ -481,7 +506,7 @@ to be displayed. See also ``DATE_INPUT_FORMATS`` and ``TIME_INPUT_FORMATS``. -.. _datetime: http://docs.python.org/library/datetime.html#strftime-behavior +.. _datetime: http://docs.python.org/library/datetime.html#strftime-strptime-behavior .. setting:: DEBUG @@ -494,8 +519,9 @@ A boolean that turns on/off debug mode. If you define custom settings, `django/views/debug.py`_ has a ``HIDDEN_SETTINGS`` regular expression which will hide from the DEBUG view anything that contains -``'SECRET'``, ``'PASSWORD'``, or ``'PROFANITIES'``. This allows untrusted users to -be able to give backtraces without seeing sensitive (or offensive) settings. +``'SECRET'``, ``'PASSWORD'``, ``'PROFANITIES'``, or ``'SIGNATURE'``. This allows +untrusted users to be able to give backtraces without seeing sensitive (or +offensive) settings. Still, note that there are always going to be sections of your debug output that are inappropriate for public consumption. File paths, configuration options, and @@ -554,7 +580,7 @@ Default content type to use for all ``HttpResponse`` objects, if a MIME type isn't manually specified. Used with ``DEFAULT_CHARSET`` to construct the ``Content-Type`` header. -.. setting:: DEFAULT_FROM_EMAIL +.. setting:: DEFAULT_FILE_STORAGE DEFAULT_FILE_STORAGE -------------------- @@ -562,7 +588,9 @@ DEFAULT_FILE_STORAGE Default: ``'django.core.files.storage.FileSystemStorage'`` Default file storage class to be used for any file-related operations that don't -specify a particular storage system. See :ref:`topics-files`. +specify a particular storage system. See :doc:`/topics/files`. + +.. setting:: DEFAULT_FROM_EMAIL DEFAULT_FROM_EMAIL ------------------ @@ -572,29 +600,29 @@ Default: ``'webmaster@localhost'`` Default e-mail address to use for various automated correspondence from the site manager(s). -.. setting:: DEFAULT_TABLESPACE +.. setting:: DEFAULT_INDEX_TABLESPACE -DEFAULT_TABLESPACE ------------------- +DEFAULT_INDEX_TABLESPACE +------------------------ .. versionadded:: 1.0 Default: ``''`` (Empty string) -Default tablespace to use for models that don't specify one, if the -backend supports it. +Default tablespace to use for indexes on fields that don't specify +one, if the backend supports it. -.. setting:: DEFAULT_INDEX_TABLESPACE +.. setting:: DEFAULT_TABLESPACE -DEFAULT_INDEX_TABLESPACE ------------------------- +DEFAULT_TABLESPACE +------------------ .. versionadded:: 1.0 Default: ``''`` (Empty string) -Default tablespace to use for indexes on fields that don't specify -one, if the backend supports it. +Default tablespace to use for models that don't specify one, if the +backend supports it. .. setting:: DISALLOWED_USER_AGENTS @@ -606,7 +634,7 @@ Default: ``()`` (Empty tuple) List of compiled regular expression objects representing User-Agent strings that are not allowed to visit any page, systemwide. Use this for bad robots/crawlers. This is only used if ``CommonMiddleware`` is installed (see -:ref:`topics-http-middleware`). +:doc:`/topics/http/middleware`). .. setting:: EMAIL_BACKEND @@ -615,10 +643,10 @@ EMAIL_BACKEND .. versionadded:: 1.2 -Default: ``'django.core.mail.backends.smtp'`` +Default: ``'django.core.mail.backends.smtp.EmailBackend'`` The backend to use for sending emails. For the list of available backends see -:ref:`topics-email`. +:doc:`/topics/email`. .. setting:: EMAIL_FILE_PATH @@ -723,7 +751,7 @@ Default:: ("django.core.files.uploadhandler.MemoryFileUploadHandler", "django.core.files.uploadhandler.TemporaryFileUploadHandler",) -A tuple of handlers to use for uploading. See :ref:`topics-files` for details. +A tuple of handlers to use for uploading. See :doc:`/topics/files` for details. .. setting:: FILE_UPLOAD_MAX_MEMORY_SIZE @@ -735,22 +763,7 @@ FILE_UPLOAD_MAX_MEMORY_SIZE Default: ``2621440`` (i.e. 2.5 MB). The maximum size (in bytes) that an upload will be before it gets streamed to -the file system. See :ref:`topics-files` for details. - -.. setting:: FILE_UPLOAD_TEMP_DIR - -FILE_UPLOAD_TEMP_DIR --------------------- - -.. versionadded:: 1.0 - -Default: ``None`` - -The directory to store data temporarily while uploading files. If ``None``, -Django will use the standard temporary directory for the operating system. For -example, this will default to '/tmp' on \*nix-style operating systems. - -See :ref:`topics-files` for details. +the file system. See :doc:`/topics/files` for details. .. setting:: FILE_UPLOAD_PERMISSIONS @@ -780,6 +793,21 @@ system's standard umask. .. _documentation for os.chmod: http://docs.python.org/library/os.html#os.chmod +.. setting:: FILE_UPLOAD_TEMP_DIR + +FILE_UPLOAD_TEMP_DIR +-------------------- + +.. versionadded:: 1.0 + +Default: ``None`` + +The directory to store data temporarily while uploading files. If ``None``, +Django will use the standard temporary directory for the operating system. For +example, this will default to '/tmp' on \*nix-style operating systems. + +See :doc:`/topics/files` for details. + .. setting:: FIRST_DAY_OF_WEEK FIRST_DAY_OF_WEEK @@ -806,7 +834,7 @@ Default: ``()`` (Empty tuple) List of locations of the fixture data files, in search order. Note that these paths should use Unix-style forward slashes, even on Windows. See -:ref:`topics-testing`. +:doc:`/topics/testing`. FORCE_SCRIPT_NAME ------------------ @@ -866,7 +894,7 @@ Default: ``('/cgi-bin/', '/_vti_bin', '/_vti_inf')`` A tuple of strings that specify beginnings of URLs that should be ignored by the 404 e-mailer. See ``SEND_BROKEN_LINK_EMAILS``, ``IGNORABLE_404_ENDS`` and -the :ref:`howto-error-reporting`. +the :doc:`/howto/error-reporting`. .. setting:: INSTALLED_APPS @@ -899,7 +927,7 @@ A tuple of IP addresses, as strings, that: * See debug comments, when ``DEBUG`` is ``True`` * Receive X headers if the ``XViewMiddleware`` is installed (see - :ref:`topics-http-middleware`) + :doc:`/topics/http/middleware`) .. setting:: LANGUAGE_CODE @@ -910,7 +938,7 @@ Default: ``'en-us'`` A string representing the language code for this installation. This should be in standard :term:`language format<language code>`. For example, U.S. English is -``"en-us"``. See :ref:`topics-i18n`. +``"en-us"``. See :doc:`/topics/i18n/index`. .. setting:: LANGUAGE_COOKIE_NAME @@ -923,7 +951,7 @@ Default: ``'django_language'`` The name of the cookie to use for the language cookie. This can be whatever you want (but should be different from ``SESSION_COOKIE_NAME``). See -:ref:`topics-i18n`. +:doc:`/topics/i18n/index`. .. setting:: LANGUAGES @@ -941,7 +969,7 @@ The list is a tuple of two-tuples in the format ``(language code, language name)``, the ``language code`` part should be a :term:`language name<language code>` -- for example, ``('ja', 'Japanese')``. This specifies which languages are available for language selection. See -:ref:`topics-i18n`. +:doc:`/topics/i18n/index`. Generally, the default value should suffice. Only set this setting if you want to restrict language selection to a subset of the Django-provided languages. @@ -1061,7 +1089,7 @@ MESSAGE_LEVEL Default: `messages.INFO` Sets the minimum message level that will be recorded by the messages -framework. See the :ref:`messages documentation <ref-contrib-messages>` for +framework. See the :doc:`messages documentation </ref/contrib/messages>` for more details. MESSAGE_STORAGE @@ -1072,7 +1100,7 @@ MESSAGE_STORAGE Default: ``'django.contrib.messages.storage.user_messages.LegacyFallbackStorage'`` Controls where Django stores message data. See the -:ref:`messages documentation <ref-contrib-messages>` for more details. +:doc:`messages documentation </ref/contrib/messages>` for more details. MESSAGE_TAGS ------------ @@ -1088,7 +1116,7 @@ Default:: messages.ERROR: 'error',} Sets the mapping of message levels to message tags. See the -:ref:`messages documentation <ref-contrib-messages>` for more details. +:doc:`messages documentation </ref/contrib/messages>` for more details. MIDDLEWARE_CLASSES ------------------ @@ -1101,12 +1129,12 @@ Default:: 'django.contrib.auth.middleware.AuthenticationMiddleware', 'django.contrib.messages.middleware.MessageMiddleware',) -A tuple of middleware classes to use. See :ref:`topics-http-middleware`. +A tuple of middleware classes to use. See :doc:`/topics/http/middleware`. .. versionchanged:: 1.2 ``'django.contrib.messages.middleware.MessageMiddleware'`` was added to the - default. For more information, see the :ref:`messages documentation - <ref-contrib-messages>`. + default. For more information, see the :doc:`messages documentation + </ref/contrib/messages>`. .. setting:: MONTH_DAY_FORMAT @@ -1152,7 +1180,7 @@ PREPEND_WWW Default: ``False`` Whether to prepend the "www." subdomain to URLs that don't have it. This is only -used if ``CommonMiddleware`` is installed (see :ref:`topics-http-middleware`). +used if ``CommonMiddleware`` is installed (see :doc:`/topics/http/middleware`). See also ``APPEND_SLASH``. .. setting:: PROFANITIES_LIST @@ -1167,6 +1195,21 @@ We don't list the default values here, because that would be profane. To see the default values, see the file `django/conf/global_settings.py`_. .. _django/conf/global_settings.py: http://code.djangoproject.com/browser/django/trunk/django/conf/global_settings.py + +.. setting:: RESTRUCTUREDTEXT_FILTER_SETTINGS + +RESTRUCTUREDTEXT_FILTER_SETTINGS +-------------------------------- + +Default: ``{}`` + +A dictionary containing settings for the ``restructuredtext`` markup filter from +the :doc:`django.contrib.markup application </ref/contrib/markup>`. They override +the default writer settings. See the Docutils restructuredtext `writer settings +docs`_ for details. + +.. _writer settings docs: http://docutils.sourceforge.net/docs/user/config.html#html4css1-writer + .. setting:: ROOT_URLCONF ROOT_URLCONF @@ -1200,8 +1243,8 @@ Default: ``False`` Whether to send an e-mail to the ``MANAGERS`` each time somebody visits a Django-powered page that is 404ed with a non-empty referer (i.e., a broken link). This is only used if ``CommonMiddleware`` is installed (see -:ref:`topics-http-middleware`. See also ``IGNORABLE_404_STARTS``, -``IGNORABLE_404_ENDS`` and :ref:`howto-error-reporting`. +:doc:`/topics/http/middleware`. See also ``IGNORABLE_404_STARTS``, +``IGNORABLE_404_ENDS`` and :doc:`/howto/error-reporting`. .. setting:: SERIALIZATION_MODULES @@ -1226,27 +1269,6 @@ Default: ``'root@localhost'`` The e-mail address that error messages come from, such as those sent to ``ADMINS`` and ``MANAGERS``. -.. setting:: SESSION_ENGINE - -SESSION_ENGINE --------------- - -.. versionadded:: 1.0 - -.. versionchanged:: 1.1 - The ``cached_db`` backend was added - -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'`` - -See :ref:`topics-http-sessions`. - .. setting:: SESSION_COOKIE_AGE SESSION_COOKIE_AGE @@ -1254,7 +1276,7 @@ SESSION_COOKIE_AGE Default: ``1209600`` (2 weeks, in seconds) -The age of session cookies, in seconds. See :ref:`topics-http-sessions`. +The age of session cookies, in seconds. See :doc:`/topics/http/sessions`. .. setting:: SESSION_COOKIE_DOMAIN @@ -1265,7 +1287,7 @@ Default: ``None`` The domain to use for session cookies. Set this to a string such as ``".lawrence.com"`` for cross-domain cookies, or use ``None`` for a standard -domain cookie. See the :ref:`topics-http-sessions`. +domain cookie. See the :doc:`/topics/http/sessions`. .. setting:: SESSION_COOKIE_NAME @@ -1275,7 +1297,7 @@ 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 ``LANGUAGE_COOKIE_NAME``). See the :ref:`topics-http-sessions`. +should be different from ``LANGUAGE_COOKIE_NAME``). See the :doc:`/topics/http/sessions`. .. setting:: SESSION_COOKIE_PATH @@ -1303,7 +1325,28 @@ 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 :ref:`topics-http-sessions`. +See the :doc:`/topics/http/sessions`. + +.. setting:: SESSION_ENGINE + +SESSION_ENGINE +-------------- + +.. versionadded:: 1.0 + +.. versionchanged:: 1.1 + The ``cached_db`` backend was added + +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'`` + +See :doc:`/topics/http/sessions`. .. setting:: SESSION_EXPIRE_AT_BROWSER_CLOSE @@ -1313,7 +1356,7 @@ SESSION_EXPIRE_AT_BROWSER_CLOSE Default: ``False`` Whether to expire the session when the user closes his or her browser. -See the :ref:`topics-http-sessions`. +See the :doc:`/topics/http/sessions`. .. setting:: SESSION_FILE_PATH @@ -1325,7 +1368,7 @@ 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 :ref:`topics-http-sessions`. When +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. @@ -1337,7 +1380,7 @@ SESSION_SAVE_EVERY_REQUEST Default: ``False`` Whether to save the session data on every request. See -:ref:`topics-http-sessions`. +:doc:`/topics/http/sessions`. .. setting:: SHORT_DATE_FORMAT @@ -1382,7 +1425,7 @@ 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 :ref:`ref-contrib-sites`. +See :doc:`/ref/contrib/sites`. .. _site framework docs: ../sites/ @@ -1405,8 +1448,8 @@ of items to be merged into the context. .. versionchanged:: 1.2 ``"django.contrib.messages.context_processors.messages"`` was added to the - default. For more information, see the :ref:`messages documentation - <ref-contrib-messages>`. + default. For more information, see the :doc:`messages documentation + </ref/contrib/messages>`. .. versionchanged:: 1.2 The auth context processor was moved in this release from its old location @@ -1440,7 +1483,7 @@ Default: ``()`` (Empty tuple) List of locations of the template source files, in search order. Note that these paths should use Unix-style forward slashes, even on Windows. -See :ref:`topics-templates`.. +See :doc:`/topics/templates`. .. setting:: TEMPLATE_LOADERS @@ -1456,7 +1499,7 @@ A tuple of template loader classes, specified as strings. Each ``Loader`` class knows how to import templates from a particular source. Optionally, a tuple can be used instead of a string. The first item in the tuple should be the ``Loader``'s module, subsequent items are passed to the ``Loader`` during initialization. See -:ref:`ref-templates-api`. +:doc:`/ref/templates/api`. .. setting:: TEMPLATE_STRING_IF_INVALID @@ -1479,7 +1522,7 @@ Default: ``'django.test.simple.DjangoTestSuiteRunner'`` Prior to 1.2, test runners were a function, not a class. The name of the class to use for starting the test suite. See -:ref:`topics-testing`. +:doc:`/topics/testing`. .. _Testing Django Applications: ../testing/ @@ -1531,7 +1574,7 @@ to be displayed. See also ``DATE_INPUT_FORMATS`` and ``DATETIME_INPUT_FORMATS``. -.. _datetime: http://docs.python.org/library/datetime.html#strftime-behavior +.. _datetime: http://docs.python.org/library/datetime.html#strftime-strptime-behavior .. setting:: TIME_ZONE @@ -1598,7 +1641,21 @@ Default: ``False`` A boolean that specifies whether to output the "Etag" header. This saves bandwidth but slows down performance. This is only used if ``CommonMiddleware`` -is installed (see :ref:`topics-http-middleware`). +is installed (see :doc:`/topics/http/middleware`). + +.. setting:: USE_I18N + +USE_I18N +-------- + +Default: ``True`` + +A boolean that specifies whether Django's internationalization system should be +enabled. This provides an easy way to turn it off, for performance. If this is +set to ``False``, Django will make some optimizations so as not to load the +internationalization machinery. + +See also ``USE_L10N`` .. setting:: USE_L10N @@ -1615,20 +1672,6 @@ format of the current locale. See also ``USE_I18N`` and ``LANGUAGE_CODE`` -.. setting:: USE_I18N - -USE_I18N --------- - -Default: ``True`` - -A boolean that specifies whether Django's internationalization system should be -enabled. This provides an easy way to turn it off, for performance. If this is -set to ``False``, Django will make some optimizations so as not to load the -internationalization machinery. - -See also ``USE_L10N`` - .. setting:: USE_THOUSAND_SEPARATOR USE_THOUSAND_SEPARATOR |