b3j0f.conf 0.3.22

Configuration

The package b3j0f.conf.model provides Configuration class in order to inject configuration resources in a configurable class.

Configuration resources respect two levels of configuration same as the ini configuration model. Both levels are respectively:

• Category: permits to define a set of parameters unique by name.

• Parameter: couple of property name and value.

And all categories/parameters are embedded in a Configuration class.

Configuration and Categories are ordered dictionaries where key values are inner element names. Therefore, Parameter names are unique per Categories, and Category/Parameter names are unique per Configuration.

Parameter Overriding

In a dynamic and flexible way, one Configurable class can be bound to several Categories and Parameters. The choice is predetermined by the class itself. That means that one Configurable class can use several configuration resources and all/some/none Categories/Parameters in those resources. In such a way, the order is important because it permits to keep only last parameter values when parameters have the same name.

This overriding is respected by default with Configurable class inheritance. That means a sub class which adds a resource after its parent class resources indicates than all parameters in the final resources will override parameters in the parent class resources where names are the sames.

Configurable

A Configurable class is provided in the b3j0f.conf.configurable.core module. It permits to get parameters from configuration resources and setup them to a python object or in a method/function parameters.

It inherits from the b3j0f.annotation.Annotation class (annotation). That means it can be used such as an annotation (decorator with annotation functions). For example, bound Configurables to an object o are retrieved like this: Configurable.get_annotations(o).

In order to perform a configuration setup, it uses:

• conf: configuration model.

• drivers: configuration resource drivers.

• scope: parsing execution scope.

• besteffort: boolean flag which aims to resolve automatically absolute object path. True by default.

• safe: boolean flag which aims to cancel calls to I/O functions. True by default.

• logger: logger which will handle all warning/error messages. None by default.

Annotated elements are bound and can all be (re)configured once in using the method applyconfiguration.

Driver

Drivers are the mean to parse configuration resources, such as files, DB documents, etc. from a configuration model provided by a Configurable object.

By default, conf drivers are able to parse json/ini/xml files. Those last use a relative path given by the environment variable B3J0F_CONF_DIR or from directories (in this order) /etc, /usr/local/etc, ~/etc, ~/.config, ~/config, current execution directory or absolute path.

Bind configuration files to an object

Bind the configuration file ~/etc/myobject.conf and ~/.config/myobject.conf to a business class MyObject (the relative path ~/etc can be changed thanks to the environment variable B3J0F_CONF_DIR).

The configuration file contains a category named MYOBJECT containing the parameters:

• myattr equals 'myvalue'.

• six equals 6.

• twelve equals six * 2.0.

Let the following configuration file ~/etc/myobject.conf in ini format:

[MYOBJECT]
myattr = myvalue
twelve = =@six * 2.0

Let the following configuration file ~/.config/myobject.conf in json format:

{
  "MYOBJECT": {
    "six": 6
  }
}

The following code permits to load upper configuration to a python object.

from b3j0f.conf import Configurable

# instantiate a business class
@Configurable(paths='myobject.conf')
class MyObject(object):
    pass

myobject = MyObject()

# assert attributes
assert myobject.myattr == 'myvalue'
assert myobject.six == 6
assert isinstance(myobject.six, int)
assert myobject.twelve == 12
assert isinstance(myobject.twelve, float)

The following code permits to load upper configuration to a python function.

from b3j0f.conf import Parameter, Array

# instantiate a business class and ensure twelve is converted into an integer and a string with commas is converted into an array of integers.
@Configurable(
  paths='myobject.conf',
  conf=[
    Parameter('default', value=len('default')),  # default value for the parameter default
    Parameter('twelve', ptype=int),
    Parameter('integers', svalue='1,2,3', ptype=Array(int))
)
def myfunc(myattr=None, six=None, twelve=None, default=None):  # Only None values will be setted by the configuration
    return myattr, six, twelve, default

myattr, six, twelve, default = myfunc(twelve=46)

# assert attributes
assert myobject.default == 7
assert myobject.myattr == 'myvalue'
assert myobject.six == 6
assert myobject.twelve == 46
assert isinstance(myobject.twelve, int)
assert myobject.integers == [1, 2, 3]

Class configuration

from b3j0f.conf import category
from b3j0f.conf import Configurable

# class configuration
@Configurable(conf=category('land', Parameter('country', value='fr')))
class World(object):
    pass

world = World()
assert world.country == 'fr'

One configuration with several objects

land = Configurable.get_annotations(world)[0]  # class method for retrieving Configurables

@land  # bind land to World2
class World2(object):
    pass

world2 = World2()

assert World2().country == 'fr'

class World3(object):
    pass

world3 = World3()
land.applyconfiguration([world3])  # apply land on world3 without annotated it

assert world3.country == 'fr'

world3s = (land(World3()) for _ in range(5))  # annotate a set of worlds

land.conf['land']['country'] = 'en'  # change default country code

land.applyconfiguration()  # update all annotated objects

for _world3 in world3s:
    assert _world3.country == 'en'

assert world2.country == 'en'

assert world3.country == 'fr'  # check not annotated element has not changed

Configure object constructor

land.autoconf = False  # disable autoconf

@land
class World4(object):
    def __init__(self, country=None):
        self.safecountry = country

world4 = World4()

assert not hasattr(world4, 'country')  # disabled auto conf side effect
assert world4.safecountry = 'en'

land.applyconfiguration()  # configure all land targets

assert world4.country == 'en'

Configure function parameters

@land
def getcountry(country=None):
    print(country)
    return country

assert getcountry() == 'en'

land['land']['country'] = 'fr'

assert getcountry() == 'fr'

Configure embedded objects

from b3j0f.conf import configuration, category, Parameter

class SubTest(object):
    pass

@Configurable(
    conf=(
        configuration(
            category('', Parameter('subtest', value=SubTest)),
# the prefix ':' refers (recursively) to a sub configuration for the parameter named with the suffix after ':'
            category(':subtest', Parameter('subsubtest', value=SubTest)),
            category(':subtset:subsubtest', Parameter('test', value=True))
        )
    )
)
class Test(object):
    pass

test = Test()

assert isinstance(test.subtest, SubTest)
assert isinstance(test.subtest.subsubtest)
assert not hasattr(test.subtest, 'test')
assert test.subtest.subsubtest.test is True

# and you can still apply configuration
Configurable.get_annotations(test)[0].conf[':subtset:subsubtest']['test'] = False
applyconfiguration(targets=[test])

assert test.subtest.subsubtest.test is False

Configure metaclasses

from six import add_metaclass

@Configurable(conf=Parameter('test', value=True))
class MetaTest(type):
    pass

@add_metaclass(MetaTest)
class Test(object):
    pass

test = Test()

assert test.test is True