diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/internals/contributing/writing-code/submitting-patches.txt | 3 | ||||
| -rw-r--r-- | docs/ref/utils.txt | 28 | ||||
| -rw-r--r-- | docs/releases/6.2.txt | 5 |
3 files changed, 34 insertions, 2 deletions
diff --git a/docs/internals/contributing/writing-code/submitting-patches.txt b/docs/internals/contributing/writing-code/submitting-patches.txt index 288a50fc76..a038de53f7 100644 --- a/docs/internals/contributing/writing-code/submitting-patches.txt +++ b/docs/internals/contributing/writing-code/submitting-patches.txt @@ -352,7 +352,8 @@ previous behavior, or standalone items that are unnecessary or unused when the deprecation ends. For example:: import warnings - from django.utils.deprecation import RemovedInDjangoXXWarning, django_file_prefixes + from django.utils.deprecation import RemovedInDjangoXXWarning + from django.utils.warnings import django_file_prefixes # RemovedInDjangoXXWarning. diff --git a/docs/ref/utils.txt b/docs/ref/utils.txt index 1c42784d13..0f38105713 100644 --- a/docs/ref/utils.txt +++ b/docs/ref/utils.txt @@ -1187,3 +1187,31 @@ For a complete discussion on the usage of the following see the Turns a Django template into something that is understood by ``xgettext``. It does so by translating the Django translation tags into standard ``gettext`` function invocations. + +``django.utils.warnings`` +========================= + +.. module:: django.utils.warnings + :synopsis: Helpers for issuing warnings. + +.. function:: django_file_prefixes() + + .. versionadded:: 6.2 + + Returns a tuple of file path prefixes for the Django package directory. + This is used as the ``skip_file_prefixes`` argument to + :func:`warnings.warn` so that warnings are attributed to the *caller* + (your project or third-party library) rather than to Django internals. + + The result is cached after the first call. + + Usage example:: + + import warnings + from django.utils.warnings import django_file_prefixes + + warnings.warn( + "Your custom warning message.", + category=RuntimeWarning, + skip_file_prefixes=django_file_prefixes(), + ) diff --git a/docs/releases/6.2.txt b/docs/releases/6.2.txt index 09dab3a93d..74ba31f171 100644 --- a/docs/releases/6.2.txt +++ b/docs/releases/6.2.txt @@ -232,7 +232,10 @@ URLs Utilities ~~~~~~~~~ -* ... +* The new ``django.utils.warnings`` module provides + :func:`~django.utils.warnings.django_file_prefixes`, which returns the file + path prefix of the Django package for use as the ``skip_file_prefixes`` + argument of :func:`warnings.warn`. Validators ~~~~~~~~~~ |