Add type hints to the toolbar and middleware modules

Co-Authored-By: Tim Schilling <[email protected]>

Author: JohananOppongAmoateng

debug_toolbar/_stubs.py

@@ -1,8 +1,9 @@
 from __future__ import annotations
 
-from typing import Any, NamedTuple, Optional
+from typing import Any, NamedTuple, Optional, Protocol
 
 from django import template as dj_template
+from django.http import HttpRequest, HttpResponse
 
 
 class InspectStack(NamedTuple):
@@ -24,3 +25,7 @@ class RenderContext(dj_template.context.RenderContext):
 class RequestContext(dj_template.RequestContext):
     template: dj_template.Template
     render_context: RenderContext
+
+
+class GetResponse(Protocol):
+    def __call__(self, request: HttpRequest) -> HttpResponse: ...

debug_toolbar/middleware.py

@@ -5,6 +5,7 @@
 import re
 import socket
 from functools import cache
+from typing import Callable
 
 from asgiref.sync import (
     async_to_sync,
@@ -13,14 +14,19 @@
     sync_to_async,
 )
 from django.conf import settings
+from django.http import HttpRequest, HttpResponse
 from django.utils.module_loading import import_string
 
 from debug_toolbar import settings as dt_settings
+from debug_toolbar._stubs import GetResponse
+from debug_toolbar.panels import Panel
 from debug_toolbar.toolbar import DebugToolbar
 from debug_toolbar.utils import clear_stack_trace_caches, is_processable_html_response
 
+_HTML_TYPES = ("text/html", "application/xhtml+xml")
 
-def show_toolbar(request):
+
+def show_toolbar(request: HttpRequest) -> bool:
     """
     Default function to determine whether to show the toolbar on a given page.
     """
@@ -35,7 +41,7 @@ def show_toolbar(request):
     return False
 
 
-def show_toolbar_with_docker(request):
+def show_toolbar_with_docker(request: HttpRequest) -> bool:
     """
     Default function to determine whether to show the toolbar on a given page.
     """
@@ -67,7 +73,7 @@ def show_toolbar_with_docker(request):
 
 
 @cache
-def show_toolbar_func_or_path():
+def show_toolbar_func_or_path() -> Callable:
     """
     Fetch the show toolbar callback from settings
 
@@ -82,7 +88,7 @@ def show_toolbar_func_or_path():
         return func_or_path
 
 
-def get_show_toolbar(async_mode):
+def get_show_toolbar(async_mode) -> Callable:
     """
     Get the callback function to show the toolbar.
 
@@ -108,7 +114,7 @@ class DebugToolbarMiddleware:
     sync_capable = True
     async_capable = True
 
-    def __init__(self, get_response):
+    def __init__(self, get_response: GetResponse):
         self.get_response = get_response
         # If get_response is a coroutine function, turns us into async mode so
         # a thread is not consumed during a whole request.
@@ -119,7 +125,7 @@ def __init__(self, get_response):
             # __call__ to avoid swapping out dunder methods.
             markcoroutinefunction(self)
 
-    def __call__(self, request):
+    def __call__(self, request: HttpRequest) -> HttpResponse:
         # Decide whether the toolbar is active for this request.
         if self.async_mode:
             return self.__acall__(request)
@@ -144,7 +150,7 @@ def __call__(self, request):
 
         return self._postprocess(request, response, toolbar)
 
-    async def __acall__(self, request):
+    async def __acall__(self, request: HttpRequest) -> HttpResponse:
         # Decide whether the toolbar is active for this request.
         show_toolbar = get_show_toolbar(async_mode=self.async_mode)
 
@@ -172,7 +178,9 @@ async def __acall__(self, request):
 
         return self._postprocess(request, response, toolbar)
 
-    def _postprocess(self, request, response, toolbar):
+    def _postprocess(
+        self, request: HttpRequest, response: HttpResponse, toolbar: DebugToolbar
+    ) -> HttpResponse:
         """
         Post-process the response.
         """
@@ -206,7 +214,7 @@ def _postprocess(self, request, response, toolbar):
         return response
 
     @staticmethod
-    def get_headers(request, panels):
+    def get_headers(request: HttpRequest, panels: list[Panel]) -> dict[str, str]:
         headers = {}
         for panel in panels:
             for header, value in panel.get_headers(request).items():

debug_toolbar/panels/__init__.py

@@ -3,6 +3,7 @@
 from django.utils.functional import classproperty
 
 from debug_toolbar import settings as dt_settings
+from debug_toolbar._stubs import GetResponse
 from debug_toolbar.utils import get_name_from_obj
 
 
@@ -13,7 +14,7 @@ class Panel:
 
     is_async = False
 
-    def __init__(self, toolbar, get_response):
+    def __init__(self, toolbar, get_response: GetResponse):
         self.toolbar = toolbar
         self.get_response = get_response
         self.from_store = False

debug_toolbar/toolbar.py

@@ -2,34 +2,46 @@
 The main DebugToolbar class that loads and renders the Toolbar.
 """
 
+from __future__ import annotations
+
 import logging
 import re
 import uuid
 from functools import cache
+from typing import Callable
 
 from django.apps import apps
 from django.conf import settings
 from django.core.exceptions import ImproperlyConfigured
 from django.dispatch import Signal
+from django.http import HttpRequest
 from django.template import TemplateSyntaxError
 from django.template.loader import render_to_string
-from django.urls import include, path, re_path, resolve
+from django.urls import URLPattern, URLResolver, 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
 
 from debug_toolbar import APP_NAME, settings as dt_settings
-from debug_toolbar.store import get_store
+from debug_toolbar._stubs import GetResponse
+from debug_toolbar.store import BaseStore, get_store
+
+from .panels import Panel
 
 logger = logging.getLogger(__name__)
 
 
 class DebugToolbar:
     # for internal testing use only
     _created = Signal()
-    store = None
-
-    def __init__(self, request, get_response, request_id=None):
+    store: BaseStore = None
+
+    def __init__(
+        self,
+        request: HttpRequest,
+        get_response: GetResponse,
+        request_id: str | None = None,
+    ):
         self.request = request
         self.config = dt_settings.get_config().copy()
         panels = []
@@ -49,21 +61,21 @@ def __init__(self, request, get_response, request_id=None):
     # Manage panels
 
     @property
-    def panels(self):
+    def panels(self) -> list[Panel]:
         """
         Get a list of all available panels.
         """
         return list(self._panels.values())
 
     @property
-    def enabled_panels(self):
+    def enabled_panels(self) -> list[Panel]:
         """
         Get a list of panels enabled for the current request.
         """
         return [panel for panel in self._panels.values() if panel.enabled]
 
     @property
-    def csp_nonce(self):
+    def csp_nonce(self) -> str | None:
         """
         Look up the Content Security Policy nonce if there is one.
 
@@ -72,15 +84,15 @@ def csp_nonce(self):
         """
         return getattr(self.request, "csp_nonce", None)
 
-    def get_panel_by_id(self, panel_id):
+    def get_panel_by_id(self, panel_id: str) -> Panel:
         """
         Get the panel with the given id, which is the class name by default.
         """
         return self._panels[panel_id]
 
     # Handle rendering the toolbar in HTML
 
-    def render_toolbar(self):
+    def render_toolbar(self) -> str:
         """
         Renders the overall Toolbar with panels inside.
         """
@@ -101,7 +113,7 @@ def render_toolbar(self):
             else:
                 raise
 
-    def should_render_panels(self):
+    def should_render_panels(self) -> bool:
         """Determine whether the panels should be rendered during the request
 
         If False, the panels will be loaded via Ajax.
@@ -121,17 +133,19 @@ def init_store(self):
         self.store.set(self.request_id)
 
     @classmethod
