Skip to main content
`Ctrl`+`K`

# 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`.

  alias of `astropy.units.Quantity` | `Buffer` | `_SupportsArray`[`dtype`[`Any`]] | `_NestedSequence`[`_SupportsArray`[`dtype`[`Any`]]] | `complex` | `bytes` | `str` | `_NestedSequence`[`complex` | `bytes` | `str`]

astropy.units.typing.UnitLike

  Type alias for input that can be converted to a Unit.

  See unit-like. Note that this includes only scalar quantities.

  alias of `astropy.units.UnitBase` | `str` | `astropy.units.Quantity`

astropy.units.typing.UnitPower = int | float | fractions.Fraction

  Alias for types that can be powers of the components of a `UnitBase` instance

astropy.units.typing.UnitPowerLike = int | float | fractions.Fraction | numpy.integer | numpy.floating

  Alias for types that can be used to create powers of the components of a `UnitBase` instance

astropy.units.typing.UnitScale = float | complex

  Alias for types that can be scale factors of a `CompositeUnit`

astropy.units.typing.UnitScaleLike = float | complex | int | fractions.Fraction | numpy.number

  Alias for types that can be used to create scale factors of a `CompositeUnit`