Create urls module and remove import package from docs. (#1537)

* Create urls module and remove import package from docs.

By creating a urls module, devs can include the urls with a string
path to the urls, include('debug_toolbar.urls').

* Instantiate each panel when DebugToolbarConfig is ready.

This allows the cache panel to enable the instrumentation when the app
is ready.

* Support previous urls installation.

Update the __init__.py module to use the proper urls string path and app name.
This will maintain backwards compatability with the documentations previous
installation instructions.

* Add test for old style, debug_toolbar.urls usage.

debug_toolbar/__init__.py

@@ -1,5 +1,7 @@
 import django
 
+from debug_toolbar.urls import app_name
+
 __all__ = ["VERSION"]
 
 
@@ -9,7 +11,7 @@
 
 # Code that discovers files or modules in INSTALLED_APPS imports this module.
 
-urls = "debug_toolbar.toolbar", "djdt"
+urls = "debug_toolbar.urls", app_name
 
 if django.VERSION < (3, 2):
     default_app_config = "debug_toolbar.apps.DebugToolbarConfig"

debug_toolbar/apps.py

@@ -14,6 +14,13 @@ class DebugToolbarConfig(AppConfig):
     name = "debug_toolbar"
     verbose_name = _("Debug Toolbar")
 
+    def ready(self):
+        from debug_toolbar.toolbar import DebugToolbar
+
+        # Import the panels when the app is ready. This allows panels
+        # like CachePanel to enable the instrumentation immediately.
+        DebugToolbar.get_panel_classes()
+
 
 @register
 def check_middleware(app_configs, **kwargs):

debug_toolbar/toolbar.py

@@ -143,6 +143,8 @@ def is_toolbar_request(cls, request):
         """
         Determine if the request is for a DebugToolbar view.
         """
+        from debug_toolbar.urls import app_name
+
         # The primary caller of this function is in the middleware which may
         # not have resolver_match set.
         try:
@@ -152,7 +154,3 @@ def is_toolbar_request(cls, request):
         except Resolver404:
             return False
         return resolver_match.namespaces and resolver_match.namespaces[-1] == app_name
-
-
-app_name = "djdt"
-urlpatterns = DebugToolbar.get_urls()

debug_toolbar/urls.py

@@ -0,0 +1,4 @@
+from debug_toolbar.toolbar import DebugToolbar
+
+app_name = "djdt"
+urlpatterns = DebugToolbar.get_urls()

docs/changes.rst

@@ -11,6 +11,8 @@ Next version
   usages before ``enable_instrumentation`` is called.
 * Add check ``W006`` to warn that the toolbar is incompatible with
   ``TEMPLATES`` settings configurations with ``APP_DIRS`` set to ``False``.
+* Create ``urls`` module and update documentation to no longer require
+  importing the toolbar package.
 
 
 3.2.2 (2021-08-14)

docs/installation.rst

@@ -79,12 +79,11 @@ Add django-debug-toolbar's URLs to your project's URLconf:
 
 .. code-block:: python
 
-    import debug_toolbar
     from django.urls import include, path
 
     urlpatterns = [
         # ...
-        path('__debug__/', include(debug_toolbar.urls)),
+        path('__debug__/', include('debug_toolbar.urls')),
     ]
 
 This example uses the ``__debug__`` prefix, but you can use any prefix that

example/urls.py

@@ -2,13 +2,11 @@
 from django.urls import include, path
 from django.views.generic import TemplateView
 
-import debug_toolbar
-
 urlpatterns = [
     path("", TemplateView.as_view(template_name="index.html")),
     path("jquery/", TemplateView.as_view(template_name="jquery/index.html")),
     path("mootools/", TemplateView.as_view(template_name="mootools/index.html")),
     path("prototype/", TemplateView.as_view(template_name="prototype/index.html")),
     path("admin/", admin.site.urls),
-    path("__debug__/", include(debug_toolbar.urls)),
+    path("__debug__/", include("debug_toolbar.urls")),
 ]

tests/test_integration.py

@@ -101,6 +101,20 @@ def get_response(request):
         self.assertContains(response, "</div>\n</body>")
 
     def test_cache_page(self):
+        # Clear the cache before testing the views. Other tests that use cached_view
+        # may run earlier and cause fewer cache calls.
+        cache.clear()
+        self.client.get("/cached_view/")
+        self.assertEqual(len(self.toolbar.get_panel_by_id("CachePanel").calls), 3)
+        self.client.get("/cached_view/")
+        self.assertEqual(len(self.toolbar.get_panel_by_id("CachePanel").calls), 5)
+
+    @override_settings(ROOT_URLCONF="tests.urls_use_package_urls")
+    def test_include_package_urls(self):
+        """Test urlsconf that uses the debug_toolbar.urls in the include call"""
+        # Clear the cache before testing the views. Other tests that use cached_view
+        # may run earlier and cause fewer cache calls.
+        cache.clear()
         self.client.get("/cached_view/")
         self.assertEqual(len(self.toolbar.get_panel_by_id("CachePanel").calls), 3)
         self.client.get("/cached_view/")

tests/urls.py

@@ -2,8 +2,6 @@
 from django.contrib.auth.views import LoginView
 from django.urls import include, path, re_path
 
-import debug_toolbar
-
 from . import views
 from .models import NonAsciiRepr
 
@@ -25,5 +23,5 @@
     path("redirect/", views.redirect_view),
     path("login_without_redirect/", LoginView.as_view(redirect_field_name=None)),
     path("admin/", admin.site.urls),
-    path("__debug__/", include(debug_toolbar.urls)),
+    path("__debug__/", include("debug_toolbar.urls")),
 ]

tests/urls_use_package_urls.py

@@ -0,0 +1,11 @@
+"""urls.py to test using debug_toolbar.urls in include"""
+from django.urls import include, path
+
+import debug_toolbar
+
+from . import views
+
+urlpatterns = [
+    path("cached_view/", views.cached_view),
+    path("__debug__/", include(debug_toolbar.urls)),
+]