Example config generationΒΆ

CONFspirator supports generated config files from the built config tree. These will populate all the fields, and if a default value is supplied will put that in place.

To use this functionality you must supply your root config group, and call the function with a file location. CONFspirator does not supply any CLI support for this, so you will want to build a command into your application or project to import your root config group, and call the generation function.

Assuming the config group as shown in the getting started page:

# ./my_app/config/root.py
from confspirator import groups, fields

root_group = groups.ConfigGroup(
    "my_app", description="The root config group.")
root_group.register_child_config(
    fields.StrConfig(
        "top_level_config",
        help_text="Some top level config on the root group.",
        default="some_default",
    )
)

# ./my_app/config/sub_section.py
from confspirator import groups, fields
from my_app.config import root

sub_group = groups.ConfigGroup(
    "sub_section", description="A sub group under the root group.")
sub_group.register_child_config(
    fields.BoolConfig(
        "bool_value",
        help_text="some boolean flag value",
        default=True,
    )
)

root.root_group.register_child_config(sub_group)

You would call the generation logic as follows:

# ./my_app/commands.py

import confspirator
from my_app.config import root


def create_config():
    confspirator.create_example_config(
        root.root_group, "conf.yaml")

This would produce a yaml config example that looks like the following:

# String - Some top level config on the root group.
top_level_config: some_default
# A sub group under the root group.
sub_section:
  # Boolean - some boolean flag value
  bool_value: true

Alternatively if you wanted toml instead, you can simply change the file extension and the exporter will pick that up. Or if you want to use an extension other than yaml or toml you can explicitly set output_format to either yaml or toml, and the file extension will be ignored:

confspirator.create_example_config(
    root.root_group, "my_app.conf", output_format="toml")

In any case, if by extension or explicit output format toml is set, your generated example config will look as follows:

[my_app]
# String - Some top level config on the root group.
top_level_config = "some_default"

# A sub group under the root group.
[my_app.sub_section]
  # Boolean - some boolean flag value
  bool_value = true

For complicated nested configs yaml tends to be easier to deal with, but for people with a preference for ini style configs toml does provide a good option that still allows nesting.