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

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

Project Description

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


Release History

This version
History Node


Supported By

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 Google Google Cloud Servers DreamHost DreamHost Log Hosting