QuantityInputOutput

class astronat.units.QuantityInputOutput(function: Optional[Callable] = None, unit: Optional[utilipy.utils.typing.UnitableType] = None, to_value: bool = False, equivalencies: Sequence = [], decompose: Union[bool, Sequence] = False, assumed_units: dict = {}, assume_annotation_units: bool = False, **decorator_kwargs)[source]

Bases: object

Decorator for validating the units of arguments to functions.

Decorator for validating the units of arguments to functions.

Parameters
function: Callable

the function to decorate (default None)

unit: :class:`~astropy.units.Unit`, optional

sets the unit for the returned value. if None, returns value unchanged, unless to_value is used if blank string, decomposes

to_value: bool, optional

whether to return .to_value(unit) see astropy.units.Quantity.to_value

equivalencies: list, optional

equivalencies for .to() and .to_value() only used if unit to to_value are not None/False

decompose: bool or list, optional

Unit decomposition. Default, False.

  • bool: True, False for decomposing.

  • list: bases for .decompose(bases=[]). Will first decompose, then apply unit, to_value, equivalencies.

Decomposing then converting wastes time, since .to(unit, equivalencies) internally does conversions. The only use for combining decompose with other quantity_return_ parameters is with

unit=None, to_value=True, equivalencies=[]

since this will decompose to desired bases then return the value in those bases

Note

experimental feature: for things which are not (Unit), tries wrapping in Unit(). This would normally return an error, but now allows for conversions such as:

>>> x = 10 * u.km * u.s
>>> bases = [u.Unit(2 * u.km), u.s]
>>> x.decompose(bases=bases) 
<Quantity 5.0 2 km s>
assumed_units: dict

dictionary of default units (default dict())

>>> from astronat.units.decorators import quantity_io
>>> dfu = dict(x=u.km)
>>> x = 10
>>> y = 20*u.km
>>> @quantity_io(assumed_units=dfu)
... def add(x, y):
...     return x + y
>>> add(x, y) 
<Quantity 30.0 km>
assume_annotation_units: bool, optional

whether to interpret function annotations as default units (default False) function annotations have lower precedence than assumed_units

Notes

Order of Precedence:

  1. Function Arguments

  2. Decorator Arguments

  3. Function Annotation Arguments

Decorator Key-Word Arguments:

Unit specifications can be provided as keyword arguments to the decorator, or by using function annotation syntax. Arguments to the decorator take precedence over any function annotations present. note decorator key-word arguments are NEVER interpreted as assumed_units

>>> from astronat.units.decorators import quantity_io
>>> @quantity_io(x=u.m, y=u.s)
... def func(x, y):
...     pass

Function Annotation Arguments:

Unit specifications can be provided as keyword arguments to the decorator, or by using function annotation syntax. Arguments to the function and decorator take precedence over any function annotations present.

>>> def func(x: u.m, y: u.s) -> u.m / u.s:
...     pass

if assume_annotation_units is True (default False) function annotations are interpreted as default units function annotations have lower precedence than assumed_units

Methods Summary

__call__(wrapped_function)

Make decorator.

as_decorator([function, unit, to_value, …])

Decorator for validating the units of arguments to functions.

Methods Documentation

__call__(wrapped_function: Callable)[source]

Make decorator.

Parameters
wrapped_functionCallable

function to wrap

Returns
wrapped: Callable

wrapped function

classmethod as_decorator(function: Optional[Callable] = None, unit: Optional[utilipy.utils.typing.UnitableType] = None, to_value: bool = False, equivalencies: Sequence = [], decompose: Union[bool, Sequence] = False, assumed_units: Dict = {}, assume_annotation_units: bool = False, **decorator_kwargs)[source]

Decorator for validating the units of arguments to functions.

Parameters
{parameters}

See also

quantity_input

Notes

{notes}