ConfigurationItem

class astropy.config.configuration.ConfigurationItem(name, defaultvalue='', description=None, cfgtype=None, module=None) [edit on github][source]

Bases: object

A setting and associated value stored in the astropy configuration files.

These objects are typically defined at the top of astropy subpackages or affiliated packages, and store values or option settings that can be modified by the user to

Parameters :

name : str

The (case-sensitive) name of this parameter, as shown in the configuration file.

defaultvalue :

The default value for this item. If this is a list of strings, this item will be interpreted as an ‘options’ value - this item must be one of those values, and the first in the list will be taken as the default value.

description : str or None

A description of this item (will be shown as a comment in the configuration file)

cfgtype : str or None

A type specifier like those used as the values of a particular key in a configspec file of configobj. If None, the type will be inferred from the default value.

module : str or None

The full module name that this item is associated with. The first element (e.g. ‘astropy’ if this is ‘astropy.config.configuration’) will be used to determine the name of the configuration file, while the remaining items determine the section. If None, the package will be inferred from the package within whiich this object’s initializer is called.

Raises :

RuntimeError :

If module is None, but the module this item is created from cannot be determined.

Examples

The following example will create an item ‘cfgoption = 42’ in the ‘[configuration]’ section of astropy.cfg (located in the directory that astropy.config.paths.get_config_dir returns), or if the option is already set, it will take the value from the configuration file:

from astropy.config import ConfigurationItem

CFG_OPTION = ConfigurationItem('cfgoption',42,module='astropy.configuration')

If called as CFG_OPTION(), this will return the value 42, or some other integer if the astropy.cfg file specifies a different value.

If this were a file astropy/configuration/__init__.py, the module option would not be necessary, as it would automatically detect the correct module.

Methods Summary

set(value) Sets the current value of this ConfigurationItem.
reload() Reloads the value of this ConfigurationItem from the relevant configuration file.
save([value]) Writes a value for this ConfigurationItem to the relevant configuration file.
set_temp(*args, **kwds) Sets this item to a specified value only inside a while loop.

Methods Documentation

set(value) [edit on github][source]

Sets the current value of this ConfigurationItem.

This also updates the comments that give the description and type information.

Note

This does not save the value of this ConfigurationItem to the configuration file. To do that, use ConfigurationItem.save or save_config.

Parameters :

value :

The value this item should be set to.

Raises :

TypeError :

If the provided value is not valid for this ConfigurationItem.

reload() [edit on github][source]

Reloads the value of this ConfigurationItem from the relevant configuration file.

Returns :

val :

The new value loaded from the configuration file.

save(value=None) [edit on github][source]

Writes a value for this ConfigurationItem to the relevant configuration file.

This also writes updated versions of the comments that give the description and type information.

Note

This only saves the value of this particular ConfigurationItem. To save all configuration settings for this package at once, see save_config.

Parameters :

value :

Save this value to the configuration file. If None, the current value of this ConfigurationItem will be saved.

Raises :

TypeError :

If the provided value is not valid for this ConfigurationItem.

set_temp(*args, **kwds) [edit on github][source]

Sets this item to a specified value only inside a while loop.

Use as::

ITEM = ConfigurationItem(‘ITEM’, ‘default’, ‘description’)

with ITEM.set_temp(‘newval’):
... do something that wants ITEM’s value to be ‘newval’ ...

# ITEM is now ‘default’ after the with block

Parameters :

value :

The value to set this item to inside the with block.

Page Contents