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 exceptions are below:

• IERS data access (astropy.utils.iers)
• Downloadable Data Management (astropy.utils.data)
• Masked Values (astropy.utils.masked)

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. Its content is solely for internal use of astropy and subject to changes without deprecations. Do not use it in external packages or code.

Reference/API

astropy.utils.codegen Module

Utilities for generating new Python code at runtime.

Functions

make_function_with_signature(func[, args, ...])

Make a new function from an existing function but with the desired signature.

astropy.utils.collections Module

A module containing specialized collection classes.

Classes

HomogeneousList(types[, values])

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

isatty(file)	Returns True if file is a tty.
color_print(*args[, end])	Prints colors and styles to the terminal uses ANSI escape sequences.
human_time(seconds)	Returns a human-friendly time string that is always exactly 6 characters long.
human_file_size(size)	Returns a human-friendly string representing a file size that is 2-4 characters long.
print_code_line(line[, col, file, tabwidth, ...])	Prints a line of source code, highlighting a particular character position in the line.
terminal_size([file])	Returns a tuple (height, width) containing the height and width of the terminal.

Classes

ProgressBar(total_or_items[, ...])	A class to display a progress bar in the terminal.
Spinner(msg[, color, file, step, chars])	A class to display a spinner in the terminal.
ProgressBarOrSpinner(total, msg[, color, file])	A class that displays either a ProgressBar or Spinner depending on whether the total size of the operation is known or not.

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

data_info_factory(names, funcs)	Factory to create a function that can be used as an option for outputting data object summary information.
dtype_info_name(dtype)	Return a human-oriented string name of the dtype arg.

Classes

BaseColumnInfo([bound])	Base info class for anything that can be a column in an astropy Table.
DataInfo([bound])	Descriptor that data classes use to add an info attribute for storing data attributes in a uniform and portable way.
MixinInfo([bound])
ParentDtypeInfo([bound])	Mixin that gets info.dtype from parent

astropy.utils.decorators Module

Sundry function and class decorators.

Functions

deprecated(since[, message, name, ...])	Used to mark a function or class as deprecated.
deprecated_attribute(name, since[, message, ...])	Used to mark a public attribute as deprecated.
deprecated_renamed_argument(old_name, ...[, ...])	Deprecate a _renamed_ or _removed_ function argument.
format_doc(docstring, *args, **kwargs)	Replaces the docstring of the decorated object and then formats it.

Classes

classproperty([fget, doc, lazy])	Similar to property, but allows class-level properties.
lazyproperty(fget[, fset, fdel, doc])	Works similarly to property(), but computes the value only once.
sharedmethod	This is a method decorator that allows both an instancemethod and a classmethod to share the same name.

astropy.utils.diff Module

Functions

diff_values(a, b[, rtol, atol])	Diff two scalar values.
report_diff_values(a, b[, fileobj, ...])	Write a diff report between two values to the specified file-like object.
where_not_allclose(a, b[, rtol, atol])	A version of numpy.allclose() that returns the indices where the two arrays differ, instead of just a boolean value.

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.

Classes

AstropyWarning	The base warning class from which all Astropy warnings should inherit.
AstropyUserWarning	The primary warning class for Astropy.
AstropyDeprecationWarning	A warning class to indicate a deprecated feature.
AstropyPendingDeprecationWarning	A warning class to indicate a soon-to-be deprecated feature.
AstropyBackwardsIncompatibleChangeWarning	A warning class indicating a change in astropy that is incompatible with previous versions.
DuplicateRepresentationWarning	A warning class indicating a representation name was already registered

astropy.utils.iers Package

Classes

