pythonrc is a drop-in rc-file parser augmenter for [docopt](http://docopt.org/).
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.
For the time being I will refer you to the somewhat complete inline documentation for each function in the package.
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.
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](docopt/docopt#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.
- 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
Read LICENSE, AUTHORS, CHANGELOG.rst