# HG changeset patch
# User Jeff Hammel <jhammel@mozilla.com>
# Date 1332973465 25200
# Node ID 0f9f8f225e79093e59e21310e2159f0076727f51
# Parent  6667e79ffcb393829240d130ebf369ebe82d1b00
draft of README plus version bump

diff -r 6667e79ffcb3 -r 0f9f8f225e79 README.txt
--- 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
diff -r 6667e79ffcb3 -r 0f9f8f225e79 setup.py
--- a/setup.py	Wed Mar 28 14:08:11 2012 -0700
+++ b/setup.py	Wed Mar 28 15:24:25 2012 -0700
@@ -4,7 +4,7 @@
 
 import os
 
-version = "0.1"
+version = "0.1.1"
 dependencies = ['MakeItSo', 'PyYAML']
 
 try: