tools.configuration – Configuration parser

Configuration set up

The custom ConfigParser provides two new functionalities to parse lists:

As base class uses the standard configparser.ConfigParser in python 3 and the backported version for python 2.7. See the configparser documentation for more info.

Examples

>>> import pyhetdex.tools.configuration as pconf
>>> # This can be imported only after `pyhetdex.tools.configuration` has been
>>> # imported
>>> from configparser import BasicInterpolation
>>> from configparser import ExtendedInterpolation
>>> # standard config parser interpolation
>>> stdparser = pconf.ConfigParser()
>>> # equivalent
>>> stdparser = pconf.ConfigParser(interpolation=BasicInterpolation())
>>> # extended config parser interpolation
>>> extparser = pconf.ConfigParser(interpolation=ExtendedInterpolation())
>>> # test mapping interface
>>> parser = pconf.ConfigParser()
>>> sections = {'section1': {'key1': 'value1',
...                          'key2': 'value2',
...                          'key3': 'value3'},
...             'section2': {'keyA': 'valueA',
...                          'keyB': 'valueB',
...                          'keyC': 'valueC'},
...             }
>>> parser.read_dict(sections)
>>> parser['section1']
<Section: section1>
>>> print(parser['section2']['keyA'])
valueA

# Configuration file: default interpolation
[general]
dir1 = /path/to
[section]
dir1 = /path/to
file1 = %(dir1)/file1

# Configuration file: extended interpolation
[general]
dir1 = /path/to
[section]
file1 = %{general:dir1}/file1

The configuration parser

class pyhetdex.tools.configuration.ConfigParser(*args, **kwargs)[source]

Bases: configparser.ConfigParser

Customise configuration parser

Parameters:
args : list

arguments passed to the parent class

kwargs : dict

keyword arguments passed to the parent class

interpolation : Interpolation instance

only for python 2: select which interpolation to use
read(filenames, encoding=None)[source]

Read and parse a filename or a list of filenames. Return the list of successfully read files.

See configparser.ConfigParser.read() for more information

read_string(string, source='<string>')[source]

Read configuration from a given string. See configparser.ConfigParser.read_string() for more information

get_list_of_list(section, option, use_default=False, cast_to=<class 'str'>)[source]

A convenience method which coerces option in the specified section to a list of lists. If the options is empty returns [[None, None]].

Parameters:
section : string

name of the section

option : string

name of the option

use_default : bool

whether default to [[None, None]]

cast_to : type, optional

convert each element to the given type; default convert to string. The bool case is treated especially to comply with the ConfigParser standards.
Returns:
value : list of lists

parsed option
Raises:
NoOptionError

if the option doesn’t exist and no default required

Examples

>>> # cat settings.cfg:
>>> # [section]
>>> # wranges_bkg = 3500-4500,4500-5500
>>> conf = ConfigParser()
>>> conf.read_dict({"section": {"wranges_bkg": "3500-4500,4500-5500"}})
>>> conf.get_list_of_list("section", "wranges_bkg")
[['3500', '4500'], ['4500', '5500']]
>>> conf.get_list_of_list("section", "wranges_bkg", cast_to=float)
[[3500.0, 4500.0], [4500.0, 5500.0]]
>>> conf.get_list_of_list("section", "not_exist")
... 
Traceback (most recent call last):
...
NoOptionError: No option 'not_exist' in section: 'section'
>>> conf.get_list_of_list("section", "not_exist", use_default=True)
[[None, None]]
get_list(section, option, use_default=False, cast_to=<class 'str'>)[source]

A convenience method which converts the option in the specified section from a comma separated list to a python list.

If the options is empty returns the empty list [].

Parameters:
section : string

name of the section

option : string

name of the option

use_default : bool, optional

whether default to []

cast_to : type, optional

convert each element to the given type; default convert to string. The bool case is treated especially to comply with the ConfigParser standards.
Returns:
value : list of lists

parsed option
Raises:
NoOptionError

if the option doesn’t exist and no default required

Examples

>>> # cat settings.cfg:
>>> # [section]
>>> # wranges_iq = 3500, 4500, 5500
>>> conf = ConfigParser()
>>> conf.read_dict({"section": {"wranges_iq": "3500, 4500, 5500"}})
>>> conf.get_list("section", "wranges_iq")
['3500', '4500', '5500']
>>> conf.get_list("section", "wranges_iq", cast_to=int)
[3500, 4500, 5500]
>>> conf.get_list("section", "not_exist")
... 
Traceback (most recent call last):
...
NoOptionError: No option 'not_exist' in section: 'section'
>>> conf.get_list("section", "not_exist", use_default=True)
[]
read_dict(dictionary, source='<dict>')

Read configuration from a dictionary.

Keys are section names, values are dictionaries with keys and values that should be present in the section. If the used dictionary type preserves order, sections and their keys will be added in order.

All types held in the dictionary are converted to strings during reading, including section names, option names and keys.

Optional second argument is the `source’ specifying the name of the dictionary being read.

read_file(f, source=None)

Like read() but the argument must be a file-like object.

The `f’ argument must be iterable, returning one line at a time. Optional second argument is the `source’ specifying the name of the file being read. If not given, it is taken from f.name. If `f’ has no `name’ attribute, `<???>’ is used.

Utilities

pyhetdex.tools.configuration.override_conf(conf, args, prefix='setting', sep='__', nones=[None, []])[source]

Overrides entries in conf with values in args.

The function collects all the attributes of args of the form: prefix<sep>section<sep>option. For each one, if its value is not in nones, replace the option in the section of the configuration object with the corresponding value in args; the value is cast to a string. The section and option must exist in conf.

Parameters:
conf : configparser.ConfigParser or child instance

configuration object. It must support the mapping protocol

args : object

object containing the attributes used for overriding the configuration

prefix : string, optional

prefix used to find the attributes in args that are considered for the override

sep : string, optional

the string that separate prefix, the section name and the option name

nones : list, optional

if the value of the option is in this list, do not insert it in conf
Returns:
conf : ConfigParser

updated configuration object

Examples

>>> from argparse import Namespace
>>> c = ConfigParser()
>>> c.read_dict({'sec1': {'opt1': 'val1'}})
>>> print(c['sec1']['opt1'])
val1
>>> c = override_conf(c, Namespace(setting__sec1__opt1=None))
>>> print(c['sec1']['opt1'])
val1
>>> c = override_conf(c, Namespace(setting__sec1__opt1='val2'))
>>> print(c['sec1']['opt1'])
val2