Mercurial > hg > configuration

annotate README.txt @ 74:0516a9e0566b

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
more README hacking
author Jeff Hammel <jhammel@mozilla.com>
date Wed, 28 Mar 2012 12:42:58 -0700
parents 79f2d70ed5e5
children 6667e79ffcb3
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
68
1025d283a570 start in on the README
Jeff Hammel <jhammel@mozilla.com>
parents: 16
diff changeset
6 - you have a (python) program that wants to read configuration from
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
1025d283a570 start in on the README
Jeff Hammel <jhammel@mozilla.com>
parents: 16
diff changeset
9 - you want to be able to serialize and deserialize configuration
1025d283a570 start in on the README
Jeff Hammel <jhammel@mozilla.com>
parents: 16
diff changeset
10
72
c39ca7020da7 formatting
Jeff Hammel <jhammel@mozilla.com>
parents: 70
diff changeset
11
74
0516a9e0566b more README hacking
Jeff Hammel <jhammel@mozilla.com>
parents: 73
diff changeset
12 Basic Usage
0516a9e0566b more README hacking
Jeff Hammel <jhammel@mozilla.com>
parents: 73
diff changeset
13 -----------
16
b7e7f450ad1a why do we care about configuration files?
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
14
68
1025d283a570 start in on the README
Jeff Hammel <jhammel@mozilla.com>
parents: 16
diff changeset
15 The ``configuration.Configuration`` class implements an abstract base
1025d283a570 start in on the README
Jeff Hammel <jhammel@mozilla.com>
parents: 16
diff changeset
16 class that extends ``optparse.OptionParser``. The form of the
1025d283a570 start in on the README
Jeff Hammel <jhammel@mozilla.com>
parents: 16
diff changeset
17 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
18 subclass. ``options`` is a dictionary of the form::
1025d283a570 start in on the README
Jeff Hammel <jhammel@mozilla.com>
parents: 16
diff changeset
19
1025d283a570 start in on the README
Jeff Hammel <jhammel@mozilla.com>
parents: 16
diff changeset
20 {'name': {<value>}}
1025d283a570 start in on the README
Jeff Hammel <jhammel@mozilla.com>
parents: 16
diff changeset
21
1025d283a570 start in on the README
Jeff Hammel <jhammel@mozilla.com>
parents: 16
diff changeset
22 ``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
23 ``dict`` that gives the form of the option.
1025d283a570 start in on the README
Jeff Hammel <jhammel@mozilla.com>
parents: 16
diff changeset
24
70
451aeb35ec04 outline what options are available for ``value``
Jeff Hammel <jhammel@mozilla.com>
parents: 68
diff changeset
25 ``Configuration`` transforms these options into ``OptionParser`` options.
451aeb35ec04 outline what options are available for ``value``
Jeff Hammel <jhammel@mozilla.com>
parents: 68
diff changeset
26
451aeb35ec04 outline what options are available for ``value``
Jeff Hammel <jhammel@mozilla.com>
parents: 68
diff changeset
27 Options for ``value`` include:
451aeb35ec04 outline what options are available for ``value``
Jeff Hammel <jhammel@mozilla.com>
parents: 68
diff changeset
28
451aeb35ec04 outline what options are available for ``value``
Jeff Hammel <jhammel@mozilla.com>
parents: 68
diff changeset
29 * 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
30 * default: default value for the option
451aeb35ec04 outline what options are available for ``value``
Jeff Hammel <jhammel@mozilla.com>
parents: 68
diff changeset
31 * 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
32 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
33 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
34 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
35 * 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
36 * 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
37 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
38 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
39
451aeb35ec04 outline what options are available for ``value``
Jeff Hammel <jhammel@mozilla.com>
parents: 68
diff changeset
40 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
41 useful items in the ``value`` dict for ``options``.
68
1025d283a570 start in on the README
Jeff Hammel <jhammel@mozilla.com>
parents: 16
diff changeset
42
1025d283a570 start in on the README
Jeff Hammel <jhammel@mozilla.com>
parents: 16
diff changeset
43 For an example, see
1025d283a570 start in on the README
Jeff Hammel <jhammel@mozilla.com>
parents: 16
diff changeset
44 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
45
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 Configuration Files
b7e7f450ad1a why do we care about configuration files?
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
48 -------------------
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 Config files are useful for (IMHO) A. complicated setup;
b7e7f450ad1a why do we care about configuration files?
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
51 B. reproducibility; C. being able to share run time configurations
b7e7f450ad1a why do we care about configuration files?
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
52 The latter is only useful if the configuration contains nothing
b7e7f450ad1a why do we care about configuration files?
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
53 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
54 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
55 command line.
0
Jeff Hammel <jhammel@mozilla.com>
parents:
diff changeset
56
74
0516a9e0566b more README hacking
Jeff Hammel <jhammel@mozilla.com>
parents: 73
diff changeset
57 ``configuration`` features the ability to serialize (dump) and deserialize
0516a9e0566b more README hacking
Jeff Hammel <jhammel@mozilla.com>
parents: 73
diff changeset
58 (load) configuration from a pluggable set of formats. By default,
0516a9e0566b more README hacking
Jeff Hammel <jhammel@mozilla.com>
parents: 73
diff changeset
59 ``--dump <filename>`` will dump the resultant configuration (that
0516a9e0566b more README hacking
Jeff Hammel <jhammel@mozilla.com>
parents: 73
diff changeset
60 gathered from the command line options and loaded configuration files)
0516a9e0566b more README hacking
Jeff Hammel <jhammel@mozilla.com>
parents: 73
diff changeset
61 to a file of format dictate by the file extension (Example:
0516a9e0566b more README hacking
Jeff Hammel <jhammel@mozilla.com>
parents: 73
diff changeset
62 ``--dump mydumpfile.json`` will use JSON format). The flag for the
0516a9e0566b more README hacking
Jeff Hammel <jhammel@mozilla.com>
parents: 73
diff changeset
63 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
64 ``Configuration``'s constructor.
0516a9e0566b more README hacking
Jeff Hammel <jhammel@mozilla.com>
parents: 73
diff changeset
65
0516a9e0566b more README hacking
Jeff Hammel <jhammel@mozilla.com>
parents: 73
diff changeset
66 ``Configuration`` instances can also deserialize data. The normal case of
0516a9e0566b more README hacking
Jeff Hammel <jhammel@mozilla.com>
parents: 73
diff changeset
67 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
68 configuration files. By default, ``Configuration`` instances read
0516a9e0566b more README hacking
Jeff Hammel <jhammel@mozilla.com>
parents: 73
diff changeset
69 positional arguments for configuration files to be loaded.
73
79f2d70ed5e5 a little about serializers
Jeff Hammel <jhammel@mozilla.com>
parents: 72
diff changeset
70
79f2d70ed5e5 a little about serializers
Jeff Hammel <jhammel@mozilla.com>
parents: 72
diff changeset
71 The `configuration package <http://pypi.python.org/pypi/configuration>`_
79f2d70ed5e5 a little about serializers
Jeff Hammel <jhammel@mozilla.com>
parents: 72
diff changeset
72 requires ``json``(``simplejson`` on older python) and ``PyYAML`` so
79f2d70ed5e5 a little about serializers
Jeff Hammel <jhammel@mozilla.com>
parents: 72
diff changeset
73 these serializers/deserializers are available if you install the package.
79f2d70ed5e5 a little about serializers
Jeff Hammel <jhammel@mozilla.com>
parents: 72
diff changeset
74
74
0516a9e0566b more README hacking
Jeff Hammel <jhammel@mozilla.com>
parents: 73
diff changeset
75
0516a9e0566b more README hacking
Jeff Hammel <jhammel@mozilla.com>
parents: 73
diff changeset
76 Extending Configuration
0516a9e0566b more README hacking
Jeff Hammel <jhammel@mozilla.com>
parents: 73
diff changeset
77 -----------------------
0516a9e0566b more README hacking
Jeff Hammel <jhammel@mozilla.com>
parents: 73
diff changeset
78
0
Jeff Hammel <jhammel@mozilla.com>
parents:
diff changeset
79 ----
Jeff Hammel <jhammel@mozilla.com>
parents:
diff changeset
80
Jeff Hammel <jhammel@mozilla.com>
parents:
diff changeset
81 Jeff Hammel
Jeff Hammel <jhammel@mozilla.com>
parents:
diff changeset
82
Jeff Hammel <jhammel@mozilla.com>
parents:
diff changeset
83 http://k0s.org/mozilla/hg/configuration