API Reference

confiddler.load_config(path_or_file, schema={}, inject_defaults=True)[source]

Convenience wrapper around validate(). (This function accepts a file).

Load the config data from the given file (or path to a file), and validate it against the given schema.

All missing values will be inserted from schema defaults. If a setting is missing and the schema contains no default value for it, a ValidationError is raised.


If your config data is already loaded into a dict and you just want to validate it and/or inject defaults, see validate().

  • path_or_file – The raw config data. Either a file object or a file path.
  • schema – The config schema, already loaded into a Python dict.


confiddler.dump_default_config(schema, f=None, format='yaml')[source]

Convenience wrapper around emit_defaults(). (This function writes to a file).

Dump the default config settings from the given schema. Settings without default values will use "{{NO_DEFAULT}}" as a placeholder.

  • schema – The config schema
  • f – File object to which default config data will be dumped. If None, then the default config is returned as a string.
Either "json", "yaml", or "yaml-with-comments". The "yaml-with-comments" format inserts comments above each setting, populated with the setting’s "description" field from the schema.
Returns:None, unless no file was provided, in which case the default config is returned as a string.
confiddler.validate(instance, schema, base_cls=None, *args, inject_defaults=False, **kwargs)[source]

Drop-in replacement for jsonschema.validate(), with the following extended functionality:

  • Specifically allow types from ruamel.yaml.comments
  • If inject_defaults is True, this function modifies the instance IN-PLACE to fill missing properties with their schema-provided default values.

See the jsonschema FAQ for details and caveats.

confiddler.emit_defaults(schema, include_yaml_comments=False, yaml_indent=2, base_cls=None, *args, **kwargs)[source]

Emit all default values for the given schema.

Similar to calling validate({}, schema, inject_defaults=True), except:

  1. Ignore schema validation errors and ‘required’ property errors
  2. If no default is given for a property, inject "{{NO_DEFAULT}}", even if the property isn’t supposed to be a string.
  3. If include_yaml_comments is True, insert CommentedMap objects instead of ordinary dicts, and insert a comment above each key, with the contents of the property "description" in the schema.
  • schema – The schema data to pull defaults from
  • include_yaml_comments – Whether or not to return ruamel.yaml objects so that comments will be written when the data is dumped to YAML.
  • yaml_indent – To ensure correctly indented comments, you must specify the indent step you plan to use when this data is eventually dumped as yaml.

A copy of instance, with default values injected, and comments if specified.


This function can be used to fine-tune the format of exported YAML configs. (It is only needed rarely.)

By default, dump_default_config() uses ‘block style’:

>>> schema = {
      "properties": {
         "names": {
           "default": ['a', 'b', 'c']

>>> dump_default_config(schema, sys.stdout)
- a
- b
- c

But if you’d prefer for a particular value to be written with ‘flow style’, wrap it with flow_style():

>>> from confiddler import flow_style
>>> schema = {
      "properties": {
         "names": {
           "default": flow_style(['a', 'b', 'c'])

>>> dump_default_config(schema, sys.stdout)
names: [a, b, c]