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.

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.

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).

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.

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.

plasmapy.utils.calculator Package

Script and utilities to launch the plasma calculator

Functions

main()

Stub function for command line tool that launches the plasma calculator notebook.

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.

Functions

get_file(basename[, base_url, directory])

Download a file from a URL (if the file does not already exist) and return the full local path to the file.