ValidateQuantities¶
-
class
plasmapy.utils.decorators.validators.
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 [DEFAULTNone
] A list of equivalent pairs to try ifthe units are not directly convertible.(seeequivalencies
, and/or astropy equivalencies)pass_equivalent_units bool
[DEFAULTFalse
] allow equivalent unitsto passcan_be_negative bool
[DEFAULT True
] values can be negativecan_be_complex bool
[DEFAULT False
] values can be complex numberscan_be_inf bool
[DEFAULT True
] values can beinf
can_be_nan bool
[DEFAULT True
] values can benan
none_shall_pass bool
[DEFAULT False
] values can be a pythonNone
Notes
- Validation of function arguments
*args
and**kwargs
is not supported. None
values will pass whenNone
is included in the list of specified units, is set as a default value for the function argument, ornone_shall_pass
is set toTrue
. Ifnone_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