5.6 Including Files

Configuration files may include other configuration files. The format is the same as an option/setting pair except a special <include> option name is used.

For example:

# file1.ini
[DEFAULT]
<include> = file2.ini
retries = 3

# file2.ini
[DEFAULT]
timeout = 10

Is equivalent to:

# file1.ini
[DEFAULT]
timeout = 10
retries = 3

Inclusion of configuration files from within a section is the same as if the settings in the included file were defined within that section. If the included file contains sections, those section names are extended.

For example:

# system.ini
[RACK0]
<include> = rack0.ini

# rack0.ini
[DEFAULT]
desc = 'main rack'
[DEV0]
path = 192.168.0.0
[DEV1]
path = 192.168.0.1

Is equivalent to:

# system.ini
[RACK0]
desc = 'main rack'
[RACK0.DEV0]
path = 192.168.0.0
[RACK0.DEV1]
path = 192.168.0.1

The extended section key syntax may also be used with the <include> special option. For example, using rack0.ini from the last example:

# system.ini
[DEFAULT]
<include>[RACK0] = rack0.ini

Is equivalent to:

# system.ini
[RACK0]
desc = 'main rack'
path[DEV0] = 192.168.0.0
path[DEV1] = 192.168.0.1

Configuration files included within sections are not necessarily read immediately (or ever). The included files are added to a pending list and are only read if all the section keys that it is associated with are in the active key list for a particular option being requested when the parse() or get() methods are called.