diff --git a/debug_toolbar/toolbar.py b/debug_toolbar/toolbar.py index fc07543b5..04502ab09 100644 --- a/debug_toolbar/toolbar.py +++ b/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"), + ), + ] diff --git a/docs/changes.rst b/docs/changes.rst index 6dbfe829a..10883b1e2 100644 --- a/docs/changes.rst +++ b/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) ------------------ diff --git a/docs/installation.rst b/docs/installation.rst index 657450fac..9200504b7 100644 --- a/docs/installation.rst +++ b/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 ` option. diff --git a/example/urls.py b/example/urls.py index 7569a57f9..b64aa1c37 100644 --- a/example/urls.py +++ b/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() diff --git a/tests/test_toolbar.py b/tests/test_toolbar.py new file mode 100644 index 000000000..7155d3fcb --- /dev/null +++ b/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)