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.

4 files changed, 24 insertions, 1 deletions

diff --git a/debug_toolbar/models.py b/debug_toolbar/models.py
index 2db10b8..c9a12d8 100644
--- a/debug_toolbar/models.py
+++ b/debug_toolbar/models.py
@@ -6,6 +6,7 @@ from django.core.urlresolvers import clear_url_caches, reverse, NoReverseMatch
 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()
diff --git a/debug_toolbar/settings.py b/debug_toolbar/settings.py
index 022fb8a..bde8a1c 100644
--- a/debug_toolbar/settings.py
+++ b/debug_toolbar/settings.py
@@ -122,3 +122,6 @@ else:
                 "%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)
diff --git a/docs/configuration.rst b/docs/configuration.rst
index 1e527e2..b0a67b1 100644
--- a/docs/configuration.rst
+++ b/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
 --------------------
 
diff --git a/docs/installation.rst b/docs/installation.rst
index 221d85f..921cfe8 100644
--- a/docs/installation.rst
+++ b/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
 ~~~~~~~