Packages

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:

config.yaml

defaults:
  - server/apache

debug: false

server/apache.yaml

defaults:
  - db: mysql

name: apache

server/db/mysql.yaml

name: mysql

server/db/sqlite.yaml

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 my_app.py

server:
  db:
    name: mysql
  name: apache
debug: 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.

config.yaml

defaults:
  - server/apache@admin

debug: false

server/apache.yaml

defaults:
 - db@backup: mysql

name: apache

Output config

admin:
  backup:
    name: mysql
  name: apache
debug: 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:

config_group/config.yaml

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. @_global_.foo 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.

server/db/mysql.yaml

# @package foo.bar
name: 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.

config.yaml

defaults:
 - server/db@src: mysql
 - server/db@dst: mysql

$ python my_app.py

src:
  name: mysql
dst:
  name: mysql

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

$ python my_app.py server/db@src=sqlite

src:
  name: sqlite
dst:
  name: mysql