Module Config

source code

A simple configuration interface for Ganga packages.

1) Overview

PackageConfig object corresponds to a configuration section in the INI file.
Typically each plugin handler has its own section. Additionally Ganga provides
a somewhat arbitrary number of other configuration packages.

Configuration of the package is done in several phases:
 - phase one: developer defines the hardcoded values in his package (default level);
              addOption
 - phase two: at startup ganga reads config files and set options (session level);
              setSessionValue() is used
 - phase three: at runtime user may modify options via GPI (user level);
              setUserValue() is used for setting, getEffectiveOption() for getting


2) Defining default options for your package:

#MyPackage.py#

import Ganga.Utility.Config

config = Ganga.Utility.Config.getConfig('MyPackage')

config.addOption('opt1','x','this is option 1')
config.addOption('opt2',3.0, 'this is option 2')

The  default  values of  the  options  may  be strings,  numbers,other
built-in  types  or  any  GPI  objects names  defined  in  the  global
config_scope dictionary (in this module).

IMPORTANT: choose the type of the default value carefully: session and
user options  will be automatically  converted to the type  implied by
the default value (you may  also override the type checking default in
setDefaultOption)  .   The  conversion   is  done  as  following  (for
setSessionValue and setUserValue):

 - nothing is done (value is assigned 'as-is'):
    - if the default type is a string and the assigned value is a string
    - if there is no default value

 - eval the string value

 - check if the type matches the default type and raise ConfigError in case of mismatch
    - unless the default type is None
 
Typically strings are assigned via setSessionValue() as they are read
from the config file or command line.

Note for bootstrap procedure: it is OK to first set the session option
and  then  to  set  it's  default  value. That  is  to  say  that  the
configuration may  be read from the  config file prior  to loading the
corresponding module which  uses it. It is NOT OK  to set user options
before the end of the bootstrap procedure.


3) Getting effective values and using callback handlers

To get the effective value of an option you may use:

print config['opt1']
print config.getEffectiveOption('opt1')
print config.getEffectiveOptions() # all options

The  effective value  takes  into account  default,  session and  user
settings  and  may change  at  runtime.  In  GPI  users  only get  the
effective values and may only set values at the user level.

You  may also attach  the callback  handlers at  the session  and user
level.     Pre-process   handlers   may    modify   what    has   been
set. Post-process handlers may be used to trigger extra actions.

def pre(opt,val):
    print 'always setting a square of the value'
    return val*2

def post(opt,val):
    print 'effectively set',val
    
config.attachUserHandler(pre,post)

4) How does user see all this in GPI ?

There is a GPI wrapper in Ganga.GPIDev.Lib.Config which:
     - internally uses setUserValue and getEffectiveOption
     - has a more appealing interface

Return the new value of the option 'name' taking into account special rules for PATH-like variables:

   A variable is PATH-like if the name ends in _PATH.
   Return 'new_value:current_value' unless new_value starts in ':::' or current_value is None.
   In that case return new_value.

   Example:
   if a name of a option terminates in _PATH then the value will not be overriden but
   appended:
   file1.ini:
     ANY_PATH = x
   file2.ini:
     ANY_PATH = y
   
   result of the merge is: ANY_PATH = x:y
   
   If you want to override the path you should use :::path, for example:
   file1.ini:
     ANY_PATH = x
   file2.ini
     ANY_PATH = :::y
   result of the merge is: ANY_PATH = y

For other variables just return the new_value.

Function to overwrite option values set in configuration file:

Arguments:
   section - Name of relevant section within configuration file
   item    - Item for which value is to be changed
   value   - Value to be assigned

Function needs to be called after configuration file has been parsed.

Return value: None