Provide a solution to prevent monkey-patching the settings.

This is necessary to work around extreme cases of circular imports.
We really need to reverse URLs at import time and this isn't always
possible.

Author: aaugustin

debug_toolbar/models.py

@@ -6,6 +6,7 @@
 from django.utils.importlib import import_module
 
 import debug_toolbar
+from debug_toolbar import settings as dt_settings
 from debug_toolbar.middleware import DebugToolbarMiddleware
 
 
@@ -56,7 +57,7 @@ def patch_root_urlconf():
         clear_url_caches()
 
 
-if settings.DEBUG:
+if dt_settings.PATCH_SETTINGS:
     patch_internal_ips()
     patch_middleware_classes()
     patch_root_urlconf()

debug_toolbar/settings.py

@@ -122,3 +122,6 @@
                 "%r was renamed to %r. Update your DEBUG_TOOLBAR_PANELS "
                 "setting." % (old_panel, new_panel), DeprecationWarning)
             PANELS[index] = new_panel
+
+
+PATCH_SETTINGS = getattr(settings, 'DEBUG_TOOLBAR_PATCH_SETTINGS', settings.DEBUG)

docs/configuration.rst

@@ -12,6 +12,13 @@ settings module to customize its behavior.
     it'll prevent you from taking advantage of better defaults that may be
     introduced in future releases.
 
+DEBUG_TOOLBAR_PATCH_SETTINGS
+----------------------------
+
+This setting defines whether the toolbar will attempt to automatically adjust
+your project's settings, as described in the :doc:`installation instructions
+<installation>`. By default it has the same value as your ``DEBUG`` setting.
+
 DEBUG_TOOLBAR_PANELS
 --------------------
 

docs/installation.rst

@@ -51,9 +51,21 @@ what it does, or if you prefer defining your settings explicitly, read below.
     during the start-up sequence. This works with ``manage.py runserver``
     because it validates models before serving requests.
 
+.. warning::
+
+    The automatic setup imports your project's URLconf in order to add the
+    Debug Toolbar's URLs. This may trigger circular imports when the URLconf
+    imports views that import models. If you're hitting an :exc:`ImportError`,
+    follow the explicit setup instructions.
+
 Explicit setup
 --------------
 
+First, tell the toolbar not to adjust your settings automatically by adding
+this line in your settings module::
+
+    DEBUG_TOOLBAR_PATCH_SETTINGS = False
+
 URLconf
 ~~~~~~~