Index: django/conf/__init__.py =================================================================== --- django/conf/__init__.py (revision 2908) +++ django/conf/__init__.py (working copy) @@ -12,6 +12,60 @@ ENVIRONMENT_VARIABLE = "DJANGO_SETTINGS_MODULE" +class LazySettings: + """ + A lazy proxy for either global django settings or a custom settings object. + The user can manually configure settings prior to using them, otherwise the + standard settings, pointed to by DJANGO_SETTINGS_MODULE. + """ + def __init__(self): + # _target must be either None or something that supports attribute + # access (getattr, hasattr, etc). + self._target = None + + def __getattr__(self, name): + if self._target is None: + self._import_settings() + if name == '__members__': + # Used to implement dir(obj), for example. + return self._target.get_all_members() + return getattr(self._target, name) + + def __setattr__(self, name, value): + if name == '_target': + self.__dict__['_target'] = value + else: + setattr(self._target, name, value) + + def _import_settings(self): + """ + Load the settings module pointed to by the environment variable. This + is used the first time we need any settings at all, if the user has not + previously configured the settings manually. + """ + try: + settings_module = os.environ[ENVIRONMENT_VARIABLE] + if not settings_module: # If it's set but is an empty string. + raise KeyError + except KeyError: + raise EnvironmentError, "Environment variable %s is undefined." % ENVIRONMENT_VARIABLE + + self._target = Settings(settings_module) + + def configure(self, default_settings = global_settings, **options): + """ + Called to manually configure the settings. The 'default_settings' + parameter sets where to retrieve any unspecified values from (its + argument must support attribute access (__getattr__). + """ + if self._target != None: + raise EnvironmentError('Settings already configured.') + holder = UserSettingsHolder(default_settings) + for name, value in options.items(): + setattr(holder, name, value) + self._target = holder + + class Settings: def __init__(self, settings_module): @@ -56,17 +110,32 @@ # move the time zone info into os.environ os.environ['TZ'] = self.TIME_ZONE -# try to load DJANGO_SETTINGS_MODULE -try: - settings_module = os.environ[ENVIRONMENT_VARIABLE] - if not settings_module: # If it's set but is an empty string. - raise KeyError -except KeyError: - raise EnvironmentError, "Environment variable %s is undefined." % ENVIRONMENT_VARIABLE + def get_all_members(self): + return dir(self) -# instantiate the configuration object -settings = Settings(settings_module) +class UserSettingsHolder: + """ + Holder for user configured settings. + """ + # SETTINGS_MODULE does not really make sense in the manually configured + # (standalone) case. + SETTINGS_MODULE = None + def __init__(self, default_settings): + """ + Requests for configuration variables not in this class are satisfied + from the module specified in default_settings (if possible). + """ + self.default_settings = default_settings + + def __getattr__(self, name): + return getattr(self.default_settings, name) + + def get_all_members(self): + return dir(self) + dir(self.default_settings) + +settings = LazySettings() + # install the translation machinery so that it is available from django.utils import translation translation.install() Index: django/utils/translation.py =================================================================== --- django/utils/translation.py (revision 2908) +++ django/utils/translation.py (working copy) @@ -117,9 +117,12 @@ globalpath = os.path.join(os.path.dirname(sys.modules[settings.__module__].__file__), 'locale') - parts = settings.SETTINGS_MODULE.split('.') - project = __import__(parts[0], {}, {}, []) - projectpath = os.path.join(os.path.dirname(project.__file__), 'locale') + if settings.SETTINGS_MODULE is not None: + parts = settings.SETTINGS_MODULE.split('.') + project = __import__(parts[0], {}, {}, []) + projectpath = os.path.join(os.path.dirname(project.__file__), 'locale') + else: + projectpath = None def _fetch(lang, fallback=None): @@ -155,7 +158,7 @@ if os.path.isdir(localepath): res = _merge(localepath) - if os.path.isdir(projectpath): + if projectpath and os.path.isdir(projectpath): res = _merge(projectpath) for appname in settings.INSTALLED_APPS: Index: django/template/defaultfilters.py =================================================================== --- django/template/defaultfilters.py (revision 2908) +++ django/template/defaultfilters.py (working copy) @@ -327,14 +327,18 @@ # DATES # ################### -def date(value, arg=settings.DATE_FORMAT): +def date(value, arg = None): "Formats a date according to the given format" from django.utils.dateformat import format + if arg is None: + arg = settings.DATE_FORMAT return format(value, arg) -def time(value, arg=settings.TIME_FORMAT): +def time(value, arg = None): "Formats a time according to the given format" from django.utils.dateformat import time_format + if arg is None: + arg = settings.TIME_FORMAT return time_format(value, arg) def timesince(value): Index: tests/othertests/templates.py =================================================================== --- tests/othertests/templates.py (revision 2908) +++ tests/othertests/templates.py (working copy) @@ -507,4 +507,5 @@ raise Exception, msg if __name__ == "__main__": + settings.configure() run_tests(1, True) Index: tests/runtests.py =================================================================== --- tests/runtests.py (revision 2908) +++ tests/runtests.py (working copy) @@ -73,6 +73,10 @@ def run_tests(self): from django.conf import settings + # An empty access of the settings to force the default options to be + # installed prior to assigning to them. + settings.INSTALLED_APPS + # Manually set INSTALLED_APPS to point to the test models. settings.INSTALLED_APPS = [MODEL_TESTS_DIR_NAME + '.' + a for a in get_test_models()] Index: docs/settings.txt =================================================================== --- docs/settings.txt (revision 2908) +++ docs/settings.txt (working copy) @@ -724,3 +724,64 @@ * For settings that are sequences, use tuples instead of lists. This is purely for performance. * Don't reinvent an already-existing setting. + +Using settings without the DJANGO_SETTINGS_MODULE environment variable +======================================================================= + +In some very special circumstances, it is not appropriate to read the +configuration module's name from an environment variable. For example, if you +are using the templating or view system as part of another system, without +running a full Django setup, you will want to be able to import the +appropriate subsystem and configure it just before you use it. + +In these cases, you can configure Django's settings manually (and, indeed, you +*must* do so if you are not setting the DJANGO_SETTINGS_MODULE environment +variable). The ``configure()`` method in ``django.conf.settings`` is the way +to do this. + +.. note:: + + You must call ``configure()`` prior to running any method that uses the + settings or reading any attributes from ``django.conf.settings`` yourself. + As soon as anything accesses ``django.conf.settings``, the module + specified in ``DJANGO_SETTINGS_MODULE`` is loaded, unless you have + previously called ``configure()`` and an error results if the environment + variable is not set correctly. + + It is an error to call ``configure()`` more than once or to call + ``configure()`` after any setting has been accessed. This is in line with + the admonishment earlier in this document about not writing to + ``settings`` at all. Configure your settings early and then leave them + fixed. + +The call to ``configure()`` takes any number of keyword arguments specifying +settings and their values. These keywords are all uppercase values with the +same names as the settings described above. If a particular setting is not +passed to ``configure()`` and is needed at some later point, the default value +from ``django.conf.global_settings`` is used. + +Example:: + + from django.conf import settings + + settings.configure(DEBUG = True, TEMPLATE_DEBUG = True, + TEMPLATE_DIRS = ('/home/web-apps/myapp/',)) + +Following this setup call, if some subsequent calls need, for example, to use +the value of ``setings.TEMPLATE_LOADERS``, the default value will be used. + +If, for some reason, you would 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()``. For example:: + + from django.conf import settings + from myapp import myapp_defaults + + settings.configure(default_settings = myapp_defaults, DEBUG = True) + + # Now all defaults will be taken from myapp_defaults and DEBUG will be + # set as requested. + # + # settings.configure(myapp_defaults, DEBUG = True) would also have worked. + Index: docs/i18n.txt =================================================================== --- docs/i18n.txt (revision 2908) +++ docs/i18n.txt (working copy) @@ -540,6 +540,17 @@ a big project out of several apps and put all translations into one big project message file. The choice is yours. +.. note:: + + If you are using manually configured settings as described in the + `settings`_ documentation, the ``locale`` directory in the project directory + will not be examined, since Django loses the ability to work out where the + project directory is (it normally uses the location of the settings file + to determine this and this file does not exist in the manually configured + case). + +.. _settings: http://www.djangoproject.com/documentation/settings/#using-settings-without-the-django-settings-module-environment-variable + All message file repositories are structured the same way. They are: * ``$APPPATH/locale//LC_MESSAGES/django.(po|mo)`` Index: docs/templates_python.txt =================================================================== --- docs/templates_python.txt (revision 2908) +++ docs/templates_python.txt (working copy) @@ -7,6 +7,11 @@ reference on the language syntax, see `The Django template language: For template authors`_. +If you are looking to use the Django template system as part of another +application, make sure to read the `configuration`_ section later in this +document for how to configure the template system after importing the right +pieces. + .. _`The Django template language: For template authors`: http://www.djangoproject.com/documentation/templates/ Basics @@ -876,3 +881,37 @@ For more examples of complex rendering, see the source code for ``{% if %}``, ``{% for %}``, ``{% ifequal %}`` and ``{% ifchanged %}``. They live in ``django/template/defaulttags.py``. + +.. _configuration: + +Configuring the template system in standalone mode +=================================================== + +.. note:: + + This section is only of interest to people trying to use the template + system as an output component in another application. If you are using the + template system as part of a Django application, nothing here applies to + you. + +Normally, Django will load all the configuration information it needs from its +own default configuration file, combined with the settings in the module given +in the ``DJANGO_SETTINGS_MODULE`` environment variable. When using the +template system independently of the rest of Django, the environment variable +approach is not very convenient because you probably want to configure the +template system in line with the rest of your application. + +To solve this problem, you need to use the manual configuration option +described in the `settings file`_ documentation. Simply import the appropriate +pieces of the templating system and then, *before* you call any of the +templating functions, call ``django.conf.settings.configure()`` with any +settings you wish to make. You might want to consider setting at least +``TEMPLATE_DIRS`` (if you are going to use template loaders), +``DEFAULT_CHARSET`` (although the default of ``utf-8`` is probably fine) and +``TEMPLATE_DEBUG``. The full set of available settings are described in the +`settings documentation`_ and any settings starting with the word *TEMPLATE_* +are of obvious interest. + +.. _settings file: http://www.djangoproject.com/documentation/settings/#using-settings-without-the-django-settings-module-environment-variable +.. _settings documentation: http://www.djangoproject.com/documentation/settings/ +