Config¶

Config files can be used to populate defaults for arguments and options, they can also contain additional data that can be accessed via the config parameter. Config files can contain additional data, where the defaults are retrieved from is specified in the specific file format sections.

location¶

If the parameters for your package are provided by a data structure in a variable named _package_data in your __init__.py, a default location will be created based on the full_package_name You can just specify the type (e.g. !Config YAML and if the full_package_name is set to abc the config is loaded from the file loaded from ~/.config/abc/abc.yaml

_package_data = dict(
    full_package_name='abc',
    version_info=(3, 2, 1),
    __version__='3.2.1',
    ....
)


version_info = _package_data['version_info']
__version__ = _package_data['__version__']

_cligen_data = """\
.....
"""

In all other cases you need to provide a scalar string to !Config, that is a path and the suffix determines the type of config file. If there is no suffix from which the config file can be determined you can provide a list !Config [YAML, ~/bla.tmp].

If the scalar string (or the second element in the list) starts with ~ or / and absolute path is assumed (and ~ is expanded). Else if there is a '/' in the scalar string, a path relative to the config_dir is assumed. If there is no / in the string a package name or package name with namespace is assumed.

The config directory follows the XDG base directory specification or %APPDATA% on Windows. Assuming the config directory is ~/.config then

!Config [YAML, ~/tmp/abc.def]

will load ~/tmp/abc.def, and

!Config tmp/abc.yaml

will load ~/.config/tmp/abc.yaml, and

!Config [INI, ruamel.edit]

will load ~/.config/ruamel.edit/edit.ini

YAML¶

This assumes that root of the YAML document loaded contains a mapping the values for 'global' are taken to have values for non-subcommand options/arguments, the keys correspondig to a subcommand are taken to have values for those subcommand options/arguments. The values themselves need to be mappings for which the key corresponds to the first long option name (or !Dest value). Root level keys that are not subcommands can be used for other, non-default, data by the program.

If not specified differently via the %YAML directive in the file, YAML 1.2 is assumed.

Make sure your package installs ruamel.yaml, as this dependency is used to load the YAML file.

PON¶

The Python Object Notation is a compact and readable notation for data. It relies on ast (the full parsing code (~100 lines) is included in __main__.py) and there are no dependencies beyond that.

The .pon file needs to contain a dict definition with the keys interpreted in the same way as for YAML. Since global is a keyword, you cannot specify dict(global=dict(verbose=1)) and need to use dict(glbl=dict(verbose=1)) or the less readable {"global": {"verbose": 1}}.

INI¶

From a file using the INI format the sections [defaults.global] and [defaults.subcommand_name] are taken and the key-value pairs in those sections used for defaults.