pint_xarray.expects

pint_xarray.expects(*args_units, return_value=None, **kwargs_units)

Decorator which ensures the inputs and outputs of the decorated function are expressed in the expected units.

Arguments to the decorated function are checked for the specified units, converting to those units if necessary, and then stripped of their units before being passed into the undecorated function. Therefore the undecorated function should expect unquantified DataArrays, Datasets, or numpy-like arrays, but with the values expressed in specific units.

Parameters:

  • func (callable) – Function to decorate, which accepts zero or more xarray.DataArrays or numpy-like arrays as inputs, and may optionally return one or more xarray.DataArrays or numpy-like arrays.

  • *args_units (unit-like or mapping of hashable to unit-like, optional) – Units to expect for each positional argument given to func.

    The decorator will first check that arguments passed to the decorated function possess these specific units (or will attempt to convert the argument to these units), then will strip the units before passing the magnitude to the wrapped function.

    A value of None indicates not to check that argument for units (suitable for flags and other non-data arguments).

  • return_value (unit-like or list of unit-like or mapping of hashable to unit-like or list of mapping of hashable to unit-like, optional) – The expected units of the returned value(s), either as a single unit or as a list of units. The decorator will attach these units to the variables returned from the function.

    A value of None indicates not to attach any units to that return value (suitable for flags and other non-data results).

  • **kwargs_units (mapping of hashable to unit-like, optional) – Unit to expect for each keyword argument given to func.

    The decorator will first check that arguments passed to the decorated function possess these specific units (or will attempt to convert the argument to these units), then will strip the units before passing the magnitude to the wrapped function.

    A value of None indicates not to check that argument for units (suitable for flags and other non-data arguments).

Returns:

return_values – Return values of the wrapped function, either a single value or a tuple of values. These will be given units according to return_value.

Return type:

Any

Raises:

  • TypeError – If any of the units are not a valid type.

  • ValueError – If the number of arguments or return values does not match the number of units specified. Also thrown if any parameter does not have a unit specified.

See also

pint.wraps

Examples

Decorating a function which takes one quantified input, but returns a non-data value (in this case a boolean).

>>> @expects("deg C")
... def above_freezing(temp):
...     return temp > 0
...

Decorating a function which allows any dimensions for the array, but also accepts an optional weights keyword argument, which must be dimensionless.

>>> @expects(None, weights="dimensionless")
... def mean(da, weights=None):
...     if weights:
...         return da.weighted(weights=weights).mean()
...     else:
...         return da.mean()
...