Switch `deprecated` internals to `warnings.deprecated` by nstarman · Pull Request #15307 · astropy/astropy

nstarman · 2023-09-11T20:43:19Z

Reimplements astropy.utils.decorators.deprecated on top of PEP 702's warnings.deprecated (Python 3.13+), falling back to the typing_extensions backport on 3.12. Our decorator keeps its own signature, default warning type, docstring rewriting, and classmethod/staticmethod support; only the machinery underneath changes.

typing_extensions is added as a conditional dependency, python_version < '3.13', in both dependencies and build-system.requires (the build imports astropy). It drops out entirely once we require 3.13.

Behaviour changes

Deprecating a class now follows PEP 702 semantics, which differ from what we did before:

The warning is raised when the class is subclassed, and when the class itself is instantiated — but not when an already-defined subclass is instantiated. Previously the wrapped __init__/__new__ warned for every subclass instantiation and never on subclass creation.
__deprecated__ is set on the wrapped function as well as the wrapper, as PEP 702 specifies.

Both are covered by docs/changes/utils/15307.api.rst and the Notes section of the decorator's docstring. The only in-tree fallout was TestRunner, which subclasses the deprecated TestRunnerBase: importing astropy.tests.runner now warns, so astropy/__init__.py imports it inside the catch_warnings block that was already there for make_test_runner_in.

TODO

changelog
edit the docs of astropy.utils.decorators.deprecated to mention warnings.deprecated: what ours does differently and when one should use that one instead.

github-actions · 2023-09-11T20:43:56Z

github-actions · 2023-09-11T20:44:01Z

👋 Thank you for your draft pull request! Do you know that you can use [ci skip] or [skip ci] in your commit messages to skip running continuous integration tests until you are ready?

nstarman · 2023-09-11T21:01:56Z

Definitely merits a changelog, given the added dependency, however proximate to core python.

nstarman · 2023-09-11T21:03:49Z

+    return func.__func__ if isinstance(func, _method_types) else func
+
+
+def _deprecation_message(alternative, pending):


In a followup PR this can be made a public function so people can have an Astropy-style deprecation message but use core python for their deprecations.

nstarman · 2023-09-25T03:48:24Z

Should probably update our decorator to also attach __deprecated__ to the original object for better consistency.

mhvk · 2023-09-25T07:33:01Z

Should probably update our decorator to also attach __deprecated__ to the original object for better consistency.

Isn't that what we did? We should indeed mimic what typing.deprecated does!

nstarman · 2023-09-25T12:56:22Z

For classmethod and such we set __deprecated__ on the wrapper, not mutating the original object. Adding it to the wrapper is good. But it should also be on the original.

neutrinoceros · 2023-09-25T13:00:50Z

Headsup: the @deprecated decorator isn't targetting the typing module anymore, and it's now proposed to land in warnings (see python/peps#3442)

neutrinoceros · 2023-09-25T13:13:48Z

It's also worth noting that it's actually not available in Python 3.12, and currently aimed at 3.13

mhvk · 2023-09-25T14:30:25Z

Must say it makes more sense in the warnings module. That likely also means there is no backport, so I guess we should just take this slow.

Still all in favour of mimicking the decorator's behaviour so that IDEs recognize our deprecated too.

nstarman · 2023-09-26T01:06:09Z

Must say it makes more sense in the warnings module. That likely also means there is no backport, so I guess we should just take this slow.

Agreed. This gives us many years to deprecate any duplicated functionality.

Still all in favour of mimicking the decorator's behaviour so that IDEs recognize our deprecated too.

That would be nice. Pyright is probably the most used and we could potentially open an issue/PR. My thought is that this is all done statically and deprecated is recognized by an AST parser, not as a live code object. Short of just matching on the function name, I'm not sure if a static checker can understand our decorator.

mhvk · 2023-09-26T06:19:56Z

Checking on a function names seems fine, TBH. What decorator called deprecated would not mean to deprecate the code...

nstarman · 2026-05-14T17:03:55Z

Just waiting for us to drop 3.11

neutrinoceros · 2026-05-17T15:29:39Z

+    This decorator is a wrapper around `~typing.deprecated`, which was introduced by
+    `PEP 702 <https://peps.python.org/pep-0702/>`_ in Python 3.12. In lower versions of
+    Python, the `~typing_extenstions.deprecated` backport is used instead. There are a number of differences
+    between this decorator and `~typing.deprecated`, which are described below.


Suggested change

between this decorator and `~typing.deprecated`, which are described below.

between this decorator and `~warnings.deprecated`, which are described below.

here and below

pllim · 2026-07-20T19:24:52Z

This has multiple conflicts now and I don't think we can even do it yet. Should we just close this PR?

nstarman · 2026-07-20T23:25:54Z

I'm fine to rebase and fix conflicts when we do drop Python 3.11.

neutrinoceros · 2026-07-21T09:15:37Z

We'll need to drop 3.12 as well if we can't agree to have typing-extensions as a conditional dependency. FTR, I'm still very much in favor of it, especially when the alternative is "let's drop 2 non-EOL versions of Python".

pllim · 2026-07-21T15:42:06Z

Re: #15307 (comment)

On the other hand, I don't like introducing a dependency and then remove it again. This is not urgent so I don't see why we cannot wait longer.

neutrinoceros · 2026-07-21T15:51:31Z

This is not urgent so I don't see why we cannot wait longer.

actually that would be my argument against most API removals (yes, deprecated ones), and these are going much faster in astropy than in most libraries I know of.
Users are now more likely than ever to rely on type checkers to discover deprecated APIs, and with our community-wise tendency to drop them as soon as possible, one more way to find call sites wouldn't be a luxury.

mhvk · 2026-07-21T15:59:26Z

I thought typing_extensions was requested for quite different reasons elsewhere -- I think that particular case really makes sense, as it is basically a backport of stuff that is already in later versions of python, blessed by python itself. It is also particularly easy to remove in the future, since it will be linked to the python version.

nstarman · 2026-07-21T16:01:31Z

a backport of stuff that is already in later versions of python, blessed by python itself. It is also particularly easy to [auto-fix typing imports], since it will be linked to the python version.

💯

astrofrog · 2026-09-11T13:36:44Z

@nstarman Python 3.11 has been dropped, so is it time to revisit this?

nstarman · 2026-09-11T14:42:02Z

Yes! I can get to this soon.

Signed-off-by: nstarman <[email protected]>

pllim · 2026-09-14T15:07:29Z

+    This decorator is a wrapper around `warnings.deprecated`, which was introduced by
+    `PEP 702 <https://peps.python.org/pep-0702/>`_ in Python 3.13. On Python 3.12 the
+    ``typing_extensions.deprecated`` backport is used instead. There are a number of
+    differences between this decorator and `warnings.deprecated`:


I feel like this is too disruptive. deprecated and its associated decorators in this module is also widely used downstream. Why do we need to change anything here? You are free to use warnings.deprecated internally here as much as you want without touching this module, yes?

I agree that changing our existing decorator is unnecessarily disruptive as it's public API. Ideally we should just... deprecate it ?

I don't even wanna think about it. How do you deprecate the deprecation? Haha. But seriously, yes, but not until we help downstream move away from it first. It is going to be a long game.

How are we going to deprecate the astropy decorator without a process like this?
We have this decorator because Python didn't (at time of writing).
I think a new core-Python mechanism for communicating deprecations is the invitation we should accept to reduce our non-core-code burden.
With this in place we can go further and deprecate the integrated message mechanism, replacing it with a helper function, so deprecations work like

from astropy.utils.decorators import deprecation_message @warnings.deprecated(deprecation_message(...)) def func(...

Looking at the differences, I think the primary way this breaks downstream is in test suites, where it should have minimal impact on users.
Also, given that warnings.deprecated is recognized by static type checkers and ours isn't, IMO no one should be using ours. E.g. VSCode shows me a visible warning every time I go to use a warnings.deprecated object, even before running the program.
I think users are best served by being notified about deprecations early, which is quite literally impossible with our decorator. Now that is possible and is in Python, IMO it's a question of how we do this, not if.

so deprecations work like

ah, maybe I should have looked at the PR again before I commented. I was thinking we would use the stdlib decorator directly within astropy itself, but clearly that's not the approach you are going with.

Yeah, and I'd refactor the internals of deprecated to use it to generate the message.

Setback encountered: @astropy.utils.deprecated sets __deprecated__ and prepends a .. deprecated:: <since> block to the docstring. warnings.deprecated sets __deprecated__ ONLY, so the Sphinx directive is not set.
Now I recall this was one reason I started with this PR, to keep the Sphinx stuff.
I'll work around this and open a PR for discussion.

Well, that went pretty disastrously.

Re: deprecation_message -- Instead of refactoring deprecated, what about you copy out the messaging code into this new function? I suspect you won't need like 95% of the stuff in deprecated to build a message?

#20407 is the current state of the draft.
deprecation uses the new deprecation_msg. It's a nice simplification inside deprecation_msg, and it adds some better error messages for malformed messages.

nstarman added this to the v6.0 milestone Sep 11, 2023

github-actions Bot added utils installation labels Sep 11, 2023

nstarman commented Sep 11, 2023

View reviewed changes

pllim reviewed Sep 11, 2023

View reviewed changes

Comment thread setup.cfg Resolved

nstarman mentioned this pull request Sep 12, 2023

refactor our deprecation machinery #15301

Open

nstarman force-pushed the utils-deprecation branch from 481d58a to b0eafcf Compare September 24, 2023 14:52

nstarman changed the title ~~Switch deprecated internals to typing.deprecated~~ Switch deprecated internals to warnings.deprecated Oct 9, 2023

nstarman added the Python 3.13 label Oct 9, 2023

nstarman modified the milestones: v6.0, v7.0 Oct 14, 2023

github-actions Bot added the Close? Tell stale bot that this issue/PR is stale label Feb 22, 2024

nstarman added keep-open and removed Close? Tell stale bot that this issue/PR is stale labels Feb 22, 2024

astropy deleted a comment from github-actions Bot Feb 22, 2024

pllim modified the milestones: v7.0.0, v7.1.0 Oct 10, 2024

astrofrog modified the milestones: v7.1.0, v7.2.0 Apr 28, 2025

astrofrog modified the milestones: v7.2.0, v8.0.0 Nov 3, 2025

astrofrog modified the milestones: v8.0.0, v8.1.0 May 5, 2026

neutrinoceros reviewed May 17, 2026

View reviewed changes

nstarman force-pushed the utils-deprecation branch from b0eafcf to e6d8061 Compare September 14, 2026 02:01

Switch deprecated internals to warnings.deprecated

ad35931

Signed-off-by: nstarman <[email protected]>

nstarman force-pushed the utils-deprecation branch from e6d8061 to ad35931 Compare September 14, 2026 02:06

nstarman marked this pull request as ready for review September 14, 2026 02:13

pllim reviewed Sep 14, 2026

View reviewed changes

nstarman mentioned this pull request Sep 15, 2026

ENH: machinery for Astropy-style deprecation messages with stdlib deprecated #20407

Draft

1 task done

pllim removed the keep-open label Oct 14, 2026

		return func.__func__ if isinstance(func, _method_types) else func


		def _deprecation_message(alternative, pending):

	between this decorator and `~typing.deprecated`, which are described below.
	between this decorator and `~warnings.deprecated`, which are described below.

Conversation

nstarman commented Sep 11, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Behaviour changes

TODO

Uh oh!

github-actions Bot commented Sep 11, 2023

Uh oh!

github-actions Bot commented Sep 11, 2023

Uh oh!

nstarman commented Sep 11, 2023

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

nstarman commented Sep 25, 2023

Uh oh!

mhvk commented Sep 25, 2023

Uh oh!

nstarman commented Sep 25, 2023

Uh oh!

neutrinoceros commented Sep 25, 2023

Uh oh!

neutrinoceros commented Sep 25, 2023

Uh oh!

mhvk commented Sep 25, 2023

Uh oh!

nstarman commented Sep 26, 2023

Uh oh!

mhvk commented Sep 26, 2023

Uh oh!

nstarman commented May 14, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

pllim commented Jul 20, 2026

Uh oh!

nstarman commented Jul 20, 2026

Uh oh!

neutrinoceros commented Jul 21, 2026

Uh oh!

pllim commented Jul 21, 2026

Uh oh!

neutrinoceros commented Jul 21, 2026

Uh oh!

mhvk commented Jul 21, 2026

Uh oh!

nstarman commented Jul 21, 2026

Uh oh!

astrofrog commented Sep 11, 2026

Uh oh!

nstarman commented Sep 11, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

pllim Sep 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

nstarman commented Sep 11, 2023 •

edited

Loading

pllim Sep 14, 2026 •

edited

Loading