-    def fetch(cls, request_id, panel_id=None):
+    def fetch(
+        cls, request_id: str, panel_id: str | None = None
+    ) -> StoredDebugToolbar | None:
         if get_store().exists(request_id):
             return StoredDebugToolbar.from_store(request_id, panel_id=panel_id)
 
     # Manually implement class-level caching of panel classes and url patterns
     # because it's more obvious than going through an abstraction.
 
-    _panel_classes = None
+    _panel_classes: list[Panel] | None = None
 
     @classmethod
-    def get_panel_classes(cls):
+    def get_panel_classes(cls) -> list[type[Panel]] | None:
         if cls._panel_classes is None:
             # Load panels in a temporary variable for thread safety.
             panel_classes = [
@@ -140,10 +154,10 @@ def get_panel_classes(cls):
             cls._panel_classes = panel_classes
         return cls._panel_classes
 
-    _urlpatterns = None
+    _urlpatterns: list[URLPattern | URLResolver] | None = None
 
     @classmethod
-    def get_urls(cls):
+    def get_urls(cls) -> list[URLPattern | URLResolver]:
         if cls._urlpatterns is None:
             from . import views
 
@@ -159,7 +173,7 @@ def get_urls(cls):
         return cls._urlpatterns
 
     @classmethod
-    def is_toolbar_request(cls, request):
+    def is_toolbar_request(cls, request: HttpRequest) -> bool:
         """
         Determine if the request is for a DebugToolbar view.
         """
@@ -171,11 +185,14 @@ def is_toolbar_request(cls, request):
             )
         except Resolver404:
             return False
-        return resolver_match.namespaces and resolver_match.namespaces[-1] == APP_NAME
+        return (
+            bool(resolver_match.namespaces)
+            and resolver_match.namespaces[-1] == APP_NAME
+        )
 
     @staticmethod
     @cache
-    def get_observe_request():
+    def get_observe_request() -> Callable:
         # If OBSERVE_REQUEST_CALLBACK is a string, which is the recommended
         # setup, resolve it to the corresponding callable.
         func_or_path = dt_settings.get_config()["OBSERVE_REQUEST_CALLBACK"]
@@ -185,22 +202,27 @@ def get_observe_request():
             return func_or_path
 
 
-def observe_request(request):
+def observe_request(request: HttpRequest) -> bool:
     """
     Determine whether to update the toolbar from a client side request.
     """
     return True
 
 
-def from_store_get_response(request):
+def from_store_get_response(request: HttpRequest | None) -> None:
     logger.warning(
         "get_response was called for debug toolbar after being loaded from the store. No request exists in this scenario as the request is not stored, only the panel's data."
     )
     return None
 
 
 class StoredDebugToolbar(DebugToolbar):
-    def __init__(self, request, get_response, request_id=None):
+    def __init__(
+        self,
+        request: HttpRequest | None,
+        get_response: GetResponse,
+        request_id: str | None = None,
+    ):
         self.request = None
         self.config = dt_settings.get_config().copy()
         self.process_request = get_response
@@ -210,7 +232,9 @@ def __init__(self, request, get_response, request_id=None):
         self.init_store()
 
     @classmethod
-    def from_store(cls, request_id, panel_id=None):
+    def from_store(
+        cls, request_id: str, panel_id: str | None = None
+    ) -> StoredDebugToolbar:
         toolbar = StoredDebugToolbar(
             None, from_store_get_response, request_id=request_id
         )
@@ -226,7 +250,7 @@ def from_store(cls, request_id, panel_id=None):
         return toolbar
 
 
-def debug_toolbar_urls(prefix="__debug__"):
+def debug_toolbar_urls(prefix: str = "__debug__") -> list[URLPattern | URLResolver]:
     """
     Return a URL pattern for serving toolbar in debug mode.
 

docs/panels.rst

@@ -386,6 +386,8 @@ There is no public CSS API at this time.
 
     .. automethod:: debug_toolbar.panels.Panel.run_checks
 
+.. autoclass:: debug_toolbar._stubs.GetResponse
+
 .. _javascript-api:
 
 JavaScript API