Conf()	Configuration parameters for astropy.utils.iers.
IERS([data, masked, names, dtype, meta, ...])	Generic IERS table class, defining interpolation functions.
IERSDegradedAccuracyWarning	IERS time conversion has degraded accuracy normally due to setting conf.auto_download = False and conf.iers_degraded_accuracy = 'warn'.
IERSRangeError	Any error for when dates are outside of the valid range for IERS
IERSStaleWarning	Downloaded IERS table may be stale.
IERSWarning	Generic warning class for IERS.
IERS_A([data, masked, names, dtype, meta, ...])	IERS Table class targeted to IERS A, provided by USNO.
IERS_Auto([data, masked, names, dtype, ...])	Provide most-recent IERS data and automatically handle downloading of updated values as necessary.
IERS_B([data, masked, names, dtype, meta, ...])	IERS Table class targeted to IERS B, provided by IERS itself.
LeapSeconds([data, masked, names, dtype, ...])	Leap seconds class, holding TAI-UTC differences.
earth_orientation_table()	Default IERS table for Earth rotation and reference systems service.

astropy.utils.introspection Module

Functions related to Python runtime introspection.

Functions

resolve_name(name, *additional_parts)	Resolve a name like module.object to an object and return it.
minversion(module, version[, inclusive, ...])	Returns True if the specified Python module satisfies a minimum version requirement, and False if not.
find_current_module([depth, finddiff])	Determines the module/package from which this function is called.
isinstancemethod(cls, obj)	Returns True if the given object is an instance method of the class it is defined on (as opposed to a staticmethod or a classmethod).

astropy.utils.metadata Module

This module contains helper functions and classes for handling metadata.

Functions

common_dtype(arrs)	Use numpy to find the common dtype for a list of ndarrays.
enable_merge_strategies(*merge_strategies)	Context manager to temporarily enable one or more custom metadata merge strategies.
merge(left, right[, merge_func, ...])	Merge the left and right metadata objects.

Classes

MergeConflictError
MergeConflictWarning
MergePlus()	Merge left and right objects using the plus operator.
MergeNpConcatenate()	Merge left and right objects using np.concatenate.
MergeStrategy()	Base class for defining a strategy for merging metadata from two sources, left and right, into a single output.
MergeStrategyMeta(name, bases, members)	Metaclass that registers MergeStrategy subclasses into the MERGE_STRATEGIES registry.
MetaData([doc, copy])	A descriptor for classes that have a meta property.
MetaAttribute([default])	Descriptor to define custom attribute which gets stored in the object meta dict and can have a defined default.

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

isiterable(obj)	Returns True if the given object is iterable.
silence()	A context manager that silences sys.stdout and sys.stderr.
format_exception(msg, *args, **kwargs)	Given an exception message string, uses new-style formatting arguments {filename}, {lineno}, {func} and/or {text} to fill in information about the exception that occurred.
find_api_page(obj[, version, openinbrowser, ...])	Determines the URL of the API page for the specified object, and optionally open that page in a web browser.
is_path_hidden(filepath)	Determines if a given file or directory is hidden.
walk_skip_hidden(top[, onerror, followlinks])	A wrapper for os.walk that skips hidden files and directories.
indent(s[, shift, width])	Indent a block of text.
dtype_bytes_or_chars(dtype)	Parse the number out of a dtype.str value like '<U5' or '<f8'.

Classes

NumpyRNGContext(seed)	A context manager (for use with the with statement) that will seed the numpy random number generator (RNG) to a specific value, and then restore the RNG state back to whatever it was before.
JsonCustomEncoder(*[, skipkeys, ...])	Support for data types that JSON default encoder does not do.
OrderedDescriptor(*args, **kwargs)	Deprecated since version 4.3.
OrderedDescriptorContainer(cls_name, bases, ...)	Deprecated since version 4.3.

astropy.utils.parsing Module

Wrappers for PLY to provide thread safety.

Functions

lex(lextab, package[, reflags])	Create a lexer from local variables.
yacc(tabmodule, package)	Create a parser from local variables.

Classes

ThreadSafeParser(parser)

Wrap a parser produced by ply.yacc.yacc.

astropy.utils.state Module

A simple class to manage a piece of global science state. See Adding New Configuration Items for more details.

Classes

ScienceState()

Science state subclasses are used to manage global items that can affect science results.

astropy.utils.shapes Module

The ShapedLikeNDArray mixin class and shape-related functions.

Functions

