Skip to main content
`Ctrl`+`K`

# Reference/API

## Utility Functions/Classes

### 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

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

#### Classes

`ProgressBar`(total_or_items[, ...]) | A class to display a progress bar 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.
`Spinner`(msg[, color, file, step, chars]) | A class to display a spinner in the terminal.

### 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`(function, /) | This is a method decorator that allows both an instance method 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

`AstropyBackwardsIncompatibleChangeWarning` | A warning class indicating a change in astropy that is incompatible with previous versions.
`AstropyDeprecationWarning` | A warning class to indicate a deprecated feature.
`AstropyPendingDeprecationWarning` | A warning class to indicate a soon-to-be deprecated feature.
`AstropyUserWarning` | The primary warning class for Astropy.
`AstropyWarning` | The base warning class from which all Astropy warnings should inherit.
`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

`find_current_module`([depth, finddiff]) | Determines the module/package from which this function is called.
`isinstancemethod`(cls, obj) |
`minversion`(module, version[, inclusive]) | Returns `True` if the specified Python module satisfies a minimum version requirement, and `False` if not.
`resolve_name`(name, *additional_parts) |

### astropy.utils.metadata Package

This module contains helper functions and classes for handling metadata.

#### Functions

`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.
`common_dtype`(arrs) | Use numpy to find the common dtype for a list of ndarrays.

#### Classes

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

### 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

`dtype_bytes_or_chars`(dtype) | Parse the number out of a dtype.str value like '<U5' or '<f8'.
`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.
`format_exception`(msg, *args, **kwargs) |
`indent`(s[, shift, width]) |
`isiterable`(obj) |
`online_help`(query) | Search the online Astropy documentation for the given query.
`silence`() | A context manager that silences sys.stdout and sys.stderr.

#### Classes

`JsonCustomEncoder`(*[, skipkeys, ...]) | Support for data types that JSON default encoder does not do.
`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.

### 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) |
`simplify_basic_index`(basic_index, *, shape) | Given a Numpy basic index, return a tuple of integers and slice objects with no default values (`None`) if possible.
`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

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

### astropy.utils.system_info Module

A helper script to automate system info in bug reports.

This can be run as:

    python -c "import astropy; astropy.system_info()"

(note that the interpreter might be called python3 instead of python, depending on your system’s details)

This script should not require anything else than the standard library and is subject to change without notice.

#### Functions

`system_info`() | Print relevant system information for astropy bug reports.

## File Downloads

### astropy.utils.data Module

Functions for accessing, downloading, and caching data files.

#### Functions

`cache_contents`([pkgname, on_missing]) | Obtain a dict mapping cached URLs to filenames.
`cache_total_size`([pkgname]) | Return the total size in bytes of all files in the cache.
`check_download_cache`([pkgname]) | Do a consistency check on the cache.
`check_free_space_in_dir`(path, size) | Determines if a given directory has enough space to hold a file of a given size.
`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.
`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.
`export_download_cache`(filename_or_obj[, ...]) | Exports the cache contents as a ZIP file.
`get_cached_urls`([pkgname, on_missing]) | Get the list of URLs in the cache.
`get_file_contents`(*args, **kwargs) | Retrieves the contents of a filename or file-like object.
`get_free_space_in_dir`(path[, unit]) | Given a path to a directory, returns the amount of free space on that filesystem.
`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_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_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_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_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_path`(*path[, package]) | Get path from source-included data directories.
`get_readable_fileobj`(name_or_obj[, ...]) | Yield a readable, seekable file-like object from a file or URL.
`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.
`is_url`(string) | Test whether a string is a valid URL for `download_file()`.
`is_url_in_cache`(url_key[, pkgname, on_missing]) | Check if a download for `url_key` is in the cache.

#### Classes

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

## 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_encoding`(source) | Determine the encoding of an XML file by reading its header.
`get_xml_iterator`(source[, ...]) | Returns an iterator over the elements of an XML file.
`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.