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.

    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

checks

Requested checks on the decorated function's input arguments and/or return.

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

checks

Requested checks on the decorated function’s input arguments and/or return.

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