Skip to main content
This is a pre-production deployment of Warehouse. Changes made here affect the production instance of PyPI (pypi.python.org).
Help us improve Python packaging - Donate today!

Configuration file support for click applications.

Project Description

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. If no --config option is provided either via CLI or an environment variable, the module will search for a file named config in the appropriate directory for your OS.

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.

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 x`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.

Release History

This version
History Node

0.4.2

History Node

0.4.1

History Node

0.4.0

Download Files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

File Name & Hash SHA256 Hash Help Version File Type Upload Date
click_config_file-0.4.2-py2.py3-none-any.whl
(7.3 kB) Copy SHA256 Hash SHA256
py2.py3 Wheel Jan 23, 2018
click_config_file-0.4.2.tar.gz
(4.1 kB) Copy SHA256 Hash SHA256
Source Jan 23, 2018

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting