ENH: machinery for Astropy-style deprecation messages with stdlib `deprecated` by nstarman · Pull Request #20407 · astropy/astropy

nstarman · 2026-09-15T15:25:34Z

Trying an alternative starting point to #15307

Things I found:

deprecation_msg needs the function name, which is a little inconvenient.
astropy.utils.deprecated does docstring manipulation, so I needed to add another decorator that handles that.
This construction works with static type checkers, but is more lines of code at the deprecation site than astropy.utils.deprecated :(
I don't think I did the Check environment lowest resolution against reference (pull_request) correctly...

AI Disclosure

Claude Code to help with the refactors, and then to clean up my 20+ commit history into something reasonable.
And to write the docstrings / changelog.

I certify that I am human and that I take full responsibility for this pull request including all interactions with reviewers.

Merge method

github-actions · 2026-09-15T15:25:48Z

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?
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.

Factor the message building of the ``@deprecated`` decorator into a public ``deprecation_msg`` function, so that the identical message can be produced without the decorator, e.g. ``warnings.deprecated(deprecation_msg(...))``. A custom ``message`` is now validated. An unsupported format specifier previously failed with a bare ``KeyError`` from ``str.format``, and an ``alternative`` that the message never interpolates was silently dropped; both now raise a ``ValueError`` naming the supported specifiers. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Signed-off-by: nstarman <nstarman@users.noreply.github.com>

…ated`` Factor the docstring handling out of ``@deprecated`` into a public ``deprecate_doc`` decorator, which takes the deprecation message from the object's ``__deprecated__`` attribute. It can therefore document objects deprecated by ``warnings.deprecated``, which sets that attribute but leaves the docstring alone. ``warnings.deprecated`` is typed as taking a ``LiteralString``, so overload ``deprecation_msg`` to return one when every argument is a literal, while the runtime ``str`` that ``@deprecated`` itself passes still gives a ``str``. Also annotate the return type of ``deprecated`` itself. It was ``Callable``, which erased the signature of whatever it decorated; it now returns ``Callable[[T], T]``, or the deprecated function for the call that passes one as ``message``. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

``warnings.deprecated`` is only available from Python 3.13 onwards, so ``typing_extensions`` is needed to provide it on 3.12. It is also a build requirement because ``setup.py`` imports ``astropy.units`` in the isolated build environment to generate the unit type stubs, the same reason ``pyerfa`` is listed there. Key ``min_versions`` in the docs configuration by canonical name, so the lookup does not depend on whether the requirement is recorded with a hyphen or an underscore. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Signed-off-by: nstarman <nstarman@users.noreply.github.com>

Move every ``@deprecated`` use in ``astropy.cosmology`` onto ``warnings.deprecated`` (PEP 702), combining ``deprecation_msg`` for the message and ``deprecate_doc`` for the ``.. deprecated::`` directive. Type checkers report uses of an object deprecated this way, which astropy's own decorator cannot express. The messages and warning categories are unchanged: each site passes the ``obj_type`` that the decorator used to infer, and the category it used to issue. In ``representation/base.py`` the ``classmethod`` had to become the outer decorator, since the standard library decorator rejects a classmethod object. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Signed-off-by: nstarman <nstarman@users.noreply.github.com>

neutrinoceros · 2026-09-15T15:57:30Z

uv run scripts/check-lowest-resolved-tree.py --overwrite (--quiet)

nstarman · 2026-09-15T16:03:23Z

Sign in to view

+            message="Use ``angular_diameter_distance(z1, z2)`` instead.",
+            obj_type="function",
+        ),
+        category=AstropyDeprecationWarning,


As an API change I'm happy to drop this argument. I don't think any users are filtering for only Astropy deprecations.

hard to tell. In any case this should be done piecemeal, so this part would go to another PR

pllim · 2026-09-15T19:07:35Z

 for line in metadata.requires("astropy"):
    req = Requirement(line.split(";")[0])
-    min_versions[req.name.lower()] = str(req.specifier)
+    min_versions[canonicalize_name(req.name)] = str(req.specifier)


Why this change? Seem unrelated.

typing extensions was complaining.

You mean a type checker ?

Sorry. I meant it was complaining about typing_extensions.

I don't think this is a one-to-one replacement. https://packaging.pypa.io/en/stable/utils.html#packaging.utils.canonicalize_name does more than just lowercase.

is it typing-extensions or typing_extensions, only the canonicalized may know.

This discussion triggered my motivation to learn more about packaging APIs, here's the result: #20414

Great. We can wait on that PR to merge before rebasing and simplifying this one.

pllim · 2026-09-15T19:10:41Z

+specifier, or passing ``alternative`` without referencing ``{alternative}`` in
+the message (which silently dropped it), raises a ``ValueError``.
+
+Added ``astropy.utils.decorators.deprecate_doc``, a decorator that prepends a


This one is confusing. Is it useful beyond internal usage during transitional period? Should this be private?

agreed. Any new API needed for this PR should be private. We can always consider promoting them later if anyone downstream actually needs them.

Sure. But private in which way: not listed in "all" or underscore-prefixed?

We don't often import underscore-prefixed functions across modules.

But private in which way

That is for your APE to figure out. 😅 As far as I am concern, private in a way we can use internally and then remove without deprecation. 😸

Lol. The problem is my APE did figure it out. Folks just didn't like the implied consequences. There is no good way for me to write this as reasonable private functions at this moment. Underscore-prefixes aren't imported across modules in Astropy and just removing it from __all__ will not dissuade people from using it on discovery, leading to deprecations-before-removal.
I'm fine doing either way since both are broken.

(I challenge anyone to find unclear public vs private API in https://github.com/GalacticDynamics/unxt or https://github.com/GalacticDynamics/coordinax/)

IMO since I think this will probably end up being public, making it look-public-but-it's-actually-not-in-__all__ is probably the better choice.

pllim · 2026-09-15T19:15:38Z

At a glance, the diff isn't too shocking. I can do a more careful review once current concerns are addressed and CI is green. Thanks!

github-actions Bot added Docs cosmology utils installation labels Sep 15, 2026

github-project-automation Bot added this to Cosmology, the Expansion Sep 15, 2026

github-project-automation Bot moved this to Triage in Cosmology, the Expansion Sep 15, 2026

nstarman and others added 4 commits September 15, 2026 11:25

nstarman force-pushed the utils/deprecation-msg branch from 5ee28a1 to f660e04 Compare September 15, 2026 15:26

nstarman added this to the v8.1.0 milestone Sep 15, 2026

nstarman changed the title ~~Utils/deprecation msg~~ ENH: machinery for Astropy-style deprecation messages on stdlib deprecated Sep 15, 2026

nstarman changed the title ~~ENH: machinery for Astropy-style deprecation messages on stdlib deprecated~~ ENH: machinery for Astropy-style deprecation messages with stdlib deprecated Sep 15, 2026

nstarman mentioned this pull request Sep 15, 2026

Switch deprecated internals to warnings.deprecated #15307

Open

2 tasks

nstarman commented Sep 15, 2026

View reviewed changes

pllim reviewed Sep 15, 2026

View reviewed changes

Comment thread docs/conf.py Outdated

pllim reviewed Sep 15, 2026

View reviewed changes

Comment thread astropy/utils/decorators.py

Address PR review

588c76a

neutrinoceros requested changes Sep 15, 2026

View reviewed changes

Comment thread scripts/lowest-resolved-tree.txt

github-project-automation Bot moved this from Triage to Review in progress in Cosmology, the Expansion Sep 15, 2026

BLD: update typing_extensions requirement to 4.10 for Python < 3.13

7e397b5

nstarman requested a review from neutrinoceros September 15, 2026 20:40

neutrinoceros mentioned this pull request Sep 16, 2026

DOC/ENH: distinguish missing packages from installed ones with incompatible versions in docs/conf.py #20414

Merged

2 tasks

Uh oh!

Conversation

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

Uh oh!

AI Disclosure

Merge method

Uh oh!

github-actions Bot commented Sep 15, 2026

Uh oh!

neutrinoceros commented Sep 15, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This comment was marked as resolved.

Uh oh!

This comment was marked as resolved.

Uh oh!

This comment was marked as resolved.

Uh oh!

Uh oh!

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!

neutrinoceros Sep 16, 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!

nstarman Sep 15, 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!

Uh oh!

pllim commented Sep 15, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

nstarman commented Sep 15, 2026 •

edited

Loading

neutrinoceros Sep 16, 2026 •

edited

Loading

nstarman Sep 15, 2026 •

edited

Loading