ValidateQuantities

class plasmapy.utils.decorators.validators.ValidateQuantities(validations_on_return=None, **validations: Dict[str, Any])

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. (see equivalencies, and/or astropy equivalencies)
  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
  can_be_zero	bool	[DEFAULT True] values can be zero

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