Configuration Transition¶
This document describes the changes in the configuration system in
astropy
0.4 and how to update code in order to use it.
For Users¶
The Config File¶
If you have not edited the configuration file in
~/.astropy/config/astropy.cfg
, there is nothing for you to do.
The first time you import astropy
0.4, it will automatically be
replaced with the configuration file template for astropy
0.4.
If you have edited the configuration file, it will be left untouched.
However, the template for astropy
0.4 will be installed as
~/.astropy/config/astropy.0.4.cfg
. You can manually compare your
changes to this file to determine what customizations should be
brought over.
Saving¶
Saving configuration items from Python has been completely removed. Instead, the configuration file must be edited directly.
Renames¶
The location of the configuration parameters have been simplified, so
they always appear in a high-level sub-package of astropy
, rather than in
low-level file names (which were really an implementation detail that
should not have been exposed to the user). On the Python side,
configuration items always are referenced through a conf
object at
the root of a sub-package.
Some configuration items that affect the results of science calculations have been removed as configuration parameters altogether and converted to science state objects that must be changed from Python code.
The following table lists all of the moves (in alphabetical order by
original configuration file location). The old names will continue to
work both from Python and the configuration file for the astropy
0.4
release cycle, and will be removed altogether in astropy
0.5.
Old config file location |
Old Python location |
New config file location |
New Python location |
---|---|---|---|
|
|
unchanged |
|
|
|
|
|
|
|
removed |
|
|
|
removed |
|
|
|
removed |
|
|
|
unchanged |
|
|
|
unchanged |
|
|
|
unchanged |
|
|
|
unchanged |
|
|
|
|
|
|
|
unchanged |
|
|
|
unchanged |
|
|
|
unchanged |
|
|
|
unchanged |
|
|
|
unchanged |
|
|
|
unchanged |
|
|
|
unchanged |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
unchanged |
|
|
|
unchanged |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
unchanged |
|
|
|
unchanged |
|
|
|
unchanged |
|
|
|
unchanged |
|
|
|
unchanged |
|
|
|
unchanged |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
For Affiliated Package Authors¶
For an affiliated package to support both astropy
0.3 and 0.4,
following the astropy
0.3 config instructions should continue to work.
Note that saving of configuration items has been removed entirely from
astropy
0.4 without a deprecation cycle, so if saving configuration
programmatically is important to your package, you may want to
consider another method to save that state.
However, by the release of astropy
0.5, the astropy
0.3 config API
will no longer work. The following describes how to transition an
affiliated package written for astropy
0.3 to support astropy
0.4 and
later. It will not be possible to support astropy
0.3, 0.4 and 0.5
simultaneously. Below pkgname
is the name of your affiliated
package.
The automatic generation of configuration files from the
ConfigurationItem
objects that it finds has been removed.
Instead, the project should include a hard-coded “template”
configuration file in pkgname/pkgname.cfg
. By convention, and to
ease upgrades for end users, all of the values should be commented
out. For example:
[nddata]
## Whether to issue a warning if NDData arithmetic is performed with
## uncertainties and the uncertainties do not support the propagation of
## correlated uncertainties.
# warn_unsupported_correlated = True
Affiliated packages should transition to using
astropy.config.ConfigItem
objects as members of
astropy.config.ConfigNamespace
subclasses.
For example, the following is an example of the astropy
0.3 and
earlier method to define configuration items:
from astropy.config import ConfigurationItem
ENABLE_RECORD_VALUED_KEYWORD_CARDS = ConfigurationItem(
'enabled_record_valued_keyword_cards', True,
'If True, enable support for record-valued keywords as described by '
'the FITS WCS distortion paper. Otherwise they are treated as normal '
'keywords.')
EXTENSION_NAME_CASE_SENSITIVE = ConfigurationItem(
'extension_name_case_sensitive', False,
'If True, extension names (i.e. the EXTNAME keyword) should be '
'treated as case-sensitive.')
The above, converted to the new method, looks like:
from astropy import config as _config
class Conf(_config.ConfigNamespace):
"""
Configuration parameters for `astropy.io.fits`.
"""
enable_record_valued_keyword_cards = _config.ConfigItem(
True,
'If True, enable support for record-valued keywords as described by '
'the FITS WCS distortion paper. Otherwise they are treated as normal '
'keywords.',
aliases=['astropy.io.fits.enabled_record_valued_keyword_cards'])
extension_name_case_sensitive = _config.ConfigItem(
False,
'If True, extension names (i.e. the ``EXTNAME`` keyword) should be '
'treated as case-sensitive.')
conf = Conf()
Moving/Renaming Configuration Items in Python¶
ConfigAlias
objects can be used when a configuration item has been
moved from an astropy
0.3-style ConfigurationItem
to an astropy
0.4-style ConfigItem
inside of a ConfigNamespace
.
In the above example, the following adds backward-compatible hooks so the old Python locations of the configuration items will continue to work from user code:
ENABLE_RECORD_VALUED_KEYWORD_CARDS = _config.ConfigAlias(
'0.4', 'ENABLE_RECORD_VALUED_KEYWORD_CARDS',
'enable_record_valued_keyword_cards')
Moving/Renaming Configuration Items in the Config File¶
If a configuration item is moved or renamed within the configuration
file, the aliases
kwarg to ConfigItem
can be used so that the
old location will continue to be used as a fallback. For example, if
the old location of an item was:
[coordinates.name_resolve]
sesame_url = http://somewhere.com
You might want to drop the fact that this is implemented in the module
name_resolve
and just store the configuration in coordinates
:
[coordinates]
sesame_url = http://somewhere.com
When defining the ConfigItem
for this entry, the aliases
kwarg
can list the old location(s) of the configuration item:
sesame_url = _config.ConfigItem(
["http://somewhere.com"],
"""Docstring""",
aliases=['astropy.coordinates.name_resolve.sesame_url'])