jochman / click_config_file

Configuration file support for Click applications

Click config file

Easily add configuration file support to your Click applications by adding a single no-arguments decorator.

Basic usage

click-config-file is designed to be a usable by simply adding the appropriate decorator to your command without having to supply any mandatory arguments. It comes with a set of sensible defaults that should just work for most cases.

Given this application:

@click.command()
@click.option('--name', default='World', help='Who to greet.')
@click_config_file.configuration_option()
def hello(name):
    click.echo('Hello {}!'.format(name))

Running hello --help will give you this:

Usage: hello [OPTIONS]

Options:
  --name TEXT    Who to greet.
  --config PATH  Read configuration from PATH.
  --help         Show this message and exit.

If the configuration file does not exist, running hello will do what you expect:

Hello World!

With this configuration file:

name="Universe"

Calling hello will also do what you expect:

Hello Universe!

Calling hello --name Multiverse will override the configuration file setting, as it should:

Hello Multiverse!

The default name for the configuration file option is --config.

Command line and environment options will override the configuration file options. Configuration file options override default options. So the resolution order for a given option is: CLI > Environment > Configuration file > Default.

Options

Although configuration_option is designed to work without any mandatory arguments, some optional parameters are supported:

implicit

Default: True

By default configuration_option will look for a configuration file even if no value for the configuration option was provided either via a CLI argument or an environment variable. In this case the value will be set implicitly from cmd_name and config_file_name as described below.

If set to False the configuration file settings will only be applied when a configuration file argument is provided.

cmd_name

Default: ctx.cmd_info

The name of the decorated command. When implicitly creating a configuration file argument, the application directory containing the configuration file is resolved by calling click.get_app_dir(cmd_name).

This defaults to the name of the command as determined by click.

config_file_name

Default: config

When implicit is set to True, this argument provides the name of the configuration file inside the application directory.

In addition to the arguments above, all arguments for click.option() and click.File() are supported.

Supported file formats

By default click-config-file supports files formatted according to Configobj's unrepr mode.

You can add support for additional configuration providers by setting the provider keyword argument. This argument expects a callable that will take the configuration file path and command name as arguments and returns a dictionary with the provided configuration options.

The command name is passed in order to allow for a shared configuration file divided by sections for each command.

For example, this will read the configuration options from a shared JSON file:

def myprovider(file_path, cmd_name):
    with open(file_path) as config_data:
        return json.load(config_data)[cmd_name]

@click.command()
@click.option('--name', default='World')
@click_config_file.configuration_option(provider=myprovider)
def hello(name):
    click.echo('Hello {}!'.format(name))

Installation

pip install click-config-file

Why?

There are several existing implementations of config file support for Click, however they seem to lack one or more of the following features:

• Sensible defaults
• Proper handling of resolution order
• Support for multi value options, multiple options or a combination of both

In contrast this module may lack some more sophisticated features of the other implementations. This is a deliberate choice as this module is intended to be a simple option that Just Works with sensible defaults.