Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Added section info on top-level use of django.conf.settings to 'contr…

…ibuting' documentation

git-svn-id: http://code.djangoproject.com/svn/django/trunk@11802 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
commit bb428f3e86953d09df050b2614639f5c8a68840d 1 parent 81dd5c2
Luke Plant authored December 09, 2009

Showing 1 changed file with 41 additions and 0 deletions. Show diff stats Hide diff stats

  1. 41  docs/internals/contributing.txt
41  docs/internals/contributing.txt
@@ -426,6 +426,47 @@ translated, here's what to do:
426 426
 
427 427
 .. _Django i18n mailing list: http://groups.google.com/group/django-i18n/
428 428
 
  429
+Django conventions
  430
+==================
  431
+
  432
+Various Django-specific code issues are detailed in this section.
  433
+
  434
+Use of ``django.conf.settings``
  435
+-------------------------------
  436
+
  437
+Modules should not in general use settings stored in ``django.conf.settings`` at
  438
+the top level (i.e. evaluated when the module is imported). The explanation for
  439
+this is as follows:
  440
+
  441
+Manual configuration of settings (i.e. not relying on the
  442
+``DJANGO_SETTINGS_MODULE`` environment variable) is allowed and possible as
  443
+follows::
  444
+
  445
+    from django.conf import settings
  446
+
  447
+    settings.configure({}, SOME_SETTING='foo')
  448
+
  449
+However, if any setting is accessed before the ``settings.configure`` line, this
  450
+will not work. (Internally, ``setttings`` is a ``LazyObject`` which configures
  451
+itself automatically when the settings are accessed if it has not already been
  452
+configured).
  453
+
  454
+So, if there is a module containg some code as follows::
  455
+
  456
+    from django.conf import settings
  457
+    from django.core.urlresolvers import get_callable
  458
+
  459
+    default_foo_view = get_callable(settings.FOO_VIEW)
  460
+
  461
+...then importing this module will cause the settings object to be configured.
  462
+That means that the ability for third parties to import the module at the top
  463
+level is incompatible with the ability to configure the settings object
  464
+manually, or makes it very difficult in some circumstances.
  465
+
  466
+Instead of the above code, a level of laziness or indirection must be used, such
  467
+as :class:`django.utils.functional.LazyObject`, :func:`django.utils.functional.lazy` or
  468
+``lambda``.
  469
+
429 470
 Coding style
430 471
 ============
431 472
 

0 notes on commit bb428f3

Please sign in to comment.
Something went wrong with that request. Please try again.