Includes

Configurations can be split into multiple files using includes. To include a file, add an includes key with a list of files to include. For instance:

# scenario.yaml
includes:
  - ../config.yaml
  - custom/extra

database:
  pool_size: 20

Include paths are resolved relative to the file containing them and the .yaml extension is optional.

Package Paths

When distributing configuration files inside an installed Python package, it can be convenient to refer to the files shipped in the distribution. This can be done using package paths.

A package path can be absolute or relative:

• Absolute path: package://package_name/path/to/file.yaml
• Relative path: package:file.yaml

Absolute paths are resolved by looking for the path to the file in the named package. Relative paths look for the file relative to the package configured as the default config package. Package names must be the one used to import the package in Python, and not the PyPI package name (e.g., my_package, not my-package). As with regular paths, the .yaml extension can be omitted.

The default config package is set when constructing the config:

config = Config(default_config_package="my_package/configs")

With that in place, the following includes are equivalent:

includes:
  - package:config
  - package://my_package/configs/config.yaml

A relative package: include raises a ValueError if no default_config_package is set; a package-absolute package://... include always resolves.