astro py:docs

- Index
- Modules

### Navigation

- next »
- « previous |
- Astropy v0.3 »
- Astropy Core Package Utilities (`astropy.utils`)

# 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 does not have detailed sections like the other packages.

Note

The `astropy.utils.compat` subpackage is not included in this documentation. It contains utility modules for compatibility with older/newer versions of python, 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 it cannot be reliably included here because of the large amount of version-specific code it contains.

## Reference/API

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

`find_current_module`([depth, finddiff]) | Determines the module/package from which this function is called.
`isiterable`(obj) | Returns `True` if the given object is iterable.
`deprecated`(since[, message, name, ...]) | Used to mark a function as deprecated.
`deprecated_attribute`(name, since[, message, ...]) | Used to mark a public attribute as deprecated.
`silence`(*args, **kwds) | 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.

#### Classes

`lazyproperty`(fget[, fset, fdel, doc]) | Works similarly to property(), but computes the value only once.
`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, ensure_ascii, ...]) | Support for data types that JSON default encoder does not do.

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

### 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, **kwargs) | 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.

#### Classes

`ProgressBar`(total_or_items[, file]) | 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.timer Module

General purpose timer related functions.

#### Functions

`timefunc`([num_tries, verbose]) | Decorator to time a function or method.

#### Classes

`RunTimePredictor`(func, *args, **kwargs) | Class to predict run time.

### File Downloads

### astropy.utils.data Module

This module contains helper functions for accessing, downloading, and caching data files.

#### Functions

`get_readable_fileobj`(*args, **kwds) | Given a filename or a readable file-like object, return a context manager that yields a readable file-like object.
`get_file_contents`(name_or_obj[, encoding, cache]) | Retrieves the contents of a filename or file-like object.
`get_pkg_data_fileobj`(data_name[, encoding, ...]) | 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[, ...]) | 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[, encoding, ...]) | Retrieves a data file from the standard locations and returns its contents as a bytes object.
`get_pkg_data_fileobjs`(datadir[, pattern, ...]) | 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[, pattern]) | Returns the path of all of the data files in a given directory that match a given glob pattern.
`compute_hash`(localfn) | Computes the MD5 hash for a file.
`clear_download_cache`([hashorurl]) | Clears the data file cache by deleting the local file(s).
`get_free_space_in_dir`(path) | Given a path to a directory, returns the amount of free space (in bytes) 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.
`download_file`(remote_url[, cache, ...]) | Accepts a URL, downloads and optionally caches the result returning the filename, with a name determined by the file’s MD5 hash.
`download_files_in_parallel`(urls[, cache, ...]) | Downloads multiple files in parallel from the given URLs.

#### Classes

`CacheMissingWarning` | 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

`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`(*args, **kwds) | 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.