Skip to main content

multi-level unified configuration

Project description

configuration
=============

multi-level unified configuration for python consumption

- 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


Basic Usage
-----------

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::

{'name': {<value>}}

``name`` is the name of the configuration option, and ``value`` is a
``dict`` that gives the form of the option.

``Configuration`` transforms these options into ``OptionParser`` options.

Options for ``value`` include:

* help : what the option is about (translated to command line help)
* default: default value for the option
* required: if a true value, this option must be present in the
configuration. If ``required`` is a string, it will be displayed if
the option is not present. If the default is defined, you won't
need required as the default value will be used
* type: type of the option. Used to control the parsing of the option
* flags: a list that, if present, will be used for the command line
flags. Othwise, the option name prepended by ``--`` will be used.
To disable as a command line option, use an empty list ``[]``

In addition, you may extend ``Configuration`` and have additional
useful items in the ``value`` dict for ``options``.

For an example, see
http://k0s.org/mozilla/hg/configuration/file/c831eb58fb52/tests/example.py#l7


Configuration Files
-------------------

Config files are useful for (IMHO) A. complicated setup;
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.

``configuration`` features the ability to serialize (dump) and deserialize
(load) configuration from a pluggable set of formats. By default,
``--dump <filename>`` will dump the resultant configuration (that
gathered from the command line options and loaded configuration files)
to a file of format dictate by the file extension (Example:
``--dump mydumpfile.json`` will use JSON format). The flag for the
option, e.g. ``--dump``, may be set via the ``dump`` parameter to
``Configuration``'s constructor.

``Configuration`` instances can also deserialize data. The normal case of
using configuration is when you want to be able to read from
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. 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
these serializers/deserializers are available if you install the package.


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.

TODO
----

* Add http://k0s.org/hg/ConfigOptionParser and deprecate it

----

Jeff Hammel

http://k0s.org/mozilla/hg/configuration

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

configuration-0.2.2.tar.gz (7.9 kB view hashes)

Uploaded Source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page