Skip to main content
`Ctrl`+`K`

# ConfigItem

class astropy.config.ConfigItem(defaultvalue='', description=None, cfgtype=None, module=None, aliases=None)

  Bases: `object`

  A setting and associated value stored in a configuration file.

  These objects should be created as members of `ConfigNamespace` subclasses, for example:

      class _Conf(config.ConfigNamespace):
          unicode_output = config.ConfigItem(
              False,
              'Use Unicode characters when outputting values, and writing widgets '
              'to the console.')
      conf = _Conf()

  Parameters:
    defaultvalue `object`, optional

      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 `python:str` or `python:None`, optional

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

    cfgtype `python:str` or `python:None`, optional

      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 `python:str` or `python:None`, optional

      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 which this object’s initializer is called.

    aliases `python:str`, or `python:list` of `python:str`, optional

      The deprecated location(s) of this configuration item. If the config item is not found at the new location, it will be searched for at all of the old locations.

  Raises:
    `RuntimeError`

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

  Attributes Summary

  `cfgtype` | A type specifier like those used as the values of a particular key in a `configspec` file of `configobj`.
  `rootname` | Rootname sets the base path for all config files.

  Methods Summary

  `__call__`() | Returns the value of this `ConfigItem`.
  `reload`() | Reloads the value of this `ConfigItem` from the relevant configuration file.
  `set`(value) | Sets the current value of this `ConfigItem`.
  `set_temp`(value) | Sets this item to a specified value only inside a with block.

  Attributes Documentation

  cfgtype = None

    A type specifier like those used as the values of a particular key in a `configspec` file of `configobj`.

  rootname = 'astropy'

    Rootname sets the base path for all config files.

  Methods Documentation

  __call__()

    Returns the value of this `ConfigItem`.

    Returns:
      val `object`

        This item’s value, with a type determined by the `cfgtype` attribute.

    Raises:
      `TypeError`

        If the configuration value as stored is not this item’s type.

  reload()

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

    Returns:
      val `object`

        The new value loaded from the configuration file.

  set(value)

    Sets the current value of this `ConfigItem`.

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

    Parameters:
      value

        The value this item should be set to.

    Raises:
      `TypeError`

        If the provided `value` is not valid for this `ConfigItem`.

  set_temp(value)

    Sets this item to a specified value only inside a with block.

    Use as:

        ITEM = ConfigItem('ITEM', 'default', 'description')

        with ITEM.set_temp('newval'):
            #... do something that wants ITEM's value to be 'newval' ...
            print(ITEM)

        # ITEM is now 'default' after the with block

    Parameters:
      value

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