Skip to main content
Version: 1.3

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