Warning: This document is for the development version of docoptcfg. The latest version is v1.0.2.

docoptcfg

Love using docopt over argparse or Click? Wish it took care of environment variables and/or config files?

docoptcfg is a wrapper for docopt which handles reading configuration data from environment variables and/or an INI/INF configuration file. You can (1) enable only the environment variable part, (2) only the config file part, (3) or use both at the same time:

  1. args = docoptcfg(__doc__, env_prefix='MYAPP_')
  2. args = docoptcfg(__doc__, config_option='--config')
  3. args = docoptcfg(__doc__, config_option='--config', env_prefix='MYAPP_')

Compatibility

docoptcfg is supported on Linux, OS X, and Windows:

  • Python 2.6, 2.7, PyPy, PyPy3, 3.3, 3.4, and 3.5 supported on Linux and OS X.
  • Python 2.7, 3.3, 3.4, and 3.5 supported on Windows (both 32 and 64 bit versions of Python).

Simple Example

Here’s a simple example of what you can do with docoptcfg. Think of docoptcfg as using configuration files and/or environment variables to set defaults. Command line arguments will always trump other sources. Environment variables also trump config files. The order of operations from low to high priority is: config file -> env var -> args.

#!/usr/bin/env python
"""My little script.

Usage:
    my_script [options]

Options:
    -c FILE --config=FILE       Path to INI config file.
    -l FILE --log-file=FILE     Write to this log file.
    -r NUM --runtime=NUM        How long before exiting.
    -t NUM --threads=NUM        Number of threads.
"""

from docoptcfg import docoptcfg

print docoptcfg(__doc__, env_prefix='MYAPP_', config_option='--config')

Now let’s create a configuration file and name it config.ini:

[my_script]
log-file = file_config.log
runtime = 10
threads = 11

And finally we run it like this:

export MYAPP_LOG_FILE=file_env.log
export MYAPP_RUNTIME=20
./my_script.py -c config.ini -r 30

Our result is:

{
    '--config': 'config.ini',
    '--log-file': 'file_env.log',
    '--runtime': '30',
    '--threads': '11',
}