Provide information on whether a value was defaulted

Consider:

"""Usage:
    foo.py [--knob=<n>]

Options:
    --knob=<n>   Set the knob to n. [default: 14]
"""
import pprint

from docopt import docopt


pprint.pprint(docopt(__doc__))

The following two command line invocations give the same result:

$ python foo.py
{'--knob': '14'}
$ python foo.py --knob 14
{'--knob': '14'}

This means there is no way to tell right now whether a parameter was explicitly passed by the user, or if it was not passed and a default was used.

I propose adding a '[defaulted]' key to the returned dict, which contains a set of all the values whose defaults were used. The new result would be:

$ python foo.py
{'--knob': '14', '[defaulted]': set(['--knob'])}
$ python foo.py --knob 14
{'--knob': '14', '[defaulted]': set([])}

The rationale is this will make it much easier to handle config files where you always want the command-line option to trump the config file option. As it is now, it’s impossible to do cleanly using the docopt API.

Alternative API:

args = docopt(__doc__)
pprint.pprint(args), args.defaulted('--knob')

Result:

$ python foo.py
{'--knob': '14'}, True
$ python foo.py --knob 14
{'--knob': '14'}, False

[joell]

As a further motivating example for resolving this ambiguity, consider merging command-line options with configuration file data loaded into a compatible dict object. Without any defaults specified in the docopt text, this is easy: Just merge the cli options and configuration file dictionaries by using the configuration-file value for every option that docopt assigned None to.

However, once default options are introduced, there’s a problem. If the user passed an explicit option with the same value as the default, then the user’s value should be used, not the one in the configuration file. But if the user did not specify a value and the configuration file holds a different value than the default, the configuration file’s value should override. Because it is impossible to determine if the option’s value was set by default or not, this cannot be resolved.

[csaftoiu]

cli default value makes sense semantically. It means: “If no value is specified anywhere, this is the value used.” If the program can run meaningfully with a default value, then it should. With your approach the program wouldn’t be able to run unless there exists a config file with a value for the given parameter. But it can make sense where a user can download a program and just run it without needing to set up any config file.

To recap, the semantics are sensible:

• If the value is not specified in either command line or config file, the default value is used.
• If the value is specified in the config file, then the config value is used.
• If the value is specified on the command line, the command line value is used.
• If the value is specified in both, the command line value should be used.

This last case is impossible to implement with docopt as it is now.