+
−===============
+
−Django settings
+
−===============
+
−
+
−A Django settings file contains all the configuration of your Django
+
−installation. This document explains how settings work and which settings are
+
−available.
+
−
+
−The basics
+
−==========
+
−
+
−A settings file is just a Python module with module-level variables.
+
−
+
−Here are a couple of example settings::
+
−
+
−    DEBUG = False
+
−    DEFAULT_FROM_EMAIL = 'webmaster@example.com'
+
−    TEMPLATE_DIRS = ('/home/templates/mike', '/home/templates/john')
+
−
+
−Because a settings file is a Python module, the following apply:
+
−
+
−    * It doesn't allow for Python syntax errors.
+
−    * It can assign settings dynamically using normal Python syntax.
+
−      For example::
+
−
+
−          MY_SETTING = [str(i) for i in range(30)]
+
−
+
−    * It can import values from other settings files.
+
−
+
−.. _django-settings-module:
+
−
+
−Designating the settings
+
−========================
+
−
+
−When you use Django, you have to tell it which settings you're using. Do this
+
−by using an environment variable, ``DJANGO_SETTINGS_MODULE``.
+
−
+
−The value of ``DJANGO_SETTINGS_MODULE`` should be in Python path syntax, e.g.
+
−``mysite.settings``. Note that the settings module should be on the
+
−Python `import search path`_.
+
−
+
−.. _import search path: http://diveintopython.org/getting_to_know_python/everything_is_an_object.html
+
−
+
−The django-admin.py utility
+
−---------------------------
+
−
+
−When using :doc:`django-admin.py </ref/django-admin>`, you can either set the
+
−environment variable once, or explicitly pass in the settings module each time
+
−you run the utility.
+
−
+
−Example (Unix Bash shell)::
+
−
+
−    export DJANGO_SETTINGS_MODULE=mysite.settings
+
−    django-admin.py runserver
+
−
+
−Example (Windows shell)::
+
−
+
−    set DJANGO_SETTINGS_MODULE=mysite.settings
+
−    django-admin.py runserver
+
−
+
−Use the ``--settings`` command-line argument to specify the settings manually::
+
−
+
−    django-admin.py runserver --settings=mysite.settings
+
−
+
−.. _django-admin.py: ../django-admin/
+
−
+
−On the server (mod_python)
+
−--------------------------
+
−
+
−In your live server environment, you'll need to tell Apache/mod_python which
+
−settings file to use. Do that with ``SetEnv``::
+
−
+
−    <Location "/mysite/">
+
−        SetHandler python-program
+
−        PythonHandler django.core.handlers.modpython
+
−        SetEnv DJANGO_SETTINGS_MODULE mysite.settings
+
−    </Location>
+
−
+
−Read the :doc:`Django mod_python documentation </howto/deployment/modpython>` for
+
−more information.
+
−
+
−Default settings
+
−================
+
−
+
−A Django settings file doesn't have to define any settings if it doesn't need
+
−to. Each setting has a sensible default value. These defaults live in the
+
−module :file:`django/conf/global_settings.py`.
+
−
+
−Here's the algorithm Django uses in compiling settings:
+
−
+
−    * Load settings from ``global_settings.py``.
+
−    * Load settings from the specified settings file, overriding the global
+
−      settings as necessary.
+
−
+
−Note that a settings file should *not* import from ``global_settings``, because
+
−that's redundant.
+
−
+
−Seeing which settings you've changed
+
−------------------------------------
+
−
+
−There's an easy way to view which of your settings deviate from the default
+
−settings. The command ``python manage.py diffsettings`` displays differences
+
−between the current settings file and Django's default settings.
+
−
+
−For more, see the :djadmin:`diffsettings` documentation.
+
−
+
−Using settings in Python code
+
−=============================
+
−
+
−In your Django apps, use settings by importing the object
+
−``django.conf.settings``. Example::
+
−
+
−    from django.conf import settings
+
−
+
−    if settings.DEBUG:
+
−        # Do something
+
−
+
−Note that ``django.conf.settings`` isn't a module -- it's an object. So
+
−importing individual settings is not possible::
+
−
+
−    from django.conf.settings import DEBUG  # This won't work.
+
−
+
−Also note that your code should *not* import from either ``global_settings`` or
+
−your own settings file. ``django.conf.settings`` abstracts the concepts of
+
−default settings and site-specific settings; it presents a single interface.
+
−It also decouples the code that uses settings from the location of your
+
−settings.
+
−
+
−Altering settings at runtime
+
−============================
+
−
+
−You shouldn't alter settings in your applications at runtime. For example,
+
−don't do this in a view::
+
−
+
−    from django.conf import settings
+
−
+
−    settings.DEBUG = True   # Don't do this!
+
−
+
−The only place you should assign to settings is in a settings file.
+
−
+
−Security
+
−========
+
−
+
−Because a settings file contains sensitive information, such as the database
+
−password, you should make every attempt to limit access to it. For example,
+
−change its file permissions so that only you and your Web server's user can
+
−read it. This is especially important in a shared-hosting environment.
+
−
+
−Available settings
+
−==================
+
−
+
−For a full list of available settings, see the :doc:`settings reference </ref/settings>`.
+
−
+
−Creating your own settings
+
−==========================
+
−
+
−There's nothing stopping you from creating your own settings, for your own
+
−Django apps. Just follow these conventions:
+
−
+
−    * Setting names are in all uppercase.
+
−    * Don't reinvent an already-existing setting.
+
−
+
−For settings that are sequences, Django itself uses tuples, rather than lists,
+
−but this is only a convention.
+
−
+
−.. _settings-without-django-settings-module:
+
−
+
−Using settings without setting DJANGO_SETTINGS_MODULE
+
−=====================================================
+
−
+
−In some cases, you might want to bypass the ``DJANGO_SETTINGS_MODULE``
+
−environment variable. For example, if you're using the template system by
+
−itself, you likely don't want to have to set up an environment variable
+
−pointing to a settings module.
+
−
+
−In these cases, you can configure Django's settings manually. Do this by
+
−calling:
+
−
+
−.. function:: django.conf.settings.configure(default_settings, **settings)
+
−
+
−Example::
+
−
+
−    from django.conf import settings
+
−
+
−    settings.configure(DEBUG=True, TEMPLATE_DEBUG=True,
+
−        TEMPLATE_DIRS=('/home/web-apps/myapp', '/home/web-apps/base'))
+
−
+
−Pass ``configure()`` as many keyword arguments as you'd like, with each keyword
+
−argument representing a setting and its value. Each argument name should be all
+
−uppercase, with the same name as the settings described above. If a particular
+
−setting is not passed to ``configure()`` and is needed at some later point,
+
−Django will use the default setting value.
+
−
+
−Configuring Django in this fashion is mostly necessary -- and, indeed,
+
−recommended -- when you're using a piece of the framework inside a larger
+
−application.
+
−
+
−Consequently, when configured via ``settings.configure()``, Django will not
+
−make any modifications to the process environment variables (see the
+
−documentation of :setting:`TIME_ZONE` for why this would normally occur). It's
+
−assumed that you're already in full control of your environment in these
+
−cases.
+
−
+
−Custom default settings
+
−-----------------------
+
−
+
−If you'd like default values to come from somewhere other than
+
−``django.conf.global_settings``, you can pass in a module or class that
+
−provides the default settings as the ``default_settings`` argument (or as the
+
−first positional argument) in the call to ``configure()``.
+
−
+
−In this example, default settings are taken from ``myapp_defaults``, and the
+
−``DEBUG`` setting is set to ``True``, regardless of its value in
+
−``myapp_defaults``::
+
−
+
−    from django.conf import settings
+
−    from myapp import myapp_defaults
+
−
+
−    settings.configure(default_settings=myapp_defaults, DEBUG=True)
+
−
+
−The following example, which uses ``myapp_defaults`` as a positional argument,
+
−is equivalent::
+
−
+
−    settings.configure(myapp_defaults, DEBUG = True)
+
−
+
−Normally, you will not need to override the defaults in this fashion. The
+
−Django defaults are sufficiently tame that you can safely use them. Be aware
+
−that if you do pass in a new default module, it entirely *replaces* the Django
+
−defaults, so you must specify a value for every possible setting that might be
+
−used in that code you are importing. Check in
+
−``django.conf.settings.global_settings`` for the full list.
+
−
+
−Either configure() or DJANGO_SETTINGS_MODULE is required
+
−--------------------------------------------------------
+
−
+
−If you're not setting the ``DJANGO_SETTINGS_MODULE`` environment variable, you
+
−*must* call ``configure()`` at some point before using any code that reads
+
−settings.
+
−
+
−If you don't set ``DJANGO_SETTINGS_MODULE`` and don't call ``configure()``,
+
−Django will raise an ``ImportError`` exception the first time a setting
+
−is accessed.
+
−
+
−If you set ``DJANGO_SETTINGS_MODULE``, access settings values somehow, *then*
+
−call ``configure()``, Django will raise a ``RuntimeError`` indicating
+
−that settings have already been configured.
+
−
+
−Also, it's an error to call ``configure()`` more than once, or to call
+
−``configure()`` after any setting has been accessed.
+
−
+
−It boils down to this: Use exactly one of either ``configure()`` or
+
−``DJANGO_SETTINGS_MODULE``. Not both, and not neither.
+
−
+
−.. _@login_required: ../authentication/#the-login-required-decorator
+
−