Skip to main content
Version: 1.1


The package determines where the content of each input config is placed in the output config. The default package of an input config is derived from its Config Group. e.g. The default package of server/db/mysql.yaml is server.db.

The default package can be overridden in the Defaults List or via a Package Directive at the top of the config file. Changing the package of a config can be useful when using a config from another library, or when using the same config group twice in the same app.

The priority for determining the final package for a config is as follows:

  1. The package specified in the Defaults List (relative to the package of the including config)
  2. The package specified in the Package Directive (absolute)
  3. The default package

We will use the following configs in the examples below:

defaults:  - server/apache
debug: false

defaults:  - db: mysql
name: apache

name: mysql
name: sqlite
Config directory structure
โ”œโ”€โ”€ serverโ”‚   โ”œโ”€โ”€ dbโ”‚   โ”‚   โ”œโ”€โ”€ mysql.yamlโ”‚   โ”‚   โ””โ”€โ”€ sqlite.yamlโ”‚   โ””โ”€โ”€ apache.yamlโ””โ”€โ”€ config.yaml

An example using only default packages#

The default package of config.yaml is the global package, of server/apache.yaml is server and of server/db/mysql.yaml is server.db.

$ python
server:  db:    name: mysql  name: apachedebug: false

Overriding packages using the Defaults List#

By default, packages specified in the Defaults List are relative to the package of containing config. As a consequence, overriding a package relocates the entire subtree.

defaults:  - server/[email protected]
debug: false
defaults: - [email protected]: mysql
name: apache
Output config
admin:  backup:    name: mysql  name: apachedebug: false

Note that content of server/apache.yaml is relocated to admin and the content of server/db/mysql.yaml to admin.backup.

Default List package keywords#

We will use this example, replacing <@PACKAGE> to demonstrate different cases:

defaults:  - /server/db<@PACKAGE>: mysql

Without a package override, the resulting package is config_group.server.db.
With the @_here_ keyword, The resulting package is the same as the containing config (config_group).

Absolute keywords:#
  • @_group_: _group_ is the absolute default package of the config (server.db)
  • @_global_: The global package. Anything following _global_ is absolute.
    e.g. becomes foo.

Overriding the package via the package directive#

The @package directive changes the package of a config file. The package specified by a @package directive is always absolute.

# @package foo.barname: mysql

To change the package to the global (empty) package, use the keyword _global_.

Using a config group more than once#

The following example adds the server/db/mysql config in the packages src and dst.

defaults: - server/[email protected]: mysql - server/[email protected]: mysql
$ python
src:  name: mysqldst:  name: mysql

When overriding config groups with a non-default package, the package must be used:

$ python server/[email protected]=sqlite
src:  name: sqlitedst:  name: mysql