This is a pre-production deployment of Warehouse, however changes made here WILL affect the production instance of PyPI.
Latest Version Dependencies status unknown Test status unknown Test coverage unknown
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

Release History


This version

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

Supported By

WebFaction WebFaction Technical Writing 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 Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting