ValidateQuantities

class plasmapy.utils.decorators.ValidateQuantities(validations_on_return=None, **validations)

Bases: plasmapy.utils.decorators.checks.CheckUnits, plasmapy.utils.decorators.checks.CheckValues

A decorator class to ‘validate’ – control and convert – the units and values of input and return arguments to a function or method. Arguments are expected to be astropy Quantity objects.

Parameters:
  • validations_on_return (dictionary of validation specifications) – Specifications for unit and value validations on the return of the function being wrapped. (see quantity validations for valid specifications.
  • **validations (dictionary of validation specifications) –

    Specifications for unit and value validations on the input arguments of the function being wrapped. Each keyword argument in validations is the name of a function argument to be validated and the keyword value contains the unit and value validation specifications.

    Unit and value validations can be defined by passing one of the astropy units, a list of astropy units, or a dictionary containing the keys defined below. Units can also be defined with function annotations, but must be consistent with decorator **validations arguments if used concurrently. If a key is omitted, then the default value will be assumed.

    Key Type Description
    units   list of desired astropy units
    equivalencies  
    [DEFAULT None] A list of equivalent pairs to try if
    the units are not directly convertible.
    pass_equivalent_units bool
    [DEFAULT False] allow equivalent units
    to pass
    can_be_negative bool [DEFAULT True] values can be negative
    can_be_complex bool [DEFAULT False] values can be complex numbers
    can_be_inf bool [DEFAULT True] values can be inf
    can_be_nan bool [DEFAULT True] values can be nan
    none_shall_pass bool [DEFAULT False] values can be a python None

Notes

  • Validation of function arguments *args and **kwargs is not supported.
  • None values will pass when None is included in the list of specified units, is set as a default value for the function argument, or none_shall_pass is set to True. If none_shall_pass is doubly/triply defined through the mentioned options, then they all must be consistent with each other.
  • If units are not specified in validations, then the decorator will attempt to identify desired units by examining the function annotations.

Examples

Define unit and value validations with decorator parameters:

import astropy.units as u
from plasmapy.utils.decorators import ValidateQuantities

@ValidateQuantities(mass={'units': u.g,
                          'can_be_negative': False},
                    vel=u.cm / u.s,
                    validations_on_return=[u.g * u.cm / u.s, u.kg * u.m / u.s])
def foo(mass, vel):
    return mass * vel

# on a method
class Foo:
    @ValidateQuantities(mass={'units': u.g,
                              'can_be_negative': False},
                        vel=u.cm / u.s,
                        validations_on_return=[u.g * u.cm / u.s,
                                               u.kg * u.m / u.s])
    def bar(self, mass, vel):
        return mass * vel

Define units with function annotations:

import astropy.units as u
from plasmapy.utils.decorators import ValidateQuantities

@ValidateQuantities(mass={'can_be_negative': False})
def foo(mass: u.g, vel: u.cm / u.s) -> u.g * u.cm / u.s:
    return mass * vel

# on a method
class Foo:
    @ValidateQuantities(mass={'can_be_negative': False})
    def bar(self, mass: u.g, vel: u.cm / u.s) -> u.g * u.cm / u.s:
        return mass * vel

Allow None values to pass:

import astropy.units as u
from plasmapy.utils.decorators import ValidateQuantities

@ValidateQuantities(checks_on_return=[u.cm, None])
def foo(arg1: u.cm = None):
    return arg1

Allow return values to have equivalent units:

import astropy.units as u
from plasmapy.utils.decorators import ValidateQuantities

@ValidateQuantities(arg1={'units': u.cm},
                    checks_on_return={'units': u.km,
                                      'pass_equivalent_units': True})
def foo(arg1):
    return arg1

Allow equivalent units to pass with specified equivalencies:

import astropy.units as u
from plasmapy.utils.decorators import ValidateQuantities

@ValidateQuantities(arg1={'units': u.K,
                          'equivalencies': u.temperature(),
                          'pass_equivalent_units': True})
def foo(arg1):
    return arg1

Attributes Summary

validations Requested validations on the decorated function’s input arguments and return variable.

Methods Summary

__call__(f)
param f:Function to be wrapped

Attributes Documentation

validations

Requested validations on the decorated function’s input arguments and return variable.

Methods Documentation

__call__(f)
Parameters:f – Function to be wrapped
Returns:wrapped function of f
Return type:function