Mercurial > hg > configuration
changeset 77:0f9f8f225e79
draft of README plus version bump
| author | Jeff Hammel <jhammel@mozilla.com> |
|---|---|
| date | Wed, 28 Mar 2012 15:24:25 -0700 |
| parents | 6667e79ffcb3 |
| children | 348451576d84 |
| files | README.txt setup.py |
| diffstat | 2 files changed, 32 insertions(+), 7 deletions(-) [+] |
line wrap: on
line diff
--- a/README.txt Wed Mar 28 14:08:11 2012 -0700 +++ b/README.txt Wed Mar 28 15:24:25 2012 -0700 @@ -3,16 +3,17 @@ multi-level unified configuration for python consumption -- you have a (python) program that wants to read configuration from + - you have a (python) program that wants to read configuration from configuration files (I currently support JSON and YAML) and also from the command line -- you want to be able to serialize and deserialize configuration + + - you want to be able to serialize and deserialize configuration Basic Usage ----------- -The ``configuration.Configuration`` class implements an abstract base +The ``configuration.Configuration`` class is an abstract base class that extends ``optparse.OptionParser``. The form of the configuration is dictated by setting the ``options`` attribute on your subclass. ``options`` is a dictionary of the form:: @@ -48,8 +49,8 @@ ------------------- Config files are useful for (IMHO) A. complicated setup; -B. reproducibility; C. being able to share run time configurations -The latter is only useful if the configuration contains nothing +B. reproducibility; C. being able to share run time configurations. +The latter is mostly useful if the configuration contains nothing machine-specific (e.g. the path to an executable might vary from machine to machine) or if the configuration is overridable from the command line. @@ -68,7 +69,8 @@ configuration files. By default, ``Configuration`` instances read positional arguments for configuration files to be loaded. If you specify a ``load`` argument to the ``Configuration`` constructor, this -option will be used instead. +option will be used instead. Likewise, the file extension will be +used to determine the format. The `configuration package <http://pypi.python.org/pypi/configuration>`_ requires ``json``(``simplejson`` on older python) and ``PyYAML`` so @@ -78,6 +80,29 @@ Extending Configuration ----------------------- +``configuration`` is designed to be pluggable. While you get a useful +set of behaviour out of the box, most of the handlers for +``configuration`` may be manipulated to do what you want to do. + +``Configuration``'s constructor takes an argument, ``types``, which is +a dictionary of callables keyed on type that translate +``Configuration.options`` into ``optparse`` options. If one of +``Configuration.options`` type isn't specified (or is ``None``), then +the default is used (``configuration.base_cli`` unless you override this). +If not passed, a ``Configuration`` instance uses ``configuration.types``. + +The callables in ``types`` should take the option name and value +dictionary and should return the args and keyword args necessary to +instantiate an ``optparse.Option``. + +``Configuration``'s constructor also accepts an option, +``configuration_providers``, that is a list of +serializers/deserializers to use. These should be objects with a list +of ``extensions`` to use, a ``read(filename)`` method that will load +configuration, and a ``write(config, filename)`` method to write it. +``read`` should return the read configuration. +If ``write`` is not present the provider cannot serialize. + ---- Jeff Hammel