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)
seeastropy.units.Quantity.to_value
- equivalencies: list, optional
equivalencies for
.to()
and.to_value()
only used ifunit
toto_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 applyunit
,to_value
,equivalencies
.
Decomposing then converting wastes time, since
.to(unit, equivalencies)
internally does conversions. The only use for combiningdecompose
with otherquantity_return_
parameters is withunit=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 inUnit()
. 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:
Function Arguments
Decorator Arguments
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 thanassumed_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
Notes
{notes}