particle_input¶
-
plasmapy.particles.decorators.
particle_input
(wrapped_function: Callable = None, require: Union[str, Set[T], List[T], Tuple] = None, any_of: Union[str, Set[T], List[T], Tuple] = None, exclude: Union[str, Set[T], List[T], Tuple] = None, none_shall_pass: bool = False) → Any¶ Convert arguments to methods and functions to
Particle
objects.Take positional and keyword arguments that are annotated with
Particle
, and pass through theParticle
object corresponding to those arguments to the decorated function or method.Optionally, raise an exception if the particle does not satisfy the specified categorical criteria.
Parameters: - wrapped_function (
callable
) – The function or method to be decorated. - require (
str
,set
,list
, ortuple
, optional) – Categories that a particle must be in. If a particle is not in all of these categories, then anAtomicError
will be raised. - any_of (
str
,set
,list
, ortuple
, optional) – Categories that a particle may be in. If a particle is not in any of these categories, then anAtomicError
will be raised. - exclude (
str
,set
,list
, ortuple
, optional) – Categories that a particle cannot be in. If a particle is in any of these categories, then anAtomicError
will be raised. - none_shall_pass (
bool
, optional) – If set toTrue
, then the decorated argument may be set toNone
without raising an exception. In such cases, this decorator will passNone
through to the decorated function or method. If set toFalse
and the annotated argument is given a value ofNone
, then this decorator will raise aTypeError
.
Notes
If the annotated argument is named
element
,isotope
, orion
, then the decorator will raise anInvalidElementError
,InvalidIsotopeError
, orInvalidIonError
if the particle does not correspond to an element, isotope, or ion, respectively.If exactly one argument is annotated with
Particle
, then the keywordsZ
andmass_numb
may be used to specify the integer charge and/or mass number of an ion or isotope. However, the decorated function must allowZ
and/ormass_numb
as keywords in order to enable this functionality.Raises: TypeError
– If the annotated argument is not astr
,int
,tuple
,list
orParticle
; or ifZ
ormass_numb
is not anint
.ValueError
– If the number of input elements in a collection do not match the number of expected elements.plasmapy/utils/InvalidParticleError
– If the annotated argument does not correspond to a valid particle.plasmapy/utils/InvalidElementError
– If an annotated argument is namedelement
, and the input does not correspond to an element, isotope, or ion.plasmapy/utils/InvalidIsotopeError
– If an annotated argument is namedisotope
, and the input does not correspond to an isotope or an ion of an isotope.plasmapy/utils/InvalidIonError
– If an annotated argument is namedion
, and the input does not correspond to an ion.plasmapy/utils/ChargeError
– If'charged'
is in therequire
argument and the particle is not explicitly charged, or ifany_of = {'charged', 'uncharged'}
and the particle does not have charge information associated with it.plasmapy/utils/AtomicError
– If an annotated argument does not meet the criteria set by the categories in therequire
,any_of
, andexclude
keywords; if more than one argument is annotated andZ
ormass_numb
are used as arguments; or if none of the arguments have been annotated withParticle
.
Examples
The following simple decorated function returns the
Particle
object created from the function’s sole argument:from plasmapy.particles import particle_input, Particle @particle_input def decorated_function(particle: Particle): return particle
This decorator may also be used to accept arguments using tuple annotation containing specific number of elements or using list annotation which accepts any number of elements in an iterable. Returns a tuple of
Particle
:from plasmapy.particles import particle_input, Particle @particle_input def decorated_tuple_function(particles: (Particle, Particle)): return particles sample_particles = decorated_tuple_function(('He', 'Li')) @particle_input def decorated_list_function(particles: [Particle]): return particles sample_particles = decorated_list_function(('Al 3+', 'C')) sample_particles = decorated_list_function(['He', 'Ne', 'Ar'])
This decorator may be used for methods in instances of classes, as in the following example:
from plasmapy.particles import particle_input, Particle class SampleClass: @particle_input def decorated_method(self, particle: Particle): return particle sample_instance = SampleClass() sample_instance.decorated_method('Fe')
Some functions may intended to be used with only certain categories of particles. The
require
,any_of
, andexclude
keyword arguments enable this functionality.from plasmapy.particles import particle_input, Particle @particle_input( require={'matter'}, any_of={'charged', 'uncharged}, exclude={'neutrino', 'antineutrino'}, ) def selective_function(particle: Particle): return particle
- wrapped_function (