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
# { "some":
#   { "contrived":
#     { "example": 2
#     }
#   }
# }

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

Hooks

class delfick_project.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, configuration=None, announce_converters=True)

Register converters

specs

a Dictionary of {key: spec}

Where key is either a string or a tuple of strings

You would use a tuple of strings if you want to have a nested key, which is useful if any part of the key has dots in it.

For example ("images", "ubuntu.16.04")

configuration

The configuration to add the converter to.

This defaults to self.configuration

announce_converters

If True (default) then we log when we convert these keys

For example:

collector.register_converters({
    "one": sb.string_spec(),
    ("two", "three"): sb.integer_spec()
})