docs/topics/settings.txt

   1 .. _topics-settings:
   2
   3 ===============
   4 Django settings
   5 ===============
   6
   7 A Django settings file contains all the configuration of your Django
   8 installation. This document explains how settings work and which settings are
   9 available.
  10
  11 The basics
  12 ==========
  13
  14 A settings file is just a Python module with module-level variables.
  15
  16 Here are a couple of example settings::
  17
  18     DEBUG = False
  19     DEFAULT_FROM_EMAIL = 'webmaster@example.com'
  20     TEMPLATE_DIRS = ('/home/templates/mike', '/home/templates/john')
  21
  22 Because a settings file is a Python module, the following apply:
  23
  24     * It doesn't allow for Python syntax errors.
  25     * It can assign settings dynamically using normal Python syntax.
  26       For example::
  27
  28           MY_SETTING = [str(i) for i in range(30)]
  29
  30     * It can import values from other settings files.
  31
  32 .. _django-settings-module:
  33
  34 Designating the settings
  35 ========================
  36
  37 When you use Django, you have to tell it which settings you're using. Do this
  38 by using an environment variable, ``DJANGO_SETTINGS_MODULE``.
  39
  40 The value of ``DJANGO_SETTINGS_MODULE`` should be in Python path syntax, e.g.
  41 ``mysite.settings``. Note that the settings module should be on the
  42 Python `import search path`_.
  43
  44 .. _import search path: http://diveintopython.org/getting_to_know_python/everything_is_an_object.html
  45
  46 The django-admin.py utility
  47 ---------------------------
  48
  49 When using :ref:`django-admin.py <ref-django-admin>`, you can either set the
  50 environment variable once, or explicitly pass in the settings module each time
  51 you run the utility.
  52
  53 Example (Unix Bash shell)::
  54
  55     export DJANGO_SETTINGS_MODULE=mysite.settings
  56     django-admin.py runserver
  57
  58 Example (Windows shell)::
  59
  60     set DJANGO_SETTINGS_MODULE=mysite.settings
  61     django-admin.py runserver
  62
  63 Use the ``--settings`` command-line argument to specify the settings manually::
  64
  65     django-admin.py runserver --settings=mysite.settings
  66
  67 .. _django-admin.py: ../django-admin/
  68
  69 On the server (mod_python)
  70 --------------------------
  71
  72 In your live server environment, you'll need to tell Apache/mod_python which
  73 settings file to use. Do that with ``SetEnv``::
  74
  75     <Location "/mysite/">
  76         SetHandler python-program
  77         PythonHandler django.core.handlers.modpython
  78         SetEnv DJANGO_SETTINGS_MODULE mysite.settings
  79     </Location>
  80
  81 Read the :ref:`Django mod_python documentation <howto-deployment-modpython>` for
  82 more information.
  83
  84 Default settings
  85 ================
  86
  87 A Django settings file doesn't have to define any settings if it doesn't need
  88 to. Each setting has a sensible default value. These defaults live in the
  89 module :file:`django/conf/global_settings.py`.
  90
  91 Here's the algorithm Django uses in compiling settings:
  92
  93     * Load settings from ``global_settings.py``.
  94     * Load settings from the specified settings file, overriding the global
  95       settings as necessary.
  96
  97 Note that a settings file should *not* import from ``global_settings``, because
  98 that's redundant.
  99
 100 Seeing which settings you've changed
 101 ------------------------------------
 102
 103 There's an easy way to view which of your settings deviate from the default
 104 settings. The command ``python manage.py diffsettings`` displays differences
 105 between the current settings file and Django's default settings.
 106
 107 For more, see the :djadmin:`diffsettings` documentation.
 108
 109 Using settings in Python code
 110 =============================
 111
 112 In your Django apps, use settings by importing the object
 113 ``django.conf.settings``. Example::
 114
 115     from django.conf import settings
 116
 117     if settings.DEBUG:
 118         # Do something
 119
 120 Note that ``django.conf.settings`` isn't a module -- it's an object. So
 121 importing individual settings is not possible::
 122
 123     from django.conf.settings import DEBUG  # This won't work.
 124
 125 Also note that your code should *not* import from either ``global_settings`` or
 126 your own settings file. ``django.conf.settings`` abstracts the concepts of
 127 default settings and site-specific settings; it presents a single interface.
 128 It also decouples the code that uses settings from the location of your
 129 settings.
 130
 131 Altering settings at runtime
 132 ============================
 133
 134 You shouldn't alter settings in your applications at runtime. For example,
 135 don't do this in a view::
 136
 137     from django.conf import settings
 138
 139     settings.DEBUG = True   # Don't do this!
 140
 141 The only place you should assign to settings is in a settings file.
 142
 143 Security
 144 ========
 145
 146 Because a settings file contains sensitive information, such as the database
 147 password, you should make every attempt to limit access to it. For example,
 148 change its file permissions so that only you and your Web server's user can
 149 read it. This is especially important in a shared-hosting environment.
 150
 151 Available settings
 152 ==================
 153
 154 For a full list of available settings, see the :ref:`settings reference <ref-settings>`.
 155
 156 Creating your own settings
 157 ==========================
 158
 159 There's nothing stopping you from creating your own settings, for your own
 160 Django apps. Just follow these conventions:
 161
 162     * Setting names are in all uppercase.
 163     * Don't reinvent an already-existing setting.
 164
 165 For settings that are sequences, Django itself uses tuples, rather than lists,
 166 but this is only a convention.
 167
 168 .. _settings-without-django-settings-module:
 169
 170 Using settings without setting DJANGO_SETTINGS_MODULE
 171 =====================================================
 172
 173 In some cases, you might want to bypass the ``DJANGO_SETTINGS_MODULE``
 174 environment variable. For example, if you're using the template system by
 175 itself, you likely don't want to have to set up an environment variable
 176 pointing to a settings module.
 177
 178 In these cases, you can configure Django's settings manually. Do this by
 179 calling:
 180
 181 .. function:: django.conf.settings.configure(default_settings, **settings)
 182
 183 Example::
 184
 185     from django.conf import settings
 186
 187     settings.configure(DEBUG=True, TEMPLATE_DEBUG=True,
 188         TEMPLATE_DIRS=('/home/web-apps/myapp', '/home/web-apps/base'))
 189
 190 Pass ``configure()`` as many keyword arguments as you'd like, with each keyword
 191 argument representing a setting and its value. Each argument name should be all
 192 uppercase, with the same name as the settings described above. If a particular
 193 setting is not passed to ``configure()`` and is needed at some later point,
 194 Django will use the default setting value.
 195
 196 Configuring Django in this fashion is mostly necessary -- and, indeed,
 197 recommended -- when you're using a piece of the framework inside a larger
 198 application.
 199
 200 Consequently, when configured via ``settings.configure()``, Django will not
 201 make any modifications to the process environment variables (see the
 202 documentation of :setting:`TIME_ZONE` for why this would normally occur). It's
 203 assumed that you're already in full control of your environment in these
 204 cases.
 205
 206 Custom default settings
 207 -----------------------
 208
 209 If you'd like default values to come from somewhere other than
 210 ``django.conf.global_settings``, you can pass in a module or class that
 211 provides the default settings as the ``default_settings`` argument (or as the
 212 first positional argument) in the call to ``configure()``.
 213
 214 In this example, default settings are taken from ``myapp_defaults``, and the
 215 ``DEBUG`` setting is set to ``True``, regardless of its value in
 216 ``myapp_defaults``::
 217
 218     from django.conf import settings
 219     from myapp import myapp_defaults
 220
 221     settings.configure(default_settings=myapp_defaults, DEBUG=True)
 222
 223 The following example, which uses ``myapp_defaults`` as a positional argument,
 224 is equivalent::
 225
 226     settings.configure(myapp_defaults, DEBUG = True)
 227
 228 Normally, you will not need to override the defaults in this fashion. The
 229 Django defaults are sufficiently tame that you can safely use them. Be aware
 230 that if you do pass in a new default module, it entirely *replaces* the Django
 231 defaults, so you must specify a value for every possible setting that might be
 232 used in that code you are importing. Check in
 233 ``django.conf.settings.global_settings`` for the full list.
 234
 235 Either configure() or DJANGO_SETTINGS_MODULE is required
 236 --------------------------------------------------------
 237
 238 If you're not setting the ``DJANGO_SETTINGS_MODULE`` environment variable, you
 239 *must* call ``configure()`` at some point before using any code that reads
 240 settings.
 241
 242 If you don't set ``DJANGO_SETTINGS_MODULE`` and don't call ``configure()``,
 243 Django will raise an ``ImportError`` exception the first time a setting
 244 is accessed.
 245
 246 If you set ``DJANGO_SETTINGS_MODULE``, access settings values somehow, *then*
 247 call ``configure()``, Django will raise a ``RuntimeError`` indicating
 248 that settings have already been configured.
 249
 250 Also, it's an error to call ``configure()`` more than once, or to call
 251 ``configure()`` after any setting has been accessed.
 252
 253 It boils down to this: Use exactly one of either ``configure()`` or
 254 ``DJANGO_SETTINGS_MODULE``. Not both, and not neither.
 255
 256 .. _@login_required: ../authentication/#the-login-required-decorator
 257