Mercurial > hg > configuration
comparison README.txt @ 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 | 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 |