skip to navigation
skip to content

docopt-rc 0.0.1

docopt-rc is a drop-in rc-file parser augmenter for docopt

docopt-rc is a drop-in rc-file parser augmenter for docopt.

Quick User’s Guide

These are the nessesary steps to use docopt-rc:

  1. Install the package
$ pip install docopt-rc
  1. Import into your project
from docopt import docopt
import rc
import myscript
  1. Run docopt to parse the command line arguments
args = docopt(__doc__, version='MyScript {v}'.format(v=myscript.__version__))
  1. Set up your script level defaults (lowest priority)
defaults = {
  'url': '',
  'category': 'news',
  'votes': 0
  1. Parse potential config-files, both in user home and in the current directory. Missing files are silently skipped.
# Merge the command line arguments with the defaults and any values
# found in either global (`$HOME`) or local (this folder) config files.
options = rc.extend_args(args, __file__, defaults, scopes=['global', 'local'])

That’s it. We have now merged the defaults <= user configs <= command line arguments.


For the time being I will refer you to the somewhat complete inline documentation for each function in the package.

Background & Motivation

Config files can unburden the command line and allow users to set user/project specific defaults. A common practice is to name such files .<script_name>rc, e.g. ‘.bashrc’, ‘.bowerrc’. The values in such an rc-file should take precedence over script level defaults but be overwritten by command line arguments.

I needed a very simple script that would parse both global (user), local (project), and custom config files and play nice with the excellent docopt package.

Flaws & Limitations

docopt, as great as it is, does come with a few limitations when trying to integrate with a config file parser. My solution has three nagging flaws:

  1. Boolean options (flags) become a major issue. There isn’t any built in way to flag False and probably won’t be either. This means you can’t override an options that defaults to True from a config file. The current solution is to avoid flags in favor of `–option=<bool>` where bool is (‘yes’, ‘no’, ‘true’, ‘false’).
  2. docopt provides a useful way to set defaults. Problem is that I couldn’t find a way to parse those defaults to compare what user supplied and default values. I therefore require all defaults to be set in a separate `dict` outside of the docstring.
  3. The intuative syntax for <position argument>, –option, command works great in-script but would be awkward as a requirement for user authored config files. Q.E.D.: I require that no two argument/option/command names be the same.


  1. DOES support YAML and JSON file formats (“JSON is YAML”)
  2. DOES convert docopt args to simpler versions by removing ‘–’ and ‘<>’
  3. DO NOT define your own defaults in the document string
  4. DO define defaults in a separate dict
  5. DO NOT use boolean arguments (flags) you want to overwrite.
  6. DO use –option=<bool> where ‘bool’ is ‘yes’/’no’ in favor of flags
  7. DO expect config files to be named “.<myapp>rc”
  8. DO NOT use multiple types of arguments with the the same name

License, Authors, Changelog