The Astropy configuration options are most easily set by modifying the
configuration file. It will be automatically generated with all the
default values commented out the first time you import Astropy. You
can find the exact location by doing:

>>> fromastropy.configimportget_config_dir>>> 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. It can be customized with the environment variable
XDG_CONFIG_HOME and the $XDG_CONFIG_HOME/astropy directory must exist.
Note that XDG_CONFIG_HOME comes from a Linux-centric specification (see
here for
more details), but Astropy will use this on any OS as a more general mean to
know where user-specific configurations should be written.

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:

>>> fromastropy.configimportreload_config>>> reload_config()

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.

By convention, configuration parameters live inside of objects called
conf at the root of each subpackage. For example, configuration
parameters related to data files live in astropy.utils.data.conf.
This object has properties for getting and setting individual
configuration parameters. For instance to get the default URL for
astropy remote data do:

Changing configuration values persistently is done by editing the
configuration file as described above. Values can also, however, be
modified in an active python session by setting any of the properties
on a conf object.

For example, if there is a part of your configuration file that looks
like:

Each time you upgrade to a new major version of astropy, the
configuration parameters may have changed.

If you never edited your configuration file, there is nothing for you
to do. It will automatically be replaced with a configuration file
template for the newly installed version of astropy.

If you did customize your configuration file, it will not be touched.
Instead, a new configuration file template will be installed alongside
it with the version number in the filename, for example
astropy.0.4.cfg. You can compare this file to your
astropy.cfg file to see what needs to be changed or updated.

Configuration items should be used wherever an option or setting is
needed that is either tied to a system configuration or should persist
across sessions of astropy or an affiliated package. Options that may
affect the results of science calculations should not be configuration
items, but should instead be astropy.utils.state.ScienceState, so
it’s possible to reproduce science results without them being affected
by configuration parameters set in a particular environment.
Admittedly, this is only a guideline, as the precise cases where a
configuration item is preferred over, say, a keyword option for a
function is somewhat personal preference. It is the preferred form of
persistent configuration, however, and astropy packages must all use
it (and it is recommended for affiliated packages).

The reference guide below describes the interface for creating a
conf object with a number of configuration parameters. They
should be defined at the top level, i.e. in the __init__.py of
each subpackage that has configuration items:

""" This is the docstring at the beginning of a module"""fromastropyimportconfigas_configclassConf(_config.ConfigNamespace):""" Configuration parameters for my subpackage. """some_setting=_config.ConfigItem(1,'Description of some_setting')another_setting=_config.ConfigItem('string value','Description of another_setting')# Create an instance for the userconf=Conf()...implementation...defsome_func():#to get the value of these options, I might do:something=conf.some_setting+2returnconf.another_setting+' Also, I added text.'

The configuration items also need to be added to the config file
template. For astropy, this file is in astropy/astropy.cfg. For
an affiliated package called, for example, packagename, the file
is in packagename/packagename.cfg. For the example above, the
following content would be added to the config file template:

Note that the key/value pairs are commented out. This will allow for
changing the default values in a future version of astropy without
requiring the user to edit their configuration file to take advantage
of the new defaults. By convention, the descriptions of each
parameter are in comment lines starting with two hash characters
(##) to distinguish them from commented out key/value pairs.

If not otherwise specified, a ConfigItem gets its
type from the type of the defaultvalue it is given when it is
created. The item can only be set to be an object of this type.
Hence:

some_setting=ConfigItem(1,'A description.')...conf.some_setting=1.2

will fail, because 1.2 is a float and 1 is an int.

Note that if you want the configuration item to be limited to a
particular set of options, you should pass in a list as the
defaultvalue option. The first entry in the list will be taken as
the default, and the list as a whole gives all the valid options. For
example:

If the default value’s type doesn’t match cfgtype, the
ConfigItem cannot be created:

an_int_setting=ConfigItem(4.2,'A description.',cfgtype='integer')

In summary, the default behavior (of automatically determining cfgtype)
is usually what you want. The main exception is when you want your
configuration item to be a list. The default behavior will treat that
as a list of options unless you explicitly tell it that the
ConfigItem itself is supposed to be a list:

Keep in mind is that ConfigItem objects can be
changed at runtime by users. So it is always recommended to read their
values immediately before use instead of just storing their initial
value to some other variable (or used as a default for a
function). For example, the following will work, but is incorrect
usage:

defsome_func(val=conf.some_setting):returnval+2

This works fine as long as the user doesn’t change its value during
runtime, but if they do, the function won’t know about the change:

Context manager to set a temporary path for the Astropy download cache, primarily for use with testing (though there may be other applications for setting a different cache directory, for example to switch to a cache dedicated to large files).