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