Add initial type annotations to unit equivalencies by eerovaher · Pull Request #18001 · astropy/astropy

eerovaher · 2025-04-10T21:49:56Z

Description

I am about to poke around in the unit equivalencies code, so it will be good to have annotations in place.

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 · 2025-04-10T21:50:25Z

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.

eerovaher · 2025-04-10T21:52:54Z

        self.kwargs = [kwargs] if kwargs is not None else [{}]

-    def __add__(self, other):
+    def __add__(self, other: list[Any]) -> list[Any]:


This might not be the best annotation, but I couldn't come up with overloads that agree with list.__add__(), so I decided this is good enough.

eerovaher · 2025-04-10T21:57:02Z

 if TYPE_CHECKING:
    from typing import TypeAlias

+EquivalencyPair: TypeAlias = (


This name is based on the phrasing used in our documentation. For example,

astropy/docs/units/equivalencies.rst

Line 16 in 92b38ae

Equivalencies are used by passing a list of equivalency pairs to the

astropy/astropy/units/equivalencies.py

Lines 107 to 109 in 92b38ae

def parallax():

"""

Returns a list of equivalence pairs that handle the conversion

or

astropy/astropy/units/equivalencies.py

Lines 598 to 600 in 92b38ae

def mass_energy():

"""

Returns a list of equivalence pairs that handle the conversion

nstarman

Looks good! I think there's one partial annotation.

mhvk

Looks good to me, except that the EquivalencyPair type seems too strict.

mhvk · 2025-04-11T20:28:37Z


+EquivalencyPair: TypeAlias = (
+    tuple[UnitBase, UnitBase | None]
+    | tuple[UnitBase, UnitBase, Callable[[npt.NDArray[Any]], npt.NDArray[Any]]]


Equivalency functions also take numbers, or really anything numeric. (A dask array would be fine.) With no guarantee that the same type is returned.

My thinking was that equivalencies are used for converting the value of a Quantity, which is always an ndarray. Is that not the case?

Mostly, it will be used in Quantity, indeed, so mostly it will be ndarray. But equivalencies can also be passed to unit.to and unit.get_converter, and then the callables are used more directly (well, via _condition_arg). See the first example on https://docs.astropy.org/en/latest/units/conversion.html but imaging an equivalency is used, is in,

u.one.to(u.arcsec, 1., equivalencies=u.dimensionless_angles()) # 206264.80624709636

Note that _condition_arg was refactored a short while ago to pass along anything with a .dtype, like a dask array. This was specifically to allow unit coversion with turning everything in ndarray.

Mostly, it will be used in Quantity, indeed, so mostly it will be ndarray. But equivalencies can also be passed to unit.to and unit.get_converter, and then the callables are used more directly (well, via _condition_arg). See the first example on https://docs.astropy.org/en/latest/units/conversion.html but imaging an equivalency is used, is in,

u.one.to(u.arcsec, 1., equivalencies=u.dimensionless_angles()) # 206264.80624709636

It should not be too difficult to replace npt.NDArray[Any] with npt.NDArray[Any] | UnitScale or npt.NDArray[Any] | UnitScaleLike.

Note that _condition_arg was refactored a short while ago to pass along anything with a .dtype, like a dask array. This was specifically to allow unit coversion with turning everything in ndarray.

Are you sure that this functionality works as intended with all the equivalencies? Have you tested it with logarithmic, parallax or doppler_redshift?

What's the simplest solution for proceeding?
A HasShape temporary protocol?

Just don't narrow Callable down for now and add a TODO?

github-actions · 2025-09-08T05:45:11Z

Hi humans 👋 - 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.

github-actions · 2026-10-16T05:44:20Z

Hi humans 👋 - this pull request hasn't had any new commits for approximately 1 year, 6 months. I plan to close this in a month 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.

Add initial type annotations to unit equivalencies

9e473a1

eerovaher added units no-changelog-entry-needed typing related to type annotations labels Apr 10, 2025

eerovaher added this to the v7.1.0 milestone Apr 10, 2025

eerovaher requested review from mhvk and nstarman April 10, 2025 21:49

github-actions Bot added the Docs label Apr 10, 2025

eerovaher commented Apr 10, 2025

View reviewed changes

nstarman reviewed Apr 11, 2025

View reviewed changes

Comment thread astropy/units/equivalencies.py Resolved

mhvk reviewed Apr 11, 2025

View reviewed changes

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

github-actions Bot added the Close? Tell stale bot that this issue/PR is stale label Sep 8, 2025

nstarman added keep-open and removed Close? Tell stale bot that this issue/PR is stale labels Sep 9, 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

pllim removed the keep-open label Oct 14, 2026

github-actions Bot added the Close? Tell stale bot that this issue/PR is stale label Oct 15, 2026

	def parallax():
	"""
	Returns a list of equivalence pairs that handle the conversion

	def mass_energy():
	"""
	Returns a list of equivalence pairs that handle the conversion

Conversation

eerovaher commented Apr 10, 2025

Description

Uh oh!

github-actions Bot commented Apr 10, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nstarman left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

mhvk left a comment

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!

github-actions Bot commented Sep 8, 2025

Uh oh!

github-actions Bot commented Oct 16, 2026

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants