Astropy Core Package Utilities (astropy.utils
)¶
Introduction¶
The astropy.utils
package contains general-purpose utility functions and
classes. Examples include data structures, tools for downloading and caching
from URLs, and version intercompatibility functions.
This functionality is not astronomy-specific, but is intended primarily for use by Astropy developers. It is all safe for users to use, but the functions and classes are typically more complicated or specific to a particular need of Astropy.
Because of the mostly standalone and grab-bag nature of these utilities, they are generally best understood through their docstrings, and hence this documentation generally does not have detailed sections like the other packages. The exception is below:
Note
The astropy.utils.compat
subpackage is not included in this
documentation. It contains utility modules for compatibility with
older/newer versions of python and numpy, as well as including some
bugfixes for the stdlib that are important for Astropy. It is recommended
that developers at least glance over the source code for this subpackage,
but most of it cannot be reliably included here because of the large
amount of version-specific code it contains. For numpy, however, there are
instructions on how to deal with issues of
compatibility between different versions.
Reference/API¶
astropy.utils.codegen Module¶
Utilities for generating new Python code at runtime.
Functions¶
|
Make a new function from an existing function but with the desired signature. |
astropy.utils.collections Module¶
A module containing specialized collection classes.
Classes¶
|
A subclass of list that contains only elements of a given type or types. |
astropy.utils.console Module¶
Utilities for console input and output.
Functions¶
|
Returns |
|
Prints colors and styles to the terminal uses ANSI escape sequences. |
|
Returns a human-friendly time string that is always exactly 6 characters long. |
|
Returns a human-friendly string representing a file size that is 2-4 characters long. |
|
Prints a line of source code, highlighting a particular character position in the line. |
|
Returns a tuple (height, width) containing the height and width of the terminal. |
Classes¶
|
A class to display a progress bar in the terminal. |
|
A class to display a spinner in the terminal. |
|
A class that displays either a |
astropy.utils.data_info Module¶
This module contains functions and methods that relate to the DataInfo class which provides a container for informational attributes as well as summary info methods.
A DataInfo object is attached to the Quantity, SkyCoord, and Time classes in astropy. Here it allows those classes to be used in Tables and uniformly carry table column attributes such as name, format, dtype, meta, and description.
Functions¶
|
Factory to create a function that can be used as an |
|
Return a human-oriented string name of the |
Classes¶
|
Base info class for anything that can be a column in an astropy Table. |
|
Descriptor that data classes use to add an |
|
|
|
Mixin that gets info.dtype from parent |
astropy.utils.decorators Module¶
Sundry function and class decorators.
Functions¶
|
Used to mark a function or class as deprecated. |
|
Used to mark a public attribute as deprecated. |
|
Deprecate a _renamed_ or _removed_ function argument. |
|
Replaces the docstring of the decorated object and then formats it. |
Classes¶
|
Similar to |
|
Works similarly to property(), but computes the value only once. |
This is a method decorator that allows both an instancemethod and a |
astropy.utils.diff Module¶
Functions¶
|
Diff two scalar values. |
|
Write a diff report between two values to the specified file-like object. |
|
A version of |
astropy.utils.exceptions Module¶
This module contains errors/exceptions and warnings of general use for astropy. Exceptions that are specific to a given subpackage should not be here, but rather in the particular subpackage. Exception is the _erfa module as we rather have the users import those exceptions from here.
Classes¶
A warning class indicating a change in astropy that is incompatible with previous versions. |
|
A warning class to indicate a deprecated feature. |
|
A warning class to indicate a soon-to-be deprecated feature. |
|
The primary warning class for Astropy. |
|
The base warning class from which all Astropy warnings should inherit. |
|
A class for errors triggered by ERFA functions (status codes < 0) |
|
A class for warnings triggered by ERFA functions (status codes > 0) |
astropy.utils.iers Package¶
Classes¶
Configuration parameters for |
|
|
Generic IERS table class, defining interpolation functions. |
Any error for when dates are outside of the valid range for IERS |
|
|
IERS Table class targeted to IERS A, provided by USNO. |
|
Provide most-recent IERS data and automatically handle downloading of updated values as necessary. |
|
IERS Table class targeted to IERS B, provided by IERS itself. |
astropy.utils.introspection Module¶
Functions related to Python runtime introspection.
Functions¶
|
Resolve a name like |
|
Returns |
|
Determines the module/package from which this function is called. |
|
Returns |
astropy.utils.metadata Module¶
This module contains helper functions and classes for handling metadata.
Functions¶
|
Use numpy to find the common dtype for a list of ndarrays. |
|
Context manager to temporarily enable one or more custom metadata merge strategies. |
|
Merge the |
Classes¶
Merge |
|
Merge |
|
Base class for defining a strategy for merging metadata from two sources, left and right, into a single output. |
|
Metaclass that registers MergeStrategy subclasses into the MERGE_STRATEGIES registry. |
|
|
A descriptor for classes that have a |
astropy.utils.misc Module¶
A “grab bag” of relatively small general-purpose utilities that don’t have a clear module/package to live in.
Functions¶
|
Returns |
|
A context manager that silences sys.stdout and sys.stderr. |
|
Given an exception message string, uses new-style formatting arguments |
|
Determines the URL of the API page for the specified object, and optionally open that page in a web browser. |
|
Determines if a given file or directory is hidden. |
|
A wrapper for |
|
Indent a block of text. |
|
Context manager to temporarily set the locale to |
|
Determines whether two or more Numpy arrays can be broadcast with each other based on their shape tuple alone. |
|
Parse the number out of a dtype.str value like ‘<U5’ or ‘<f8’. |
Classes¶
|
A context manager (for use with the |
|
Support for data types that JSON default encoder does not do. |
|
This metaclass makes methods of a class automatically have their docstrings filled in from the methods they override in the base class. |
|
Base class for descriptors whose order in the class body should be preserved. |
|
Classes should use this metaclass if they wish to use |
Mixin class to provide shape-changing methods. |
|
|
astropy.utils.state Module¶
A simple class to manage a piece of global science state. See Adding New Configuration Items for more details.
Classes¶
Science state subclasses are used to manage global items that can affect science results. |
astropy.utils.timer Module¶
General purpose timer related functions.
Classes¶
|
Class to predict run time. |
File Downloads¶
astropy.utils.data Module¶
This module contains helper functions for accessing, downloading, and caching data files.
Functions¶
|
Given a filename, pathlib.Path object or a readable file-like object, return a context manager that yields a readable file-like object. |
|
Retrieves the contents of a filename or file-like object. |
|
Retrieves a data file from the standard locations for the package and provides the file as a file-like object that reads bytes. |
|
Retrieves a data file from the standard locations for the package and provides a local filename for the data. |
|
Retrieves a data file from the standard locations and returns its contents as a bytes object. |
|
Returns readable file objects for all of the data files in a given directory that match a given glob pattern. |
|
Returns the path of all of the data files in a given directory that match a given glob pattern. |
|
Computes the MD5 hash for a file. |
|
Clears the data file cache by deleting the local file(s). |
|
Given a path to a directory, returns the amount of free space (in bytes) on that filesystem. |
|
Determines if a given directory has enough space to hold a file of a given size. |
|
Accepts a URL, downloads and optionally caches the result returning the filename, with a name determined by the file’s MD5 hash. |
|
Downloads multiple files in parallel from the given URLs. |
|
Check if a download from |
Get the list of URLs in the cache. |
Classes¶
Configuration parameters for |
|
This warning indicates the standard cache directory is not accessible, with the first argument providing the warning message. |
XML¶
The astropy.utils.xml.*
modules provide various
XML processing tools.
astropy.utils.xml.check Module¶
A collection of functions for checking various XML-related strings for standards compliance.
Functions¶
|
Returns |
|
Returns |
|
Returns |
|
Returns |
|
Given an arbitrary string, create one that can be used as an xml id. |
astropy.utils.xml.iterparser Module¶
This module includes a fast iterator-based XML parser.
Functions¶
|
Returns an iterator over the elements of an XML file. |
|
Determine the encoding of an XML file by reading its header. |
|
Get the lines from a given XML file. |
astropy.utils.xml.unescaper Module¶
URL unescaper functions.
Functions¶
|
Recursively unescape a given URL. |
astropy.utils.xml.validate Module¶
Functions to do XML schema and DTD validation. At the moment, this makes a subprocess call to xmllint. This could use a Python-based library at some point in the future, if something appropriate could be found.
Functions¶
|
Validates an XML file against a schema or DTD. |