Mercurial > hg > configuration

annotate README.txt @ 87:928654373755

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
change default flow style for yaml, http://pyyaml.org/wiki/PyYAMLDocumentation
author Jeff Hammel <jhammel@mozilla.com>
date Fri, 27 Apr 2012 14:13:04 -0700
parents fe31a57ac577
children 66a4fe43b61f
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
0
Jeff Hammel <jhammel@mozilla.com>
parents:
diff changeset
1 configuration
72
c39ca7020da7 formatting
Jeff Hammel <jhammel@mozilla.com>
parents: 70
diff changeset
2 =============
0
Jeff Hammel <jhammel@mozilla.com>
parents:
diff changeset
3
16
b7e7f450ad1a why do we care about configuration files?
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
4 multi-level unified configuration for python consumption
b7e7f450ad1a why do we care about configuration files?
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
5
77
0f9f8f225e79 draft of README plus version bump
Jeff Hammel <jhammel@mozilla.com>
parents: 76
diff changeset
6 - you have a (python) program that wants to read configuration from
68
1025d283a570 start in on the README
Jeff Hammel <jhammel@mozilla.com>
parents: 16
diff changeset
7 configuration files (I currently support JSON and YAML) and also
1025d283a570 start in on the README
Jeff Hammel <jhammel@mozilla.com>
parents: 16
diff changeset
8 from the command line
77
0f9f8f225e79 draft of README plus version bump
Jeff Hammel <jhammel@mozilla.com>
parents: 76
diff changeset
9
0f9f8f225e79 draft of README plus version bump
Jeff Hammel <jhammel@mozilla.com>
parents: 76
diff changeset
10 - you want to be able to serialize and deserialize configuration
68
1025d283a570 start in on the README
Jeff Hammel <jhammel@mozilla.com>
parents: 16
diff changeset
11
72
c39ca7020da7 formatting
Jeff Hammel <jhammel@mozilla.com>
parents: 70
diff changeset
12
74
0516a9e0566b more README hacking
Jeff Hammel <jhammel@mozilla.com>
parents: 73
diff changeset
13 Basic Usage
0516a9e0566b more README hacking
Jeff Hammel <jhammel@mozilla.com>
parents: 73
diff changeset
14 -----------
16
b7e7f450ad1a why do we care about configuration files?
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
15
77
0f9f8f225e79 draft of README plus version bump
Jeff Hammel <jhammel@mozilla.com>
parents: 76
diff changeset
16 The ``configuration.Configuration`` class is an abstract base
68
1025d283a570 start in on the README
Jeff Hammel <jhammel@mozilla.com>
parents: 16
diff changeset
17 class that extends ``optparse.OptionParser``. The form of the
1025d283a570 start in on the README
Jeff Hammel <jhammel@mozilla.com>
parents: 16
diff changeset
18 configuration is dictated by setting the ``options`` attribute on your
1025d283a570 start in on the README
Jeff Hammel <jhammel@mozilla.com>
parents: 16
diff changeset
19 subclass. ``options`` is a dictionary of the form::
1025d283a570 start in on the README
Jeff Hammel <jhammel@mozilla.com>
parents: 16
diff changeset
20
1025d283a570 start in on the README
Jeff Hammel <jhammel@mozilla.com>
parents: 16
diff changeset
21 {'name': {<value>}}
1025d283a570 start in on the README
Jeff Hammel <jhammel@mozilla.com>
parents: 16
diff changeset
22
1025d283a570 start in on the README
Jeff Hammel <jhammel@mozilla.com>
parents: 16
diff changeset
23 ``name`` is the name of the configuration option, and ``value`` is a
1025d283a570 start in on the README
Jeff Hammel <jhammel@mozilla.com>
parents: 16
diff changeset
24 ``dict`` that gives the form of the option.
1025d283a570 start in on the README
Jeff Hammel <jhammel@mozilla.com>
parents: 16
diff changeset
25
70
451aeb35ec04 outline what options are available for ``value``
Jeff Hammel <jhammel@mozilla.com>
parents: 68
diff changeset
26 ``Configuration`` transforms these options into ``OptionParser`` options.
451aeb35ec04 outline what options are available for ``value``
Jeff Hammel <jhammel@mozilla.com>
parents: 68
diff changeset
27
451aeb35ec04 outline what options are available for ``value``
Jeff Hammel <jhammel@mozilla.com>
parents: 68
diff changeset
28 Options for ``value`` include:
451aeb35ec04 outline what options are available for ``value``
Jeff Hammel <jhammel@mozilla.com>
parents: 68
diff changeset
29
451aeb35ec04 outline what options are available for ``value``
Jeff Hammel <jhammel@mozilla.com>
parents: 68
diff changeset
30 * help : what the option is about (translated to command line help)
451aeb35ec04 outline what options are available for ``value``
Jeff Hammel <jhammel@mozilla.com>
parents: 68
diff changeset
31 * default: default value for the option
451aeb35ec04 outline what options are available for ``value``
Jeff Hammel <jhammel@mozilla.com>
parents: 68
diff changeset
32 * required: if a true value, this option must be present in the
451aeb35ec04 outline what options are available for ``value``
Jeff Hammel <jhammel@mozilla.com>
parents: 68
diff changeset
33 configuration. If ``required`` is a string, it will be displayed if
451aeb35ec04 outline what options are available for ``value``
Jeff Hammel <jhammel@mozilla.com>
parents: 68
diff changeset
34 the option is not present. If the default is defined, you won't
451aeb35ec04 outline what options are available for ``value``
Jeff Hammel <jhammel@mozilla.com>
parents: 68
diff changeset
35 need required as the default value will be used
451aeb35ec04 outline what options are available for ``value``
Jeff Hammel <jhammel@mozilla.com>
parents: 68
diff changeset
36 * type: type of the option. Used to control the parsing of the option
451aeb35ec04 outline what options are available for ``value``
Jeff Hammel <jhammel@mozilla.com>
parents: 68
diff changeset
37 * flags: a list that, if present, will be used for the command line
451aeb35ec04 outline what options are available for ``value``
Jeff Hammel <jhammel@mozilla.com>
parents: 68
diff changeset
38 flags. Othwise, the option name prepended by ``--`` will be used.
451aeb35ec04 outline what options are available for ``value``
Jeff Hammel <jhammel@mozilla.com>
parents: 68
diff changeset
39 To disable as a command line option, use an empty list ``[]``
451aeb35ec04 outline what options are available for ``value``
Jeff Hammel <jhammel@mozilla.com>
parents: 68
diff changeset
40
451aeb35ec04 outline what options are available for ``value``
Jeff Hammel <jhammel@mozilla.com>
parents: 68
diff changeset
41 In addition, you may extend ``Configuration`` and have additional
451aeb35ec04 outline what options are available for ``value``
Jeff Hammel <jhammel@mozilla.com>
parents: 68
diff changeset
42 useful items in the ``value`` dict for ``options``.
68
1025d283a570 start in on the README
Jeff Hammel <jhammel@mozilla.com>
parents: 16
diff changeset
43
1025d283a570 start in on the README
Jeff Hammel <jhammel@mozilla.com>
parents: 16
diff changeset
44 For an example, see
1025d283a570 start in on the README
Jeff Hammel <jhammel@mozilla.com>
parents: 16
diff changeset
45 http://k0s.org/mozilla/hg/configuration/file/c831eb58fb52/tests/example.py#l7
16
b7e7f450ad1a why do we care about configuration files?
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
46
b7e7f450ad1a why do we care about configuration files?
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
47
b7e7f450ad1a why do we care about configuration files?
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
48 Configuration Files
b7e7f450ad1a why do we care about configuration files?
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
49 -------------------
b7e7f450ad1a why do we care about configuration files?
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
50
b7e7f450ad1a why do we care about configuration files?
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
51 Config files are useful for (IMHO) A. complicated setup;
77
0f9f8f225e79 draft of README plus version bump
Jeff Hammel <jhammel@mozilla.com>
parents: 76
diff changeset
52 B. reproducibility; C. being able to share run time configurations.
0f9f8f225e79 draft of README plus version bump
Jeff Hammel <jhammel@mozilla.com>
parents: 76
diff changeset
53 The latter is mostly useful if the configuration contains nothing
16
b7e7f450ad1a why do we care about configuration files?
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
54 machine-specific (e.g. the path to an executable might vary from
b7e7f450ad1a why do we care about configuration files?
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
55 machine to machine) or if the configuration is overridable from the
b7e7f450ad1a why do we care about configuration files?
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
56 command line.
0
Jeff Hammel <jhammel@mozilla.com>
parents:
diff changeset
57
74
0516a9e0566b more README hacking
Jeff Hammel <jhammel@mozilla.com>
parents: 73
diff changeset
58 ``configuration`` features the ability to serialize (dump) and deserialize
0516a9e0566b more README hacking
Jeff Hammel <jhammel@mozilla.com>
parents: 73
diff changeset
59 (load) configuration from a pluggable set of formats. By default,
0516a9e0566b more README hacking
Jeff Hammel <jhammel@mozilla.com>
parents: 73
diff changeset
60 ``--dump <filename>`` will dump the resultant configuration (that
0516a9e0566b more README hacking
Jeff Hammel <jhammel@mozilla.com>
parents: 73
diff changeset
61 gathered from the command line options and loaded configuration files)
0516a9e0566b more README hacking
Jeff Hammel <jhammel@mozilla.com>
parents: 73
diff changeset
62 to a file of format dictate by the file extension (Example:
0516a9e0566b more README hacking
Jeff Hammel <jhammel@mozilla.com>
parents: 73
diff changeset
63 ``--dump mydumpfile.json`` will use JSON format). The flag for the
0516a9e0566b more README hacking
Jeff Hammel <jhammel@mozilla.com>
parents: 73
diff changeset
64 option, e.g. ``--dump``, may be set via the ``dump`` parameter to
0516a9e0566b more README hacking
Jeff Hammel <jhammel@mozilla.com>
parents: 73
diff changeset
65 ``Configuration``'s constructor.
0516a9e0566b more README hacking
Jeff Hammel <jhammel@mozilla.com>
parents: 73
diff changeset
66
0516a9e0566b more README hacking
Jeff Hammel <jhammel@mozilla.com>
parents: 73
diff changeset
67 ``Configuration`` instances can also deserialize data. The normal case of
0516a9e0566b more README hacking
Jeff Hammel <jhammel@mozilla.com>
parents: 73
diff changeset
68 using configuration is when you want to be able to read from
0516a9e0566b more README hacking
Jeff Hammel <jhammel@mozilla.com>
parents: 73
diff changeset
69 configuration files. By default, ``Configuration`` instances read
76
6667e79ffcb3 note load option
Jeff Hammel <jhammel@mozilla.com>
parents: 74
diff changeset
70 positional arguments for configuration files to be loaded. If you
6667e79ffcb3 note load option
Jeff Hammel <jhammel@mozilla.com>
parents: 74
diff changeset
71 specify a ``load`` argument to the ``Configuration`` constructor, this
77
0f9f8f225e79 draft of README plus version bump
Jeff Hammel <jhammel@mozilla.com>
parents: 76
diff changeset
72 option will be used instead. Likewise, the file extension will be
0f9f8f225e79 draft of README plus version bump
Jeff Hammel <jhammel@mozilla.com>
parents: 76
diff changeset
73 used to determine the format.
73
79f2d70ed5e5 a little about serializers
Jeff Hammel <jhammel@mozilla.com>
parents: 72
diff changeset
74
79f2d70ed5e5 a little about serializers
Jeff Hammel <jhammel@mozilla.com>
parents: 72
diff changeset
75 The `configuration package <http://pypi.python.org/pypi/configuration>`_
79f2d70ed5e5 a little about serializers
Jeff Hammel <jhammel@mozilla.com>
parents: 72
diff changeset
76 requires ``json``(``simplejson`` on older python) and ``PyYAML`` so
79f2d70ed5e5 a little about serializers
Jeff Hammel <jhammel@mozilla.com>
parents: 72
diff changeset
77 these serializers/deserializers are available if you install the package.
79f2d70ed5e5 a little about serializers
Jeff Hammel <jhammel@mozilla.com>
parents: 72
diff changeset
78
74
0516a9e0566b more README hacking
Jeff Hammel <jhammel@mozilla.com>
parents: 73
diff changeset
79
0516a9e0566b more README hacking
Jeff Hammel <jhammel@mozilla.com>
parents: 73
diff changeset
80 Extending Configuration
0516a9e0566b more README hacking
Jeff Hammel <jhammel@mozilla.com>
parents: 73
diff changeset
81 -----------------------
0516a9e0566b more README hacking
Jeff Hammel <jhammel@mozilla.com>
parents: 73
diff changeset
82
77
0f9f8f225e79 draft of README plus version bump
Jeff Hammel <jhammel@mozilla.com>
parents: 76
diff changeset
83 ``configuration`` is designed to be pluggable. While you get a useful
0f9f8f225e79 draft of README plus version bump
Jeff Hammel <jhammel@mozilla.com>
parents: 76
diff changeset
84 set of behaviour out of the box, most of the handlers for
0f9f8f225e79 draft of README plus version bump
Jeff Hammel <jhammel@mozilla.com>
parents: 76
diff changeset
85 ``configuration`` may be manipulated to do what you want to do.
0f9f8f225e79 draft of README plus version bump
Jeff Hammel <jhammel@mozilla.com>
parents: 76
diff changeset
86
0f9f8f225e79 draft of README plus version bump
Jeff Hammel <jhammel@mozilla.com>
parents: 76
diff changeset
87 ``Configuration``'s constructor takes an argument, ``types``, which is
0f9f8f225e79 draft of README plus version bump
Jeff Hammel <jhammel@mozilla.com>
parents: 76
diff changeset
88 a dictionary of callables keyed on type that translate
0f9f8f225e79 draft of README plus version bump
Jeff Hammel <jhammel@mozilla.com>
parents: 76
diff changeset
89 ``Configuration.options`` into ``optparse`` options. If one of
0f9f8f225e79 draft of README plus version bump
Jeff Hammel <jhammel@mozilla.com>
parents: 76
diff changeset
90 ``Configuration.options`` type isn't specified (or is ``None``), then
0f9f8f225e79 draft of README plus version bump
Jeff Hammel <jhammel@mozilla.com>
parents: 76
diff changeset
91 the default is used (``configuration.base_cli`` unless you override this).
0f9f8f225e79 draft of README plus version bump
Jeff Hammel <jhammel@mozilla.com>
parents: 76
diff changeset
92 If not passed, a ``Configuration`` instance uses ``configuration.types``.
0f9f8f225e79 draft of README plus version bump
Jeff Hammel <jhammel@mozilla.com>
parents: 76
diff changeset
93
0f9f8f225e79 draft of README plus version bump
Jeff Hammel <jhammel@mozilla.com>
parents: 76
diff changeset
94 The callables in ``types`` should take the option name and value
0f9f8f225e79 draft of README plus version bump
Jeff Hammel <jhammel@mozilla.com>
parents: 76
diff changeset
95 dictionary and should return the args and keyword args necessary to
0f9f8f225e79 draft of README plus version bump
Jeff Hammel <jhammel@mozilla.com>
parents: 76
diff changeset
96 instantiate an ``optparse.Option``.
0f9f8f225e79 draft of README plus version bump
Jeff Hammel <jhammel@mozilla.com>
parents: 76
diff changeset
97
0f9f8f225e79 draft of README plus version bump
Jeff Hammel <jhammel@mozilla.com>
parents: 76
diff changeset
98 ``Configuration``'s constructor also accepts an option,
0f9f8f225e79 draft of README plus version bump
Jeff Hammel <jhammel@mozilla.com>
parents: 76
diff changeset
99 ``configuration_providers``, that is a list of
0f9f8f225e79 draft of README plus version bump
Jeff Hammel <jhammel@mozilla.com>
parents: 76
diff changeset
100 serializers/deserializers to use. These should be objects with a list
0f9f8f225e79 draft of README plus version bump
Jeff Hammel <jhammel@mozilla.com>
parents: 76
diff changeset
101 of ``extensions`` to use, a ``read(filename)`` method that will load
0f9f8f225e79 draft of README plus version bump
Jeff Hammel <jhammel@mozilla.com>
parents: 76
diff changeset
102 configuration, and a ``write(config, filename)`` method to write it.
0f9f8f225e79 draft of README plus version bump
Jeff Hammel <jhammel@mozilla.com>
parents: 76
diff changeset
103 ``read`` should return the read configuration.
0f9f8f225e79 draft of README plus version bump
Jeff Hammel <jhammel@mozilla.com>
parents: 76
diff changeset
104 If ``write`` is not present the provider cannot serialize.
0f9f8f225e79 draft of README plus version bump
Jeff Hammel <jhammel@mozilla.com>
parents: 76
diff changeset
105
79
fe31a57ac577 note TODO
Jeff Hammel <jhammel@mozilla.com>
parents: 77
diff changeset
106 TODO
fe31a57ac577 note TODO
Jeff Hammel <jhammel@mozilla.com>
parents: 77
diff changeset
107 ----
fe31a57ac577 note TODO
Jeff Hammel <jhammel@mozilla.com>
parents: 77
diff changeset
108
fe31a57ac577 note TODO
Jeff Hammel <jhammel@mozilla.com>
parents: 77
diff changeset
109 * Add http://k0s.org/hg/ConfigOptionParser and deprecate it
fe31a57ac577 note TODO
Jeff Hammel <jhammel@mozilla.com>
parents: 77
diff changeset
110
0
Jeff Hammel <jhammel@mozilla.com>
parents:
diff changeset
111 ----
Jeff Hammel <jhammel@mozilla.com>
parents:
diff changeset
112
Jeff Hammel <jhammel@mozilla.com>
parents:
diff changeset
113 Jeff Hammel
Jeff Hammel <jhammel@mozilla.com>
parents:
diff changeset
114
Jeff Hammel <jhammel@mozilla.com>
parents:
diff changeset
115 http://k0s.org/mozilla/hg/configuration