Mercurial > hg > configuration

comparison README.txt @ 77:0f9f8f225e79

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
draft of README plus version bump
author Jeff Hammel <jhammel@mozilla.com>
date Wed, 28 Mar 2012 15:24:25 -0700
parents 6667e79ffcb3
children fe31a57ac577
comparison
equal deleted inserted replaced
76:6667e79ffcb3 77:0f9f8f225e79
1 configuration 1 configuration
2 ============= 2 =============
3 3
4 multi-level unified configuration for python consumption 4 multi-level unified configuration for python consumption
5 5
6 - you have a (python) program that wants to read configuration from 6 - you have a (python) program that wants to read configuration from
7 configuration files (I currently support JSON and YAML) and also 7 configuration files (I currently support JSON and YAML) and also
8 from the command line 8 from the command line
9 - you want to be able to serialize and deserialize configuration 9
10 - you want to be able to serialize and deserialize configuration
10 11
11 12
12 Basic Usage 13 Basic Usage
13 ----------- 14 -----------
14 15
15 The ``configuration.Configuration`` class implements an abstract base 16 The ``configuration.Configuration`` class is an abstract base
16 class that extends ``optparse.OptionParser``. The form of the 17 class that extends ``optparse.OptionParser``. The form of the
17 configuration is dictated by setting the ``options`` attribute on your 18 configuration is dictated by setting the ``options`` attribute on your
18 subclass. ``options`` is a dictionary of the form:: 19 subclass. ``options`` is a dictionary of the form::
19 20
20 {'name': {<value>}} 21 {'name': {<value>}}
46 47
47 Configuration Files 48 Configuration Files
48 ------------------- 49 -------------------
49 50
50 Config files are useful for (IMHO) A. complicated setup; 51 Config files are useful for (IMHO) A. complicated setup;
51 B. reproducibility; C. being able to share run time configurations 52 B. reproducibility; C. being able to share run time configurations.
52 The latter is only useful if the configuration contains nothing 53 The latter is mostly useful if the configuration contains nothing
53 machine-specific (e.g. the path to an executable might vary from 54 machine-specific (e.g. the path to an executable might vary from
54 machine to machine) or if the configuration is overridable from the 55 machine to machine) or if the configuration is overridable from the
55 command line. 56 command line.
56 57
57 ``configuration`` features the ability to serialize (dump) and deserialize 58 ``configuration`` features the ability to serialize (dump) and deserialize
66 ``Configuration`` instances can also deserialize data. The normal case of 67 ``Configuration`` instances can also deserialize data. The normal case of
67 using configuration is when you want to be able to read from 68 using configuration is when you want to be able to read from
68 configuration files. By default, ``Configuration`` instances read 69 configuration files. By default, ``Configuration`` instances read
69 positional arguments for configuration files to be loaded. If you 70 positional arguments for configuration files to be loaded. If you
70 specify a ``load`` argument to the ``Configuration`` constructor, this 71 specify a ``load`` argument to the ``Configuration`` constructor, this
71 option will be used instead. 72 option will be used instead. Likewise, the file extension will be
73 used to determine the format.
72 74
73 The `configuration package <http://pypi.python.org/pypi/configuration>`_ 75 The `configuration package <http://pypi.python.org/pypi/configuration>`_
74 requires ``json``(``simplejson`` on older python) and ``PyYAML`` so 76 requires ``json``(``simplejson`` on older python) and ``PyYAML`` so
75 these serializers/deserializers are available if you install the package. 77 these serializers/deserializers are available if you install the package.
76 78
77 79
78 Extending Configuration 80 Extending Configuration
79 ----------------------- 81 -----------------------
80 82
83 ``configuration`` is designed to be pluggable. While you get a useful
84 set of behaviour out of the box, most of the handlers for
85 ``configuration`` may be manipulated to do what you want to do.
86
87 ``Configuration``'s constructor takes an argument, ``types``, which is
88 a dictionary of callables keyed on type that translate
89 ``Configuration.options`` into ``optparse`` options. If one of
90 ``Configuration.options`` type isn't specified (or is ``None``), then
91 the default is used (``configuration.base_cli`` unless you override this).
92 If not passed, a ``Configuration`` instance uses ``configuration.types``.
93
94 The callables in ``types`` should take the option name and value
95 dictionary and should return the args and keyword args necessary to
96 instantiate an ``optparse.Option``.
97
98 ``Configuration``'s constructor also accepts an option,
99 ``configuration_providers``, that is a list of
100 serializers/deserializers to use. These should be objects with a list
101 of ``extensions`` to use, a ``read(filename)`` method that will load
102 configuration, and a ``write(config, filename)`` method to write it.
103 ``read`` should return the read configuration.
104 If ``write`` is not present the provider cannot serialize.
105
81 ---- 106 ----
82 107
83 Jeff Hammel 108 Jeff Hammel
84 109
85 http://k0s.org/mozilla/hg/configuration 110 http://k0s.org/mozilla/hg/configuration