Configuration system Documentation

The astropy configuration system is designed to give users control of various parameters used in astropy or affiliated packages without delving into the source code to make those changes.

For Users

To see the configuration options, look for your astropy configuration file. You can find it by doing:

from astropy.config import get_config_dir

print get_config_dir()

And you should see the location of your configuration directory. The standard scheme generally puts your configuration directory in $HOME/.astropy/config, but if you’ve set the environment variable XDG_CONFIG_HOME and the $XDG_CONFIG_HOME/astropy directory exists, it will instead be there.

Once you’ve found the configuration file, open it with your favorite editor. It should have all of the sections you might want, with descriptions and the type of the value that is accepted. Feel free to edit this as you wish, and any of these changes will be reflected when you next start Astropy. Or, if you want to see your changes immediately in your current Astropy session, just do:

from astropy.config import reload_config()

reload_config()

Warning

The above is not true yet, because the setup doesn’t automatically populate the configuration files. Hopefully it will be true soon, though. The astropy.config.configuration._generate_all_config_items() function will already do this, basically, but there has to be some thought about how to make driver scripts that actually do this for each user, and coordinate when they get run so that everything is already built.

Note

If for whatever reason your $HOME/.astropy directory is not accessible (i.e., you have astropy running somehow as root but you are not the root user), the best solution is to set the XDG_CONFIG_HOME and XDG_CACHE_HOME environment variables pointing to directories, and create an astropy directory inside each of those. Both the configuration and data download systems will then use those directories and never try to access the $HOME/.astropy directory.

For Developers

The Reference guide below describes the full interface - this is a summary of typical practices. The most common way to use the configuration system is as follows:

""" This is the docstring at the beginning of a module
"""
from astropy.config import ConfigurationItem

SOME_OPTION = ConfigurationItem('some_opt',1,'A description.')
ANOTHER_OPTION = ConfigurationItem('anno_opt','a string val',
                        'A longer description of what this does.')

... implementation ...
def some_func():
    #to get the value of these options, I might do:
    something = SOME_OPTION()+2
    return ANOTHER_OPTION()+' Also, I added text.'

It is highly recommended that any configuration items be placed at the top of a module like this, as they can then be easily found when viewing the source code and the automated tools to generate the default configuration files can also locate these items.

Reference/API

astropy.config Module

This module contains configuration and setup utilities for the astropy project. This includes all functionality related to the affiliated package index.

Functions

clear_data_cache([hashorurl])	Clears the data file cache by deleting the local file(s).
compute_hash(localfn)	Computes the MD5 hash for a file.
get_cache_dir()	Determines the Astropy cache directory name and creates the directory if it
get_config([packageormod, reload])	Gets the configuration object or section associated with a particular package or module.
get_config_dir([create])	Determines the Astropy configuration directory name and creates the
get_data_contents(dataname[, cache])	Retrieves a data file from the standard locations and returns its contents as a bytes object.
get_data_filename(dataname)	Retrieves a data file from the standard locations and provides the local name of the file.
get_data_filenames(datadir[, pattern])	Returns the path of all of the data files in a given directory that match a given glob pattern.
get_data_fileobj(dataname[, cache])	Retrieves a data file from the standard locations and provides the file as a file-like object.
get_data_fileobjs(datadir[, pattern])	Returns readable file objects for all of the data files in a given directory that match a given glob pattern.
reload_config([packageormod])	Reloads configuration settings from a configuration file for the root package of the requested package/module.
save_config([packageormod])	Saves all configuration settings to the configuration file for the root package of the requested package/module.

Classes

AstropyLogger(name[, level])	This class is used to set up the Astropy logging.
CacheMissingWarning	This warning indicates the standard cache directory is not accessible, with the first argument providing the warning message.
ConfigurationItem(name[, defaultvalue, ...])	A setting and associated value stored in the astropy configuration files.
ConfigurationMissingWarning	A Warning that is issued when the configuration directory cannot be
InvalidConfigurationItemWarning	A Warning that is issued when the configuration value specified in the
LoggingError	This exception is for various errors that occur in the astropy logger,