Collector

The collector object is responsible for collecting configuration and setting up converters

For example:

class JsonCollector(Collector):
    def start_configuration(self):
        return MergedOptions()

    def find_missing_config(self, configuration):
        assert "important_option" in configuration

    def extra_prepare(self, configuration, args_dict):
        configuration.update(
              {"some_option": args_dict["some_option"]}
            , source=<extra_prepare>
            )

    def read_file(self, location):
        return json.loads(location)

    def add_configuration(self, configuration, collect_another_source, done, result, src):
        configuration.update(result, source=src)
        for loc in result.get("others", []):
            collect_another_source(
                  os.path.join(os.path.dirname(src), loc)
                , prefix=os.path.splitext(loc)[1]
                )

    def extra_configuration_collection(self, configuration):
        def convert(p, v):
            return v * 2
        configuration.add_converter(
              Converter(
                  convert=convert
                , convert_path=["some", "contrived", "example"]
                )
            )

collector = JsonCollector()
collector.prepare(
      "/path/to/first_config_file.json"
    , {"some_option": "stuff"}
    )

#### /path/to/first_config_file.json
# { "hello": "there"
# , "others": ["some.json"]
# }

#### /path/to/some.json
# { "contrived":
#   { "example": 2
#   }
# }

collector.configuration["some_option"] == "stuff"
collector.configuration["some.contrived.example"] == 4

Hooks

class option_merge.collector.Collector

When using the Collector, it is expected that you implement a number of hooks to make this class useful.

exception BadConfigurationErrorKls(_errors)

exception BadFileErrorKls(message)

add_configuration(configuration, collect_another_source, done, result, src)

Hook to add to the configuration the loaded result from src into configuration

The collect_another_source function can be used to collect another source

And done is a dictionary of configuration we have already added

alter_clone_args_dict(new_collector, new_args_dict, *args, **kwargs)

Hook for altering args_dict given to a clone collector it must return a dictionary

This dictionary will be used in the prepare call for the new collector

extra_configuration_collection(configuration)

Hook to do any extra configuration collection or converter registration

extra_prepare(configuration, args_dict)

Hook for any extra preparation before the converters are activated

extra_prepare_after_activation(configuration, args_dict)

Hook for any extra preparation after the converters are activated

find_missing_config(configuration)

Hook to raise errors about missing configuration

home_dir_configuration_location()

Hook to return the location of the configuration in the user’s home directory

read_file(location)

Hook to read in a file and return a dictionary

setup()

Called at __init__ time

start_configuration()

Hook for starting the base of the configuration

Usage

Collector.prepare(configuration_file, args_dict, extra_files=None)

Prepare the collector!

• Collect all the configuration
• find missing configuration
• do self.extra_prepare
• Activate the converters
• Do self.extra_prepare_after_activation

Collector.clone(*args, **kwargs)

Create a new collector that is a clone of this one

Collector.register_converters(specs, Meta, configuration, NotSpecified)

Register converters

specs

a Dictionary of {(priority, [path]): spec}

Meta

The class to instantiate to create meta

The converter will call spec.normalise(meta, val)

configuration

The configuration to add the converter to