Introduce debug_toolbar_urls to simplify installation

While this isn't a huge improvement, it provides a hook for us
to more easily introduce library level controls for when urls
are installed. It also eliminates the user from having to
write an if statement for the most basic of installations.

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

@@ -7,6 +7,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)