summaryrefslogtreecommitdiff
path: root/parts/django/docs/topics/settings.txt
diff options
context:
space:
mode:
Diffstat (limited to 'parts/django/docs/topics/settings.txt')
-rw-r--r--parts/django/docs/topics/settings.txt255
1 files changed, 0 insertions, 255 deletions
diff --git a/parts/django/docs/topics/settings.txt b/parts/django/docs/topics/settings.txt
deleted file mode 100644
index 59c02c3..0000000
--- a/parts/django/docs/topics/settings.txt
+++ /dev/null
@@ -1,255 +0,0 @@
-===============
-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
-