Introduce debug_toolbar_urls to simplify installation

debug_toolbar/toolbar.py

@@ -2,16 +2,18 @@
 The main DebugToolbar class that loads and renders the Toolbar.
 """
 
+import re
 import uuid
 from collections import OrderedDict
 from functools import lru_cache
 
 from django.apps import apps
+from django.conf import settings
 from django.core.exceptions import ImproperlyConfigured
 from django.dispatch import Signal
 from django.template import TemplateSyntaxError
 from django.template.loader import render_to_string
-from django.urls import path, resolve
+from django.urls import include, path, re_path, resolve
 from django.urls.exceptions import Resolver404
 from django.utils.module_loading import import_string
 from django.utils.translation import get_language, override as lang_override
@@ -186,3 +188,27 @@ def observe_request(request):
     Determine whether to update the toolbar from a client side request.
     """
     return True
+
+
+def debug_toolbar_urls(prefix="__debug__"):
+    """
+    Return a URL pattern for serving toolbar in debug mode.
+
+    from django.conf import settings
+    from debug_toolbar.toolbar import debug_toolbar_urls
+
+    urlpatterns = [
+        # ... the rest of your URLconf goes here ...
+    ] + debug_toolbar_urls()
+    """
+    if not prefix:
+        raise ImproperlyConfigured("Empty urls prefix not permitted")
+    elif not settings.DEBUG:
+        # No-op if not in debug mode.
+        return []
+    return [
+        re_path(
+            r"^%s/" % re.escape(prefix.lstrip("/")),
+            include("debug_toolbar.urls"),
+        ),
+    ]

docs/changes.rst

@@ -9,6 +9,8 @@ Pending
 * Limit ``E001`` check to likely error cases when the
   ``SHOW_TOOLBAR_CALLBACK`` has changed, but the toolbar's URL
   paths aren't installed.
+* Introduce helper function ``debug_toolbar_urls`` to
+  simplify installation.
 
 4.4.2 (2024-05-27)
 ------------------

docs/installation.rst

@@ -95,14 +95,14 @@ Add django-debug-toolbar's URLs to your project's URLconf:
 .. code-block:: python
 
     from django.urls import include, path
+    from debug_toolbar.toolbar import debug_toolbar_urls
 
     urlpatterns = [
-        # ...
-        path("__debug__/", include("debug_toolbar.urls")),
-    ]
+        # ... the rest of your URLconf goes here ...
+    ] + debug_toolbar_urls()
 
-This example uses the ``__debug__`` prefix, but you can use any prefix that
-doesn't clash with your application's URLs.
+By default this uses the ``__debug__`` prefix for the paths, but you can
+use any prefix that doesn't clash with your application's URLs.
 
 
 5. Add the Middleware
@@ -180,11 +180,13 @@ You should also modify your URLconf file:
 
 .. code-block:: python
 
+    from django.conf import settings
+    from debug_toolbar.toolbar import debug_toolbar_urls
+
     if not settings.TESTING:
         urlpatterns = [
             *urlpatterns,
-            path("__debug__/", include("debug_toolbar.urls")),
-        ]
+        ] + debug_toolbar_urls()
 
 Alternatively, you can check out the :ref:`IS_RUNNING_TESTS <IS_RUNNING_TESTS>`
 option.

example/urls.py

@@ -1,8 +1,8 @@
-from django.conf import settings
 from django.contrib import admin
-from django.urls import include, path
+from django.urls import path
 from django.views.generic import TemplateView
 
+from debug_toolbar.toolbar import debug_toolbar_urls
 from example.views import increment
 
 urlpatterns = [
@@ -34,9 +34,4 @@
     ),
     path("admin/", admin.site.urls),
     path("ajax/increment", increment, name="ajax_increment"),
-]
-
-if settings.ENABLE_DEBUG_TOOLBAR:
-    urlpatterns += [
-        path("__debug__/", include("debug_toolbar.urls")),
-    ]
+] + debug_toolbar_urls()

tests/test_toolbar.py

@@ -0,0 +1,17 @@
+from django.core.exceptions import ImproperlyConfigured
+
+from debug_toolbar.toolbar import debug_toolbar_urls
+from tests.base import BaseTestCase
+
+
+class DebugToolbarUrlsTestCase(BaseTestCase):
+    def test_empty_prefix_errors(self):
+        with self.assertRaises(ImproperlyConfigured):
+            debug_toolbar_urls(prefix="")
+
+    def test_empty_when_debug_is_false(self):
+        self.assertEqual(debug_toolbar_urls(), [])
+
+    def test_has_path(self):
+        with self.settings(DEBUG=True):
+            self.assertEqual(len(debug_toolbar_urls()), 1)