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

Environment Variables

When environment variables are enabled (by specifying env_prefix in docoptcfg), there are a few things to keep in mind.

Short Names

If you’ve got something like -c FILE --config=FILE in your docstring, only the --config part is relevant. Short option names are ignored in environment variables. So you can’t have something like PREFIX_C. Your end users will need to use PREFIX_CONFIG instead.

Hyphens

Hyphens in docopt options are underscores in environment variables (e.g. --mac-addr is PREFIX_MAC_ADDR).

Flags/Booleans

Flags in docopt options are handled in environment variables as booleans as well. Users will need to set their environment variable to true, yes, on, or 1. These are case insensitive so TRUE works too. Those values are interpreted as boolean True while anything else is considered False.

Environment variables set but empty are considered False as well.

So if you’ve got --verbose and the user has PREFIX_VERBOSE=true, then you’ll have a True value in your returned dictionary.

Repeating Options

Docopt supports repeating options by specifying an ellipses in the docstring. An example:

Test handling of ... options.

Usage:
    my_script [--config=FILE] [--flag]... [--key=VAL]...

Options:
    --config=FILE   Path INI config file.
    --flag          Boolean value.
    --key=VAL       Key value value.

In this case, docopt gives you integers for flags (instead of booleans) and lists for key/value options (instead of strings).

docoptcfg supports this in environment variables as well:

  1. Environment variables for flags are expected to be integers.
  2. Environment variables for key/values can be specified multiple times by appending integers from 0 or 1.

For example, the end user may specify PREFIX_FLAG=2 to mimic --flag --flag.

For key/value options they can set PREFIX_KEY=one, PREFIX_KEY0=two, and so on (up to 99 is supported). They can also start at 1: PREFIX_KEY=one, PREFIX_KEY1=two, PREFIX_KEY2=three. They can even skip the integer-less variable and do PREFIX_KEY0=one, PREFIX_KEY1=two and so on. The first variable must start either integer-less or with 0.

docoptcfg will keep looking for increments until it can’t find one. So if the user sets PREFIX_KEY0=one, PREFIX_KEY1=two, and PREFIX_KEY3=three, docoptcfg will only return ['one', 'two'].