Skip to main content
Python Software Foundation 20th Year Anniversary Fundraiser  Donate today!

Helpers to load your application configuration from YAML files

Project description


CI codecov

A YAML parser with advanced functionalities to ease your application configuration.

Who is this library for ?

This library is meant to be used in medium to large-scale applications, that have a lot of parameters to configure.

Modular applications especially can greatly benefit from using configue to easily inject new modules.


Run pip install configue to install from PyPI.

Run pip install . to install from sources.

This project follows the (Semantic Versioning Specification)[]. All breaking changes are described in the Changelog.


Basic usage

This library uses PyYAML to parse the YAML files and return the file content.

from configue import load_config_from_file

config = load_config_from_file("/path/to/yaml/file.yml")

Instantiating classes

Use () in your YAML files to instantiate classes:

# config.yml
(): "my_project.MyAwesomeClass"
my_argument: "my_value"
  (): "my_project.my_module.MyOtherClass"
from configue import load_config_from_file
from my_project import MyAwesomeClass
from my_project.my_module import MyOtherClass

my_instance = load_config_from_file("config.yml")
assert isinstance(my_instance, MyAwesomeClass)
assert my_instance.my_argument == "my_value"
assert isinstance(my_instance.my_other_argument, MyOtherClass)

Note that the instance is lazy-loaded if it is contained in a list or a dictionary, it is only created when the element is called.

Loading external variables

# config.yml
my_argument: ext://my_project.my_module.my_variable

When a value starts with ext://, the value will be imported from the corresponding python module.

Loading internal variables

# config.yml
        (): my_project.MyClass
my_instance_shortcut: cfg://my_object.my_instance

When a value starts with cfg://, the value will be loaded from the same configuration file (useful for a DRY configuration).

Environment variables

If you want to load an environment variable in your YAML config file, you can use this syntax:

# config.yml
my_key: ${var_name}

This will resolve as "my_value" if the environment variable var_name is set to this value.

If you need a default value in case the environment variable is not set:

# config.yml
my_key: ${var_name-default}

You can insert this syntax in the middle of a string:

# config.yml
my_key: prefix${var_name-default}suffix

This will resolve as "prefixmy_value_suffix" if the value is set, "prefixdefaultsuffix" if it is not.

If your value string starts with a special character (%-.[]{},?:*&!|>\), you need to quote it for the YAML parser. Unfortunately, this breaks the detection of the ${} pattern. You have to use this syntax instead:

my_final_key: !env "{${var_name}}"

This will resolve as "{my_value}".

In all those examples, if both the variable and the default value are not defined, the value is replaced by an empty string, and then the field value is cast by the yaml loader ("" becomes None, "10" becomes 10, and "true" becomes True).

Lists in environment variables

You can store a list in your environment variable, and use this syntax to split it on commas:

# config.yml
my_list: !list ${my_var}

with my_var=my_first_value,my_second_value

This will resolve as ["my_value", "my_second_value"].

Relative paths

If you want to expand a relative path in your YAML config file:

# config.yml
my_path: !path my_folder/my_file.txt  

Assuming your file structure looks like this:

├── config.yml
├── my_folder
    ├── my_file.txt

The path is resolved starting from the folder containing the parent yml file, this example will resolve to /root/my_folder/my_file.txt

Do not start the path with / as it will be treated as an absolute path instead.

You can use environment variables in your file path.

Importing other files

You can import another file directly in your YAML config file:

# config.yml
my_import: !import my_folder/my_other_config.yml
# my_other_config.yml
- var_1
- var_2

The path is resolved starting from the folder containing the parent yml file, this example will resolve to "my_import": [var_1, var_2]

Do not start the import path with / as it will be treated as an absolute path instead.

You can use environment variables in your import path.


Install the development dependencies with pip install -r dev.requirements.txt.

Run python -m unitttest discover to run the tests.

Run pylint configue to check the files linting.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for configue, version 3.0.4
Filename, size File type Python version Upload date Hashes
Filename, size configue-3.0.4-py3-none-any.whl (7.9 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size configue-3.0.4.tar.gz (7.4 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page