Switch usage to skip_file_prefixes instead of stacklevel when it makes sense

[Simon Charette]

In most of our usages of warnings.warn (and almost every usage that relates to deprecation warnings) we want them to be associated to the first out-of-as that's the most likely location that can be adjusted to avoid the warning.

In order to achieve this goal we've historically attempted to pass a fixed stacklevel to warnings.warn which can sometimes ​be tricky and error prone depending on how nested and convoluted the user or third-party app offending call site might be. In other cases ​we've opted not to provide a stacklevel at all as determining the offending call site under all circumstances is impossible.

Well it appears that this is a problem that Python 3.12 allows frameworks to address in a better way with ​the introduction of warnings.warn(skip_file_prefixes: tuple[str] | None). This new feature would allow us to ensure that the proper offending call site is referenced when emitting from a deeply nested call site where stacklevel is inappropriate.

Since this is a Python 3.12+ feature I'd suggest we introduce a get_non_django_stacklevel() -> int (better name welcome) function that could be used to pass to warnings.warn(stacklevel) until we drop support for Python 3.11.

[Natalia Bidart]

Hello Simon, as always thank you for your detailed and thorough report.

I agree with your proposal, I think this would help reducing the mistakes and overall improve the contributing experience. I'm setting this version to dev since this new feature should target 5.2 at this point.

[Mohammad Salehi]

Hello, If you agree, I would like to review this issue and start working on it ?
Thank you.

[Simon Charette]

I think we might want to wait for the patch for #35666 to land before committing efforts here Mohammad.

[Jacob Walls]

Just noting we have a someday/maybe ticket to favor importlib.resources over __file__ to better support byte-compiled Django: #30950. Should we be using that when developing this feature?

[Jacob Walls <jacobtylerwalls@…>]

In 34bd3ed:

Refs #36559, #35667 -- Used skip_file_prefixes in PartialTemplate.source warning.

[GitHub <noreply@…>]

In 7b26b64:

Refs #35667 -- Cached Django file prefixes for warnings.

[GitHub <noreply@…>]

In 8956ee3c:

Refs #35667 -- Updated contributing guide to use django_file_prefixes on deprecations.

[GitHub <noreply@…>]

In 9932866e:

Refs #35667 -- Corrected usage of skip_file_prefixes in contributing docs.

[Simon Charette]

Now that we're on Python 3.12+ in main this issue is much easier as we don't have to build our own shim and can simply swap usages of stacklevel with skip_file_prefixes.

[Jacob Walls <jacobtylerwalls@…>]

In fd705912:

Refs #36152, #35667 -- Used skip_file_prefixes in alias deprecation warning.

Follow-up to 8ede411a81b40ca53362e6788601193c7e56a0cf.

[Jacob Walls]

​PR