pythonrc
pythonrc is a drop-in rc-file parser augmenter for [docopt](http://docopt.org/).
Quick User's Guide
These are the nessesary steps to use pythonrc:
- Install the package
$ pip install rc
- Import into your project
from docopt import docopt
import rc
import myscript
- Run docopt to parse the command line arguments
args = docopt(__doc__, version='MyScript {v}'.format(v=myscript.__version__))
- Set up your script level defaults (lowest priority)
defaults = {
'url': 'news.layervault.com',
'category': 'news',
'votes': 0
}
- 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.
Documentation
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:
- Boolean options (flags) become a major issue. There isn't any built in way to flag False and [probably won't be](https://github.com/docopt/docopt/issues/51) 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').
- 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.
- 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.
Checklist
- DOES support YAML and JSON file formats ("JSON is YAML")
- DOES convert docopt args to simpler versions by removing '--' and '<>'
- DO NOT define your own defaults in the document string
- DO define defaults in a separate dict
- DO NOT use boolean arguments (flags) you want to overwrite.
- DO use --option=<bool> where 'bool' is 'yes'/'no' in favor of flags
- DO expect config files to be named ".<myapp>rc"
- DO NOT use multiple types of arguments with the the same name
License, Authors, Changelog
Read LICENSE, AUTHORS, CHANGELOG.rst