Unit-Aware Type Annotations#

Python supports static type analysis using the type syntax of PEP 484. For a detailed guide on type hints, function annotations, and other related syntax see the Real Python Guide. Below we describe how you can be use Quantity type hints and annotations and also include metadata about the associated units.

We assume the following imports:

>>> import typing as T
>>> import astropy.units as u
>>> from astropy.units import Quantity

Quantity Type Annotation#

A Quantity can be used as a type annotation,:

>>> x: Quantity = 2 * u.km

or as a function annotation.:

>>> def func(x: Quantity) -> Quantity:
...     return x

Preserving Units#

While the above annotations are useful for annotating the value’s type, it does not inform us of the other most important attribute of a Quantity: the unit.

Unit information may be included by the syntax Quantity[unit or "physical_type", shape, numpy.dtype].:

>>> Quantity[u.m]
typing.Annotated[astropy.units.quantity.Quantity, Unit("m")]
>>>
>>> Quantity["length"]
typing.Annotated[astropy.units.quantity.Quantity, PhysicalType('length')]

See typing.Annotated for explanation of Annotated

These can also be used on functions

>>> def func(x: Quantity[u.kpc]) -> Quantity[u.m]:
...     return x << u.m

Multiple Annotations#

Multiple Quantity and unit-aware Quantity annotations are supported using Union or Optional (including | operations).

>>> Quantity[u.m] | None
typing.Optional[typing.Annotated[astropy.units.quantity.Quantity, Unit("m")]]
>>>
>>> Quantity[u.m] | Quantity["time"]
typing.Union[typing.Annotated[astropy.units.quantity.Quantity, Unit("m")],
             typing.Annotated[astropy.units.quantity.Quantity, PhysicalType('time')]]

Type Annotations Module#

Typing module for supporting type annotations related to units.

astropy.units.typing.QuantityLike#

Type alias for a quantity-like object.

This is an object that can be converted to a Quantity object using the Quantity() constructor.

Examples

We assume the following imports:

>>> from astropy import units as u

This is a non-exhaustive list of examples of quantity-like objects:

Integers and floats:

>>> u.Quantity(1, u.meter)
<Quantity 1.0 m>

>>> u.Quantity(1.0, u.meter)
<Quantity 1.0 m>

Lists and tuples:

>>> u.Quantity([1.0, 2.0], u.meter)
<Quantity [1., 2.] m>

>>> u.Quantity((1.0, 2.0), u.meter)
<Quantity [1., 2.] m>

Numpy arrays:

>>> u.Quantity(np.array([1.0, 2.0]), u.meter)

Quantity objects:

>>> u.Quantity(u.Quantity(1.0, u.meter))
<Quantity 1.0 m>

Strings:

>>> u.Quantity('1.0 m')
<Quantity 1.0 m>

For more examples see the numpy.typing definition of numpy.typing.ArrayLike.