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:

• Warnings and exceptions used in PlasmaPy, such as RelativityWarning or PhysicsError.

• Decorators we use for reusable physical Quantity computation and checking, such as validate_quantities and check_relativistic.

• Helper utilities for importing and testing packages.

• Functionality for downloading files from PlasmaPy’s data repository.

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	Decorators to convert units.
deprecation	Decorators to mark objects that are deprecated.
helpers	Miscellaneous decorators for various package uses.
lite_func	Module for defining functionality that marks and handle Lite-Function creation.
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.

Functions

angular_freq_to_hz(fn)	A decorator that enables a function to convert its return value from angular frequency (rad/s) to frequency (Hz).
bind_lite_func(lite_func[, attrs])	Decorator to bind a lightweight "lite" version of a formulary function to the full formulary function, as well as any supporting attributes.
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_class_attributes([...])	A decorator responsible for raising errors if the expected arguments weren't provided during class instantiation.
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.

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.

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.

plasmapy.utils.calculator Package

Subpackage formerly containing a prototype plasma calculator.

Important

The plasma calculator has been removed from PlasmaPy so that it can be included in the plasmapy-calculator standalone package.

Functions

main()

Plasma calculator.

plasmapy.utils.data Package

The plasmapy.utils.data subpackage contains functionality for downloading and retrieving data files.

Sub-Packages & Modules

downloader

Contains functionality for downloading files from a URL.

Classes

Downloader([directory, validate, api_token])

Accesses the PlasmaPy resource files.

Variables & Attributes

_API_CONNECTION_ESTABLISHED

Returns True when the argument is true, False otherwise.