API

class modularyze.modularyze.ConfBuilder(yaml=None, attr_sep='.')

This configuration builder works with a jinja2 templated yaml file. It first renders the template, then parses the yaml file.

It can be used to directly instantiate almost any object, provided that it’s type has been registered first.

__call__(*args, **kwargs)

Alias of build()

build(spec, context=None, root_path=None)

Build the final configuration by first rendering the spec as a template and then building the resulting YAML document.

:param Same as render():

Returns: Config object (dict, list, etc…)

property constructors

Return registered constructors and multi-constructors

static default_tag_name(obj)

The default tag name for an object is simply the object’s name prefixed by an exclamation point

static get_data(loader, node)

Convert node to it’s builtin representation ScalarNode -> one of bool, int, float, etc… SequenceNode -> list, tuple, … MappingNode -> dictionary, omap, …

hash(spec, context=None, root_path=None)

Hash a config. This hash will depend on the spec (conf string or file) as well as any context it depends on.

For the hash to be computed, the config is first normalized (see normalize()) as a key-sorted, json-dumped string and then hashed using the SHA3-256 algorithm.

:param Same as render():

Returns

The config’s unique hash as an int

load(document)

Load and instantiate the rendered config (full-YAML document).

Args: document: YAML document as a string.

Returns: Config object (dict, list, etc…)

normalize(spec, sort_keys=False, raw=False, context=None, root_path=None)

Get the config pre-initialization of members as a normalized representation.

Args: Same as render()

Returns: Normalized representation of configuration as a string.

register_constructors(*callables, **named_callables)

For an object to be instantiated, or a function to be called, when loading the configuration from yaml, it needs to be first registered by the builder. This registration creates a default constructor for that callable that yaml will use when it parses that callable’s tag.

A tag can either be specified, or if left out, a default tag will be used (see default_tag_name()).

Parameters

• callables – classes or functions to register_constructors with a default tag

• named_callables – other callables with specified tag names

register_constructors_from_modules(*modules, filter_funcs=None, **named_modules)

It’s often helpful to register_constructors from a module. This method registers all attributes of a given module that satisfy the filter functions, prepending a given prefix to the autogenerated tag name.

This is similar to using from package import * as it will clutter the namespace and probably over-register_constructors. It is often best to use register_multi_constructors_from_modules.

Note: This might fail if the __name__ attribute is not set on either an unnamed module, or any sub-module/callable.

Parameters

• modules – List of modules to register implicitly. These modules will be registered using an inferred tag-prefix of ‘!<module name>’.

• named_modules – Dictionary of tag-prefixes -> modules to register explicitly. The modules passed as kwargs will be registered with the key as their tag.

• filter_funcs – these provide a way to limit registration by filtering out any callables that don’t meet a requirement. By default any private attribute or non-class attribute is not registered.

register_multi_constructors(*callables, **named_callables)

This registration creates a default multi-constructor for the given callables.

A tag prefix can either be specified, or if left out, a default tag prefix will be used (see default_tag_name()).

Parameters

• callables – classes or functions to register a multi-constructors with a default tag prefix

• named_callables – other callables with specified tag prefix

register_multi_constructors_from_modules(*modules, **named_modules)

This method registers modules as multi-constructors enabling submodules to be accessed dynamically and lazy loaded.

This is favored over register_constructors_from_modules as it only adds one multi-constructor per module instead of numerous single use constructors per module.

Parameters

• modules – List of modules to register implicitly. These modules will be registered using an inferred tag-prefix of ‘!<module name>’. Note that this might fail if the __name__ attribute is not set.

• named_modules – Dictionary of tag-prefixes -> modules to register explicitly. The modules passed as kwargs will be registered with the key as their tag.

render(spec, context=None, root_path=None)

Method responsible for rendering the config template. If context is a valid (simple) yaml file then it will be used as context for jinja’s rendering, otherwise context should be a dictionary or object that can be unpacked using the double-star operator (**).

Parameters

• spec – config path or string

• context – context to pass to templating engine

• root_path – path of config directory (only needed if config is multi-file)

Returns

A rendered template, which is the fully formed YAML config file.

vanilla_load(document, ignore_unknown=False)

Reset the yaml loader by temporarily clearing it’s constructors, load the document, then add back the constructors. If ignore_unknown, unrecognized tags will be replaced by None, otherwise they will be converted to their text representation.

Note: This relies on monkey-patching the yaml parser, so use with care. See code for more.