Refs #35514 -- Added warn_about_external_use() deprecation utility.

Implemented a new `warn_about_external_use()` helper to conditionally
issue warnings depending on whether a deprecated feature is used from
within Django.

Fixed `LazySettings._show_deprecation_warning()` (Refs #26029) to work
correctly when called from anywhere in `LazySettings`. Previously, it
assumed a specific code path through `LazyObject.__getattribute__()` and
an `@property` getter on `LazySettings`.

2 files changed, 97 insertions, 10 deletions

diff --git a/django/conf/__init__.py b/django/conf/__init__.py
index 25f5ffa305..dd0a158dfb 100644
--- a/django/conf/__init__.py
+++ b/django/conf/__init__.py
@@ -9,14 +9,16 @@ for a list of all possible variables.
 import importlib
 import os
 import time
-import traceback
 import warnings
 from pathlib import Path
 
-import django
 from django.conf import global_settings
 from django.core.exceptions import ImproperlyConfigured
-from django.utils.deprecation import RemovedInDjango70Warning, django_file_prefixes
+from django.utils.deprecation import (
+    RemovedInDjango70Warning,
+    django_file_prefixes,
+    warn_about_external_use,
+)
 from django.utils.functional import LazyObject, empty
 
 ENVIRONMENT_VARIABLE = "DJANGO_SETTINGS_MODULE"
@@ -146,13 +148,19 @@ class LazySettings(LazyObject):
         return self._wrapped is not empty
 
     def _show_deprecation_warning(self, message, category):
-        stack = traceback.extract_stack()
-        # Show a warning if the setting is used outside of Django.
-        # Stack index: -1 this line, -2 the property, -3 the
-        # LazyObject __getattribute__(), -4 the caller.
-        filename, _, _, _ = stack[-4]
-        if not filename.startswith(os.path.dirname(django.__file__)):
-            warnings.warn(message, category, stacklevel=2)
+        """Issue a warning when external code uses a deprecated setting.
+
+        Allow Django's own code to use it without emitting the warning. This
+        function should only be called from within LazySettings methods.
+        """
+        warn_about_external_use(
+            message,
+            category,
+            skip_name_prefixes=(
+                "django.conf.LazySettings",
+                "django.utils.functional.LazyObject",
+            ),
+        )
 
 
 class Settings:
diff --git a/django/utils/deprecation.py b/django/utils/deprecation.py
index 4aa1183216..89c9f71e55 100644
--- a/django/utils/deprecation.py
+++ b/django/utils/deprecation.py
@@ -30,6 +30,85 @@ class RemovedInDjango70Warning(PendingDeprecationWarning):
 RemovedAfterNextVersionWarning = RemovedInDjango70Warning
 
 
+def warn_about_external_use(
+    message,
+    category,
+    *,
+    skip_name_prefixes=None,
+    skip_frames=0,
+    internal_modules=None,
+):
+    """Issue a warning when a deprecated feature is used outside of Django.
+
+    Skip the warning when called from within Django, to avoid cascading
+    warnings when one deprecated feature is implemented on top of another.
+
+    Examine the stack to determine the "effective caller" (the code using the
+    deprecated feature). By default, this is the third frame from the top
+    (ignoring this helper plus the call site).
+
+    Provide `skip_name_prefixes` (a string or tuple of strings) to skip
+    additional frames by prefix-matching each frame's fully qualified name
+    (dotted module path plus qualname). `skip_name_prefixes` can be used to
+    skip specific functions, all methods in a class, or everything in a module.
+    Skipping stops at the first non-matching frame. Useful when a shared helper
+    is called through multiple paths of varying depth with a common prefix.
+
+    Provide `skip_frames` (an integer) to skip a fixed number of additional
+    frames (e.g., exactly one decorator or shared helper function). If both
+    options are provided, `skip_name_prefixes` is applied first.
+
+    Provide `internal_modules` (a tuple of names, defaulting to ("django",)) to
+    customize what counts as "internal". A frame is internal when its fully
+    qualified name starts with one of these names followed by a dot.
+
+    The warning is issued only if the effective caller (the first non-skipped
+    frame) is outside Django, attributed to that frame. If all frames are
+    skipped, it falls back to the base of the stack.
+
+    Note: To unconditionally issue a warning identifying the first caller
+    outside Django as its source, don't use this function. Instead, use::
+
+        warnings.warn(..., skip_file_prefixes=django_file_prefixes())
+
+    to avoid unnecessary stack inspection overhead.
+    """
+
+    if internal_modules is None:
+        internal_modules = ("django",)
+    if not isinstance(internal_modules, tuple):
+        raise TypeError("internal_modules must be a tuple of module names")
+    internal_prefixes = tuple(f"{mod}." for mod in internal_modules)
+
+    def get_fq_name(frame):
+        mod_name = frame.f_globals.get("__name__", "__main__")
+        return f"{mod_name}.{frame.f_code.co_qualname}"
+
+    def back(frame, level):
+        if frame is not None:
+            return frame.f_back, level + 1
+        return None, level
+
+    frame, level = inspect.currentframe(), 0
+    try:
+        # Back two frames: ignore warn_about_external_use() and its caller.
+        frame, level = back(*back(frame, level))
+
+        if skip_name_prefixes is not None:
+            while frame and get_fq_name(frame).startswith(skip_name_prefixes):
+                frame, level = back(frame, level)
+
+        for _ in range(skip_frames):
+            frame, level = back(frame, level)
+
+        is_internal = frame and get_fq_name(frame).startswith(internal_prefixes)
+    finally:
+        del frame
+
+    if not is_internal:
+        warnings.warn(message, category=category, stacklevel=level + 1)
+
+
 class warn_about_renamed_method:
     def __init__(
         self, class_name, old_method_name, new_method_name, deprecation_warning