Make `AstropyDeprecationWarning` a `FutureWarning` subclass

[eerovaher]

Description

Starting from pytest 8.0 pytest.deprecated_call() recognizes FutureWarning instances, so AstropyDeprecationWarning being a subclass will allow reducing the amount of boilerplate code in tests. Compare:

import pytest
...
from astropy.utils.exceptions import AstropyDeprecationWarning
...
    with pytest.warns(AstropyDeprecationWarning, match=...):
        ....
# -------------------------------------------------------------
import pytest
...
    with pytest.deprecated_call(match=...):
        ...

astropy currently supports pytest 7.0, so we cannot start using deprecated_call() immediately, but we should not prevent downstream developers from using it if they choose to drop support for pytest < 8.0 before we do.

An alternative would be to make AstropyDeprecationWarning a subclass of DeprecationWarning instead, which would allow us to use deprecated_call() immediately. But doing that would not be entirely backwards compatible because by default it would also prevent users from seeing some (but not all) deprecation warnings, so I've opened this pull request with the less disruptive implementation.

• [x] By checking this box, the PR author has requested that maintainers do NOT use the "Squash and Merge" button. Maintainers should respect this when possible; however, the final decision is at the discretion of the maintainer that merges the PR.

[github-actions[bot]]

Thank you for your contribution to Astropy! 🌌 This checklist is meant to remind the package maintainers who will review this pull request of some common things to look for.

• [ ] Do the proposed changes actually accomplish desired goals?
• [ ] Do the proposed changes follow the Astropy coding guidelines?
• [ ] Are tests added/updated as required? If so, do they follow the Astropy testing guidelines?
• [ ] Are docs added/updated as required? If so, do they follow the Astropy documentation guidelines?
• [ ] Is rebase and/or squash necessary? If so, please provide the author with appropriate instructions. Also see instructions for rebase and squash.
• [ ] Did the CI pass? If no, are the failures related? If you need to run daily and weekly cron jobs as part of the PR, please apply the "Extra CI" label. Codestyle issues can be fixed by the bot.
• [ ] Is a change log needed? If yes, did the change log check pass? If no, add the "no-changelog-entry-needed" label. If this is a manual backport, use the "skip-changelog-checks" label unless special changelog handling is necessary.
• [ ] Is this a big PR that makes a "What's new?" entry worthwhile and if so, is (1) a "what's new" entry included in this PR and (2) the "whatsnew-needed" label applied?
• [ ] Is a milestone set? Milestone must be set but we cannot check for it on Actions; do not let the green checkmark fool you.
• [ ] At the time of adding the milestone, if the milestone set requires a backport to release branch(es), apply the appropriate "backport-X.Y.x" label(s) before merge.

[pllim]

Might have to wait for the pytest 8 compatibility problem to be resolved first before I can think about this. As it stands, is this fully backward compatible? This warning is widely used downstream too in the ecosystem, I don't want unpleasant surprises downstream.

[pllim]

I wonder if this should be discussed on astropy-dev and hold off till 7.0

[mhvk]

My 2¢ is that we should inherit from DeprecationWarning even if that means the warning will be a bit less visible - deprecation warnings really should not be too visible, since usually a user cannot do anything about them. And it is implied by the name...

May indeed be best to hold off till 7.0...

[eerovaher]

AstropyDeprecationWarning used to be a subclass of DeprecationWarning, but that was changed in #1871. The discussion there mentions Python 2.7, but the reasoning also applies to Python 3.2-3.6. However, Python 3.7 incorporates changes proposed in PEP 565, which make DeprecationWarning more visible, so it might indeed be a good idea to reconsider the decision made in #1871.

I can agree that if we choose to make AstropyDeprecationWarning a subclass of DeprecationWarning then it might be best to do it in 7.0.

[mhvk]

Thanks, that history is helpful!

[pllim]

OK, I posted this PR on https://groups.google.com/g/astropy-dev/c/FKHBpV1MSQA so people are aware and can provide feedback. I will change this back to draft and milestone to 7.0. Thanks!

[nstarman]

I agree on both counts:

1. AstropyDeprecationWarning should be a subclass of DeprecationWarning
2. And should be done in v7.

[saimn]

Imho it doesn't sound like a good idea to hide deprecation warning from users. Yes with PEP 565 they will sometimes see the warnings from an interactive session but not always (it's not clear to me from the PEP, when are warnings shown ? from functions imported in the REPL, but not if another function or their function call a deprecated astropy function ? )

[mhvk]

@saimn - I see your sentiment but in general feel that one should follow the standard unless there are very good reasons not to do so, and AstropyDeprecationWarning just shouts "subclass of DeprecationWarning". I'm not sure that there are many cases where a user can so usefully act on a warning that it is needed (I think most often they'll come from libraries that use astropy but don't quite have the resources to immediately act on them), but we could use or adapt numpy's VisbibleDeprecationWarning where it might be useful. This has the added benefit that for developers it is immediately clear that this is something special, not just a regular deprecation.

