Author: lukeplant Date: 2009-12-09 06:47:50 -0600 (Wed, 09 Dec 2009) New Revision: 11802
Modified: django/trunk/docs/internals/contributing.txt Log: Added section info on top-level use of django.conf.settings to 'contributing' documentation Modified: django/trunk/docs/internals/contributing.txt =================================================================== --- django/trunk/docs/internals/contributing.txt 2009-12-09 04:24:05 UTC (rev 11801) +++ django/trunk/docs/internals/contributing.txt 2009-12-09 12:47:50 UTC (rev 11802) @@ -426,6 +426,47 @@ .. _Django i18n mailing list: http://groups.google.com/group/django-i18n/ +Django conventions +================== + +Various Django-specific code issues are detailed in this section. + +Use of ``django.conf.settings`` +------------------------------- + +Modules should not in general use settings stored in ``django.conf.settings`` at +the top level (i.e. evaluated when the module is imported). The explanation for +this is as follows: + +Manual configuration of settings (i.e. not relying on the +``DJANGO_SETTINGS_MODULE`` environment variable) is allowed and possible as +follows:: + + from django.conf import settings + + settings.configure({}, SOME_SETTING='foo') + +However, if any setting is accessed before the ``settings.configure`` line, this +will not work. (Internally, ``setttings`` is a ``LazyObject`` which configures +itself automatically when the settings are accessed if it has not already been +configured). + +So, if there is a module containg some code as follows:: + + from django.conf import settings + from django.core.urlresolvers import get_callable + + default_foo_view = get_callable(settings.FOO_VIEW) + +...then importing this module will cause the settings object to be configured. +That means that the ability for third parties to import the module at the top +level is incompatible with the ability to configure the settings object +manually, or makes it very difficult in some circumstances. + +Instead of the above code, a level of laziness or indirection must be used, such +as :class:`django.utils.functional.LazyObject`, :func:`django.utils.functional.lazy` or +``lambda``. + Coding style ============ -- You received this message because you are subscribed to the Google Groups "Django updates" group. To post to this group, send email to django-upda...@googlegroups.com. To unsubscribe from this group, send email to django-updates+unsubscr...@googlegroups.com. For more options, visit this group at http://groups.google.com/group/django-updates?hl=en.
