[News] The astro.main.Config interface rewritten

[John P. McFarland]

Dear All,

This News item is long and concerns the technical details of the new Config 
interface for astro.external programs.  If you don't have a need or are not 
interested, there is no reason to read further.


The astro.main.Config interface has been rewritten to make sure all 
persistent Config objects have a uniform and expanded interface and complete 
information about all persistent properties.  Below is a listing of the 
relevant changes.

- All KW_LISTs from the astro.external modules are deprecated.  The
   changeable information contained within them now exists only in the Config
   classes.  Each of the external program modules contains a copy of the
   original KW_LISTs at the end of the file.  This copy is for reference
   only.
   - If a list similar to the original KW_LIST is needed, the current one can
     be retrieved through the Config method call get_kw_list() and the
     default one through the method call get_defaults().

- All PARAM_LISTs from the astro.external modules (Sextractor and
   LDAC.make_ssc only) are deprecated.  They are now represented by a Params
   class or integrated into the Config class.  The relevant program modules
   contain a copy of the original PARAMS_LISTs at the end of the file.  This
   copy is for reference only.
   - If a list similar to the original PARAM_LIST is needed, the current one
     can be retrieved through the Params method call get_param_list() and the
     default one through the method call get_defaults().

- The Config and Params objects have new features, some deprecating similar
   functionality in the astro.external modules:
   - The show() method will print the settings as they will appear in the
     file.
   - The save() method will save the properly formatted configuration to an
     optional filename.
   - An optional filename can also be specified during instantiation.  If one
     is not specified, a unique, canonical name will be provided.
   - The remove() method will remove the configuration file if it exists, and
     silently ignore it if it doesn't.  It can also take an optional
     filename.
   - All Config and Params objects can and should be created using the
     factory functions create_config and create_params (see examples below).
   - The names of the arguments of the factory functions are now more
     uniform: they are all in lowercase letters.  See astro.main.Config and
     astro.main.DiaConfig for details.
   - The new Config interface has all the same functionality as the previous
     interface and is backwards compatible.  This may change in the future.

- The interface for Sextractor, Swarp, LDAC, and Dia is now uniform.  All
   four modules have been modified to use the new interface.  This includes
   removing configuration file writing functions as they are now part of the
   relevant Config objects (i.e., the Configs know how to write themselves to
   a file: the save() method).

- All relevant function calls in the classes for the above four modules has
   also been rewritten.  Only personal code requires any further
   modification.  A summary of the changes per module is given below with
   examples:

   - Sextractor
     - The specification of the configuration and parameter lists have been
       changed.
       - old call:
         > from astro.main.Config import create_config
         > config = create_config('SExtractor')
         > Sextractor.sex(filename, param=list_of_params,
                          **config.get_kw_dict())
       - new call:
         > from astro.main.Config import create_config, create_params
         > config = create_config('sextractor')
         > params = create_params('sextractor',
                                  class_defaults=list_of_params)
         # Assignment here is optional as the Sextractor call will check
           for and correct the PARAMETERS_NAME if necessary.
         > config.PARAMETERS_NAME = params.filename
         > Sextractor.sex(filename, params=params, config=config)
     - cosmic_sex is removed because the call is the same as sex but with
       CosmicConfig and CosmicParams instances.
       - old call:
         > config = create_config('Cosmic')
         > Sextractor.cosmic_sex(filename, param=list_of_params,
                                 **config.get_kw_dict())
       - new call:
         > config = create_config('cosmic')
         > params = create_params('cosmic')
         > Sextractor.sex(filename, params=params, config=config)

   - Swarp
     - The specification of the configuration has changed.
       - old call:
         > config = create_config('Swarp')
         > Swarp.swarp(image_links, **config.get_kw_dict())
       - new call:
         > config = create_config('swarp')
         > Swarp.swarp(image_links, config=config)
     - The swarp_rename_output has been removed because the call is identical
       to the swarp call.  The swarp call tests config options before
       renaming, the swarp_rename_output simply renames without checking.

   - LDAC
     - The specification of the configuration has changed.
       - old call:
         > from astro.external.LDAC import LDAC
         > config = create_config('Preastrom')
         > ldac = LDAC.LDAC()
         > ldac.preastrom(incats, outcats, refcats, astrom_ref_cat,
                          distances, **config.get_kw_dict())
       - new call:
         > from astro.external.LDAC import LDAC
         > config = create_config('preastrom')
         > ldac = LDAC.LDAC()
         > ldac.preastrom(incats, outcats, refcats, astrom_ref_cat,
                          distances, config)
     - The astrom and other calls are similar.

   - Dia
     - The specification of the configuration has changed and a factory
       function now supplies the Config instances.
       - old call:
         > from astro.main.DiaConfig import DiaMstackConfig
         > config = DiaMstackConfig()
         > Dia.dia_mstack(list, **config.get_kw_dict())
       - new call:
         > from astro.main.DiaConfig import create_config
         > config = create_config('diamstack')
         > Dia.dia_mstack(list, config=config)
     - All the other Dia programs are called in a similar fashion.

- All external program calls are now more uniform.
   - Those that need a configuration take a Config object assigned to the
     "config" parameter of the call (Sextractor takes a Params object
     assigned to the "params" parameter).
   - For all calls, the Config (and Params) object is optional.  If it is not
     given, the default configuration (and parameter list) is used
     automatically.

The changes described above have been fully tested with the unittests and 
committed to the "test" version of the opipe code-base.  They will remain 
there until fully qualified (approximately 1 month).  Once qualified, the 
changes will become part of the AWBASE version.  Until they are qualified, 
use of the test version for testing is recommended only if these newer 
features are required.  Please report any problems by replying to this 
message (reply to all) and keeping the subject line intact.

Cheers,


-=John