Core package utilities (plasmapy.utils)

Introduction

The utils subpackage contains functionality that is needed across multiple subpackages or does not fit nicely in any other subpackage. Functionality contained in utils includes:

API

plasmapy.utils.decorators Package

A module to contain various decorators used to build readable and useful code.

Sub-Packages & Modules

checks

Decorator for checking input/output arguments of functions.

converter

Decorator to convert units of functions in /physics methods

deprecation

Decorators to mark objects that are deprecated.

helpers

Miscellaneous decorators for various package uses.

validators

Various decorators to validate input/output arguments to functions.

Classes

CheckBase([checks_on_return])

Base class for 'Check' decorator classes.

CheckUnits([checks_on_return])

A decorator class to 'check' -- limit/control -- the units of input and return arguments to a function or method.

CheckValues([checks_on_return])

A decorator class to 'check' -- limit/control -- the values of input and return arguments to a function or method.

ValidateQuantities([validations_on_return])

A decorator class to 'validate' -- control and convert -- the units and values of input and return arguments to a function or method.

Inheritance diagram of plasmapy.utils.decorators.checks.CheckBase, plasmapy.utils.decorators.checks.CheckUnits, plasmapy.utils.decorators.checks.CheckValues, plasmapy.utils.decorators.validators.ValidateQuantities

Functions

angular_freq_to_hz(fn)

A decorator that adds to a function the ability to convert the function's return from angular frequency (rad/s) to frequency (Hz).

check_relativistic([func, betafrac])

Warns or raises an exception when the output of the decorated function is greater than betafrac times the speed of light.

check_units([func, checks_on_return])

A decorator to 'check' -- limit/control -- the units of input and return arguments to a function or method.

check_values([func, checks_on_return])

A decorator to 'check' -- limit/control -- the values of input and return arguments to a function or method.

deprecated(since[, message, name, ...])

A wrapper of astropy.utils.decorators.deprecated that by default assumes a warning type of PlasmaPyDeprecationWarning.

modify_docstring([func, prepend, append])

A decorator which programmatically prepends and/or appends the docstring of the decorated method/function.

preserve_signature(f)

A decorator for decorators, which preserves the signature of the function being wrapped.

validate_quantities([func, ...])

A decorator to 'validate' -- control and convert -- the units and values of input and return arguments to a function or method.

plasmapy.utils.exceptions Module

Exceptions and warnings specific to PlasmaPy.

Exceptions

InvalidRomanNumeralError

An exception to be raised when the input is not a valid Roman numeral.

OutOfRangeError

An exception to be raised for integers that outside of the range that can be converted to Roman numerals.

PhysicsError

The base exception for physics-related errors.

PlasmaPyError

Base class of PlasmaPy custom errors.

RelativityError

An exception for speeds greater than the speed of light.

RomanError

A base exception for errors from plasmapy.utils.roman.

Inheritance diagram of plasmapy.utils.exceptions.InvalidRomanNumeralError, plasmapy.utils.exceptions.OutOfRangeError, plasmapy.utils.exceptions.PhysicsError, plasmapy.utils.exceptions.PlasmaPyError, plasmapy.utils.exceptions.RelativityError, plasmapy.utils.exceptions.RomanError

Warnings

CouplingWarning

A warning for functions that rely on a particular coupling regime to be valid.

PhysicsWarning

The base warning for warnings related to non-physical situations.

PlasmaPyDeprecationWarning

A warning for deprecated features when the warning is intended for other Python developers.

PlasmaPyFutureWarning

A warning for deprecated features when the warning is intended for end users of PlasmaPy.

PlasmaPyWarning

Base class of PlasmaPy custom warnings.

RelativityWarning

A warning for when relativistic velocities are being used in or are returned by non-relativistic functionality.

Inheritance diagram of plasmapy.utils.exceptions.CouplingWarning, plasmapy.utils.exceptions.PhysicsWarning, plasmapy.utils.exceptions.PlasmaPyDeprecationWarning, plasmapy.utils.exceptions.PlasmaPyFutureWarning, plasmapy.utils.exceptions.PlasmaPyWarning, plasmapy.utils.exceptions.RelativityWarning

plasmapy.utils.code_repr Module

Tools for formatting strings, including for error messages.

Functions

attribute_call_string(cls, attr[, ...])

Approximate the command to instantiate a class, and access an attribute of the resulting class instance.

call_string(f[, args, kwargs, max_items])

Approximate a call of a function or class with positional and keyword arguments.

method_call_string(cls, method, *[, ...])

Approximate the command to instantiate a class, and then call a method in the resulting class instance.