astro py:docs

- Index
- Modules

### Navigation

- next »
- « previous |
- Astropy v0.3 »
- Configuration system (`astropy.config`) »
- ConfigurationItem

# ConfigurationItem

class `astropy.config.configuration.``ConfigurationItem`(name, defaultvalue=u'', description=None, cfgtype=None, module=None)

  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

  `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`(value) | Sets the current value of this `ConfigurationItem`.
  `set_temp`(*args, **kwds) | Sets this item to a specified value only inside a while loop.

  Methods Documentation

  `reload`()

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

    Returns:

    val :

    > The new value loaded from the configuration file.

  `save`(value=None)

    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`(value)

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

  `set_temp`(*args, **kwds)

    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.