# `utopya_rc` module

The `utopya_rc` module holds the base class for objects that have settings defined in a rcfile.

## Class hierarchy

The classes are defined according to following hierarchy:

- `UtopyaBase`

  - `UtopyaRc`

## Classes

class utopya_rc.UtopyaRc(rcfile=None, rcbase='', env={}, urc=None)

  Bases: `UtopyaBase`

  Base class for UTOPyA objects configured by a text file called the ‘rcfile’. See the documentation of the `rc` module for details on the rcfile formating and preprocessing on reading.

  The settings are read on initialization if either:

  - `rcfile` is present with the name of the settings file, and optionally `rcbase` and `env`; these are passed to `InitRc()`;

  - `urc` is provided which is an instance of the `UtopyaRc`` class; the settings already read into this instance are then copied; this could speedup processing since the settings do not need to be read again.

  If none of these arguments is upplied, a later call to `InitRc()` should be made.

  Use the `GetSetting()` method to obtain the value of a setting. For example, if the rcfile ‘test.rc’ has content:

      ! sample setting:
      data.value    :  10

  this could be retrieved using:

      uto = UtopyaRc( 'test.rc' )
      n = uto.GetSetting( 'data.value', 'int' )

  The optional ‘rcbase’ defines the first part of the settings, and can be used to define groups of similar settings. For example, if the rcfile contains settings for ‘Model-A’ and ‘Model-B’:

      ! sample setting:
      Model-A.data.value    :  10
      Model-B.data.value    :  20

  then the settings for ‘Model-A’ are selected using:

      uto = UtopyaRc( 'test.rc', rcbase='Model-A' )
      n = uto.GetSetting( 'data.value', 'int' )

  Settings that apply to all bases could be defined by a template:

      ! sample setting:
      *.data.value    :  10

  In summary, the following methods are provided with this class:

  - `InitRc()` : read rcfile if not done on initialization;

  - `GetSetting()` : extract value of setting;

  - `ImportClass()` : import class specified by an rcfile setting.

  InitRc(rcfile, rcbase='', env={})

    Initialize rcfile if not done on initialization.

  GetSetting(name, totype='', **kwargs)

    Return value of the named entry in the rcfile:

        <name>       :  <value>

    If at initialization an optional ‘rcbase’ was provided, the entry that is searched for is prefixed by this base, or is a generic version:

        <rcbase>.<name>    :  <value>
        *.<name>           :  <value>

    Optional keyword arguments are pased to the `RcFile.get()` method. For example, a keyword argument ‘default’ could be used to set the return value if none of the keys is found.

    Note that double dots ‘..’ in a name are replaced by a single ‘.’, this is useful when the provided name is combined from some underlying parts and some of these start or end with a dot already.

  SetSetting(name, value)

    Set key/value pair.

  WriteSettings(filename)

    Write evaluated settings to file.

  ImportClass(name)

    Import class from a module, where the names are specified in the rcfile.

    For example, to import ‘MyClass’ from the module ‘MyMod’ defined in the file ‘/path/to/MyMod.py’, use the following setting:

        [<rcbase>.]name      :  /path/to/MyMod.MyClass