check_broadcast(*shapes)	Determines whether two or more Numpy arrays can be broadcast with each other based on their shape tuple alone.
unbroadcast(array)	Given an array, return a new array that is the smallest subset of the original array that can be re-broadcasted back to the original array.

Classes

NDArrayShapeMethods()	Mixin class to provide shape-changing methods.
ShapedLikeNDArray()	Mixin class to provide shape-changing methods.
IncompatibleShapeError(shape_a, shape_a_idx, ...)

File Downloads

astropy.utils.data Module

Functions for accessing, downloading, and caching data files.

Functions

download_file(remote_url[, cache, ...])	Downloads a URL and optionally caches the result.
download_files_in_parallel(urls[, cache, ...])	Download multiple files in parallel from the given URLs.
get_readable_fileobj(name_or_obj[, ...])	Yield a readable, seekable file-like object from a file or URL.
get_pkg_data_fileobj(data_name[, package, ...])	Retrieves a data file from the standard locations for the package and provides the file as a file-like object that reads bytes.
get_pkg_data_filename(data_name[, package, ...])	Retrieves a data file from the standard locations for the package and provides a local filename for the data.
get_pkg_data_contents(data_name[, package, ...])	Retrieves a data file from the standard locations and returns its contents as a bytes object.
get_pkg_data_fileobjs(datadir[, package, ...])	Returns readable file objects for all of the data files in a given directory that match a given glob pattern.
get_pkg_data_filenames(datadir[, package, ...])	Returns the path of all of the data files in a given directory that match a given glob pattern.
get_pkg_data_path(*path[, package])	Get path from source-included data directories.
is_url(string)	Test whether a string is a valid URL for download_file().
is_url_in_cache(url_key[, pkgname])	Check if a download for url_key is in the cache.
get_cached_urls([pkgname])	Get the list of URLs in the cache.
cache_total_size([pkgname])	Return the total size in bytes of all files in the cache.
cache_contents([pkgname])	Obtain a dict mapping cached URLs to filenames.
export_download_cache(filename_or_obj[, ...])	Exports the cache contents as a ZIP file.
import_download_cache(filename_or_obj[, ...])	Imports the contents of a ZIP file into the cache.
import_file_to_cache(url_key, filename[, ...])	Import the on-disk file specified by filename to the cache.
check_download_cache([pkgname])	Do a consistency check on the cache.
clear_download_cache([hashorurl, pkgname])	Clears the data file cache by deleting the local file(s).
compute_hash(localfn)	Computes the MD5 hash for a file.
get_free_space_in_dir(path[, unit])	Given a path to a directory, returns the amount of free space on that filesystem.
check_free_space_in_dir(path, size)	Determines if a given directory has enough space to hold a file of a given size.
get_file_contents(*args, **kwargs)	Retrieves the contents of a filename or file-like object.

Classes

Conf()	Configuration parameters for astropy.utils.data.
CacheMissingWarning	This warning indicates the standard cache directory is not accessible, with the first argument providing the warning message.
CacheDamaged(*args[, bad_urls, bad_files])	Record the URL or file that was a problem.

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

check_anyuri(uri)	Returns True if uri is a valid URI as defined in RFC 2396.
check_id(ID)	Returns True if ID is a valid XML ID.
check_mime_content_type(content_type)	Returns True if content_type is a valid MIME content type (syntactically at least), as defined by RFC 2045.
check_token(token)	Returns True if token is a valid XML token, as defined by XML Schema Part 2.
fix_id(ID)	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

get_xml_iterator(source[, ...])	Returns an iterator over the elements of an XML file.
get_xml_encoding(source)	Determine the encoding of an XML file by reading its header.
xml_readlines(source)	Get the lines from a given XML file.

astropy.utils.xml.unescaper Module

URL unescaper functions.

Functions

unescape_all(url)

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

validate_schema(filename, schema_file)

Validates an XML file against a schema or DTD.

astropy.utils.xml.writer Module

Contains a class that makes it simple to stream out well-formed and nicely-indented XML.

Classes

XMLWriter(file)

A class to write well-formed and nicely indented XML.