[saimn]

I'm not sure that there are many cases where a user can so usefully act on a warning that it is needed

just to take an example of changes waiting for 6.1:

• Renamed the min_cut and max_cut keywords in simple_norm and fits2bitmap to vmin and vmax. The old names are deprecated. [#15621]

this typically affects user code, and they have a way to fix it. Actually most of our deprecation warnings should mention an alternative, that's the point: https://github.com/astropy/astropy-APEs/blob/main/APE2.rst#releases-and-backwards-compatibility

API changes should be documented, with clear guidance on what is changing, why the change is being made, and how to migrate existing code to the new behavior.

[saimn]

in general feel that one should follow the standard unless there are very good reasons not to do so, and AstropyDeprecationWarning just shouts "subclass of DeprecationWarning

From Python docs, DeprecationWarning is for developers (libraries) while FutureWarning is for users:

exception DeprecationWarning Base class for warnings about deprecated features when those warnings are intended for other Python developers. exception FutureWarning Base class for warnings about deprecated features when those warnings are intended for end users of applications that are written in Python.

So subclassing FutureWarning seems perfectly fine.

[mhvk]

So subclassing FutureWarning seems perfectly fine.

I have nothing against renaming it to AstropyFutureWarning!

[mhvk]

On your specific example, current DeprecationWarning will be emitted if the user does the command from the prompt, just not if it is done from a script or inside a library. That seems somewhat appropriate. But really it seems like we should actually have the AstropyFutureWarning as well.

[github-actions[bot]]

Hi humans :wave: - this pull request hasn't had any new commits for approximately 4 months. I plan to close this in 30 days if the pull request doesn't have any new commits by then.

In lieu of a stalled pull request, please consider closing this and open an issue instead if a reminder is needed to revisit in the future. Maintainers may also choose to add keep-open label to keep this PR open but it is discouraged unless absolutely necessary.

If this PR still needs to be reviewed, as an author, you can rebase it to reset the clock.

If you believe I commented on this pull request incorrectly, please report this here.

[eerovaher]

Is there consensus about how to proceed? I don't care too much if AstropyDeprecationWarning is a subclass of DeprecationWarning or FutureWarning because we will be able to reduce the amount of boilerplate code either way.

[nstarman]

Given https://peps.python.org/pep-0702/ maybe DeprecationWarning is better?

[mhvk]

My sense is to inherit AstropyDeprecationWarning from DeprecationWarning as its name suggests, and possibly (in another PR) have a new AstropyFutureWarning for more visible warnings if we need them.

[pllim]

A long, long time ago, we didn't inherit from DeprecationWarning because Python ignored it by default. But Python and pytest have come a long way since, so maybe this is not an issue anymore. And I agree it makes more sense than inheriting from FutureWarning.

[github-actions[bot]]

I'm going to close this pull request as per my previous message. If you think what is being added/fixed here is still important, please remember to open an issue to keep track of it. Thanks!

If this is the first time I am commenting on this issue, or if you believe I closed this issue incorrectly, please report this here.

[eteq]

We discussed this in a dev telecon today. I think the feeling is that we want to go forward with this, but it's still not clear if we have reached consensus on DeprecationWaringvs FutureWarning. It seems to me like things are tilting DeprecationWarning, but I want to check: @saimn, are you ok with that?

My two cents is that I share @saimn's concern about hiding this from users (see my comments in #1871, which I think are still relevant a decade later), but I think experience also suggests that the users generally ignore these anyway, so I think it's a bit less critical than I think it used to be, and hence I also am ok with it subclassing DeprecationWarning.

[mhvk]

which I think are still relevant a decade later

Python has changed in the meantime: you now get to see a DeprecationWarning once, if you hit it from the command line.

[dhomeier]

My sense is to inherit AstropyDeprecationWarning from DeprecationWarning as its name suggests, and possibly (in another PR) have a new AstropyFutureWarning for more visible warnings if we need them.

This still seems the clean way out and should address the above concerns, even if it probably involves more work refactoring.

[eerovaher]

PEP 565 contains the following recommendation:

For library and framework authors that want to ensure their API compatibility warnings are more reliably seen by their users, the recommendation is to use a custom warning class that derives from DeprecationWarning in Python 3.7+, and from FutureWarning in earlier versions.

[github-actions[bot]]

Hi humans :wave: - this pull request hasn't had any new commits for approximately 6 months. I plan to close this in 30 days if the pull request doesn't have any new commits by then.

In lieu of a stalled pull request, please consider closing this and open an issue instead if a reminder is needed to revisit in the future. Maintainers may also choose to add keep-open label to keep this PR open but it is discouraged unless absolutely necessary.

If this PR still needs to be reviewed, as an author, you can rebase it to reset the clock.

If you believe I commented on this pull request incorrectly, please report this here.